WPILibC++ 2024.3.1
NetworkTableEntry.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <stdint.h>
8
9#include <initializer_list>
10#include <memory>
11#include <span>
12#include <string>
13#include <string_view>
14#include <vector>
15
18#include "ntcore_c.h"
19#include "ntcore_cpp.h"
20
21namespace nt {
22
23class NetworkTableInstance;
24class Topic;
25
26/**
27 * NetworkTables Entry
28 *
29 * @note For backwards compatibility, the NetworkTableEntry destructor does not
30 * release the entry.
31 *
32 * @ingroup ntcore_cpp_api
33 */
34class NetworkTableEntry final {
35 public:
36 /**
37 * Flag values (as returned by GetFlags()).
38 * @deprecated Use IsPersistent() instead.
39 */
41
42 /**
43 * Construct invalid instance.
44 */
46
47 /**
48 * Construct from native handle.
49 *
50 * @param handle Native handle
51 */
52 explicit NetworkTableEntry(NT_Entry handle);
53
54 /**
55 * Determines if the native handle is valid.
56 *
57 * @return True if the native handle is valid, false otherwise.
58 */
59 explicit operator bool() const { return m_handle != 0; }
60
61 /**
62 * Gets the native handle for the entry.
63 *
64 * @return Native handle
65 */
66 NT_Entry GetHandle() const;
67
68 /**
69 * Gets the instance for the entry.
70 *
71 * @return Instance
72 */
74
75 /**
76 * Determines if the entry currently exists.
77 *
78 * @return True if the entry exists, false otherwise.
79 */
80 bool Exists() const;
81
82 /**
83 * Gets the name of the entry (the key).
84 *
85 * @return the entry's name
86 */
87 std::string GetName() const;
88
89 /**
90 * Gets the type of the entry.
91 *
92 * @return the entry's type
93 */
95
96 /**
97 * Returns the flags.
98 *
99 * @return the flags (bitmask)
100 * @deprecated Use IsPersistent() or topic properties instead
101 */
102 [[deprecated("Use IsPersistent() or topic properties instead")]]
103 unsigned int GetFlags() const;
104
105 /**
106 * Gets the last time the entry's value was changed.
107 *
108 * @return Entry last change time
109 */
110 int64_t GetLastChange() const;
111
112 /**
113 * Gets the entry's value. If the entry does not exist, returns an empty
114 * value.
115 *
116 * @return the entry's value or an empty value if it does not exist.
117 */
118 Value GetValue() const;
119
120 /**
121 * Gets the entry's value as a boolean. If the entry does not exist or is of
122 * different type, it will return the default value.
123 *
124 * @param defaultValue the value to be returned if no value is found
125 * @return the entry's value or the given default value
126 */
127 bool GetBoolean(bool defaultValue) const;
128
129 /**
130 * Gets the entry's value as a integer. If the entry does not exist or is of
131 * different type, it will return the default value.
132 *
133 * @param defaultValue the value to be returned if no value is found
134 * @return the entry's value or the given default value
135 */
136 int64_t GetInteger(int64_t defaultValue) const;
137
138 /**
139 * Gets the entry's value as a float. If the entry does not exist or is of
140 * different type, it will return the default value.
141 *
142 * @param defaultValue the value to be returned if no value is found
143 * @return the entry's value or the given default value
144 */
145 float GetFloat(float defaultValue) const;
146
147 /**
148 * Gets the entry's value as a double. If the entry does not exist or is of
149 * different type, it will return the default value.
150 *
151 * @param defaultValue the value to be returned if no value is found
152 * @return the entry's value or the given default value
153 */
154 double GetDouble(double defaultValue) const;
155
156 /**
157 * Gets the entry's value as a string. If the entry does not exist or is of
158 * different type, it will return the default value.
159 *
160 * @param defaultValue the value to be returned if no value is found
161 * @return the entry's value or the given default value
162 */
163 std::string GetString(std::string_view defaultValue) const;
164
165 /**
166 * Gets the entry's value as a raw. If the entry does not exist or is of
167 * different type, it will return the default value.
168 *
169 * @param defaultValue the value to be returned if no value is found
170 * @return the entry's value or the given default value
171 */
172 std::vector<uint8_t> GetRaw(std::span<const uint8_t> defaultValue) const;
173
174 /**
175 * Gets the entry's value as a boolean array. If the entry does not exist
176 * or is of different type, it will return the default value.
177 *
178 * @param defaultValue the value to be returned if no value is found
179 * @return the entry's value or the given default value
180 *
181 * @note This makes a copy of the array. If the overhead of this is a
182 * concern, use GetValue() instead.
183 *
184 * @note The returned array is std::vector<int> instead of std::vector<bool>
185 * because std::vector<bool> is special-cased in C++. 0 is false, any
186 * non-zero value is true.
187 */
188 std::vector<int> GetBooleanArray(std::span<const int> defaultValue) const;
189
190 /**
191 * Gets the entry's value as a integer array. If the entry does not exist
192 * or is of different type, it will return the default value.
193 *
194 * @param defaultValue the value to be returned if no value is found
195 * @return the entry's value or the given default value
196 *
197 * @note This makes a copy of the array. If the overhead of this is a
198 * concern, use GetValue() instead.
199 */
200 std::vector<int64_t> GetIntegerArray(
201 std::span<const int64_t> defaultValue) const;
202
203 /**
204 * Gets the entry's value as a float array. If the entry does not exist
205 * or is of different type, it will return the default value.
206 *
207 * @param defaultValue the value to be returned if no value is found
208 * @return the entry's value or the given default value
209 *
210 * @note This makes a copy of the array. If the overhead of this is a
211 * concern, use GetValue() instead.
212 */
213 std::vector<float> GetFloatArray(std::span<const float> defaultValue) const;
214
215 /**
216 * Gets the entry's value as a double array. If the entry does not exist
217 * or is of different type, it will return the default value.
218 *
219 * @param defaultValue the value to be returned if no value is found
220 * @return the entry's value or the given default value
221 *
222 * @note This makes a copy of the array. If the overhead of this is a
223 * concern, use GetValue() instead.
224 */
225 std::vector<double> GetDoubleArray(
226 std::span<const double> defaultValue) const;
227
228 /**
229 * Gets the entry's value as a string array. If the entry does not exist
230 * or is of different type, it will return the default value.
231 *
232 * @param defaultValue the value to be returned if no value is found
233 * @return the entry's value or the given default value
234 *
235 * @note This makes a copy of the array. If the overhead of this is a
236 * concern, use GetValue() instead.
237 */
238 std::vector<std::string> GetStringArray(
239 std::span<const std::string> defaultValue) const;
240
241 /**
242 * Get an array of all value changes since the last call to ReadQueue.
243 *
244 * The "poll storage" subscribe option can be used to set the queue depth.
245 *
246 * @return Array of values; empty array if no new changes have been
247 * published since the previous call.
248 */
249 std::vector<NetworkTableValue> ReadQueue();
250
251 /**
252 * Sets the entry's value if it does not exist.
253 *
254 * @param defaultValue the default value to set
255 * @return False if the entry exists with a different type
256 */
257 bool SetDefaultValue(const Value& defaultValue);
258
259 /**
260 * Sets the entry's value if it does not exist.
261 *
262 * @param defaultValue the default value to set
263 * @return False if the entry exists with a different type
264 */
265 bool SetDefaultBoolean(bool defaultValue);
266
267 /**
268 * Sets the entry's value if it does not exist.
269 *
270 * @param defaultValue the default value to set
271 * @return False if the entry exists with a different type
272 */
273 bool SetDefaultInteger(int64_t defaultValue);
274
275 /**
276 * Sets the entry's value if it does not exist.
277 *
278 * @param defaultValue the default value to set
279 * @return False if the entry exists with a different type
280 */
281 bool SetDefaultFloat(float defaultValue);
282
283 /**
284 * Sets the entry's value if it does not exist.
285 *
286 * @param defaultValue the default value to set
287 * @return False if the entry exists with a different type
288 */
289 bool SetDefaultDouble(double defaultValue);
290
291 /**
292 * Sets the entry's value if it does not exist.
293 *
294 * @param defaultValue the default value to set
295 * @return False if the entry exists with a different type
296 */
297 bool SetDefaultString(std::string_view defaultValue);
298
299 /**
300 * Sets the entry's value if it does not exist.
301 *
302 * @param defaultValue the default value to set
303 * @return False if the entry exists with a different type
304 */
305 bool SetDefaultRaw(std::span<const uint8_t> defaultValue);
306
307 /**
308 * Sets the entry's value if it does not exist.
309 *
310 * @param defaultValue the default value to set
311 * @return False if the entry exists with a different type
312 */
313 bool SetDefaultBooleanArray(std::span<const int> defaultValue);
314
315 /**
316 * Sets the entry's value if it does not exist.
317 *
318 * @param defaultValue the default value to set
319 * @return False if the entry exists with a different type
320 */
321 bool SetDefaultIntegerArray(std::span<const int64_t> defaultValue);
322
323 /**
324 * Sets the entry's value if it does not exist.
325 *
326 * @param defaultValue the default value to set
327 * @return False if the entry exists with a different type
328 */
329 bool SetDefaultFloatArray(std::span<const float> defaultValue);
330
331 /**
332 * Sets the entry's value if it does not exist.
333 *
334 * @param defaultValue the default value to set
335 * @return False if the entry exists with a different type
336 */
337 bool SetDefaultDoubleArray(std::span<const double> defaultValue);
338
339 /**
340 * Sets the entry's value if it does not exist.
341 *
342 * @param defaultValue the default value to set
343 * @return False if the entry exists with a different type
344 */
345 bool SetDefaultStringArray(std::span<const std::string> defaultValue);
346
347 /**
348 * Sets the entry's value.
349 *
350 * @param value the value to set
351 * @return False if the entry exists with a different type
352 */
353 bool SetValue(const Value& value);
354
355 /**
356 * Sets the entry's value.
357 *
358 * @param value the value to set
359 * @param time the timestamp to set (0 = nt::Now())
360 * @return False if the entry exists with a different type
361 */
362 bool SetBoolean(bool value, int64_t time = 0);
363
364 /**
365 * Sets the entry's value.
366 *
367 * @param value the value to set
368 * @param time the timestamp to set (0 = nt::Now())
369 * @return False if the entry exists with a different type
370 */
371 bool SetInteger(int64_t value, int64_t time = 0);
372
373 /**
374 * Sets the entry's value.
375 *
376 * @param value the value to set
377 * @param time the timestamp to set (0 = nt::Now())
378 * @return False if the entry exists with a different type
379 */
380 bool SetFloat(float value, int64_t time = 0);
381
382 /**
383 * Sets the entry's value.
384 *
385 * @param value the value to set
386 * @param time the timestamp to set (0 = nt::Now())
387 * @return False if the entry exists with a different type
388 */
389 bool SetDouble(double value, int64_t time = 0);
390
391 /**
392 * Sets the entry's value.
393 *
394 * @param value the value to set
395 * @param time the timestamp to set (0 = nt::Now())
396 * @return False if the entry exists with a different type
397 */
398 bool SetString(std::string_view value, int64_t time = 0);
399
400 /**
401 * Sets the entry's value.
402 *
403 * @param value the value to set
404 * @param time the timestamp to set (0 = nt::Now())
405 * @return False if the entry exists with a different type
406 */
407 bool SetRaw(std::span<const uint8_t> value, int64_t time = 0);
408
409 /**
410 * Sets the entry's value.
411 *
412 * @param value the value to set
413 * @param time the timestamp to set (0 = nt::Now())
414 * @return False if the entry exists with a different type
415 */
416 bool SetBooleanArray(std::span<const bool> value, int64_t time = 0);
417
418 /**
419 * Sets the entry's value.
420 *
421 * @param value the value to set
422 * @param time the timestamp to set (0 = nt::Now())
423 * @return False if the entry exists with a different type
424 */
425 bool SetBooleanArray(std::span<const int> value, int64_t time = 0);
426
427 /**
428 * Sets the entry's value.
429 *
430 * @param value the value to set
431 * @param time the timestamp to set (0 = nt::Now())
432 * @return False if the entry exists with a different type
433 */
434 bool SetIntegerArray(std::span<const int64_t> value, int64_t time = 0);
435
436 /**
437 * Sets the entry's value.
438 *
439 * @param value the value to set
440 * @param time the timestamp to set (0 = nt::Now())
441 * @return False if the entry exists with a different type
442 */
443 bool SetFloatArray(std::span<const float> value, int64_t time = 0);
444
445 /**
446 * Sets the entry's value.
447 *
448 * @param value the value to set
449 * @param time the timestamp to set (0 = nt::Now())
450 * @return False if the entry exists with a different type
451 */
452 bool SetDoubleArray(std::span<const double> value, int64_t time = 0);
453
454 /**
455 * Sets the entry's value.
456 *
457 * @param value the value to set
458 * @param time the timestamp to set (0 = nt::Now())
459 * @return False if the entry exists with a different type
460 */
461 bool SetStringArray(std::span<const std::string> value, int64_t time = 0);
462
463 /**
464 * Sets flags.
465 *
466 * @param flags the flags to set (bitmask)
467 * @deprecated Use SetPersistent() or topic properties instead
468 */
469 [[deprecated("Use SetPersistent() or topic properties instead")]]
470 void SetFlags(unsigned int flags);
471
472 /**
473 * Clears flags.
474 *
475 * @param flags the flags to clear (bitmask)
476 * @deprecated Use SetPersistent() or topic properties instead
477 */
478 [[deprecated("Use SetPersistent() or topic properties instead")]]
479 void ClearFlags(unsigned int flags);
480
481 /**
482 * Make value persistent through program restarts.
483 */
484 void SetPersistent();
485
486 /**
487 * Stop making value persistent through program restarts.
488 */
489 void ClearPersistent();
490
491 /**
492 * Returns whether the value is persistent through program restarts.
493 *
494 * @return True if the value is persistent.
495 */
496 bool IsPersistent() const;
497
498 /**
499 * Stops publishing the entry if it's been published.
500 */
501 void Unpublish();
502
503 /**
504 * Deletes the entry.
505 * @deprecated Use Unpublish() instead.
506 */
507 [[deprecated("Use Unpublish() instead")]]
508 void Delete();
509
510 /**
511 * Gets the entry's topic.
512 *
513 * @return Topic
514 */
516
517 /**
518 * Equality operator. Returns true if both instances refer to the same
519 * native handle.
520 */
521 bool operator==(const NetworkTableEntry&) const = default;
522
523 protected:
524 /* Native handle */
526};
527
528} // namespace nt
529
NetworkTables Entry.
Definition: NetworkTableEntry.h:34
NetworkTableType GetType() const
Gets the type of the entry.
Definition: NetworkTableEntry.inc:35
std::vector< int > GetBooleanArray(std::span< const int > defaultValue) const
Gets the entry's value as a boolean array.
Definition: NetworkTableEntry.inc:77
std::string GetName() const
Gets the name of the entry (the key).
Definition: NetworkTableEntry.inc:31
bool SetDouble(double value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:176
unsigned int GetFlags() const
Returns the flags.
Definition: NetworkTableEntry.inc:39
void Unpublish()
Stops publishing the entry if it's been published.
Definition: NetworkTableEntry.inc:239
std::vector< float > GetFloatArray(std::span< const float > defaultValue) const
Gets the entry's value as a float array.
Definition: NetworkTableEntry.inc:87
void ClearPersistent()
Stop making value persistent through program restarts.
Definition: NetworkTableEntry.inc:231
std::vector< std::string > GetStringArray(std::span< const std::string > defaultValue) const
Gets the entry's value as a string array.
Definition: NetworkTableEntry.inc:97
void SetPersistent()
Make value persistent through program restarts.
Definition: NetworkTableEntry.inc:227
bool SetString(std::string_view value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:180
void SetFlags(unsigned int flags)
Sets flags.
Definition: NetworkTableEntry.inc:219
float GetFloat(float defaultValue) const
Gets the entry's value as a float.
Definition: NetworkTableEntry.inc:59
bool SetDefaultValue(const Value &defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:106
Topic GetTopic() const
Gets the entry's topic.
bool SetDefaultFloat(float defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:118
bool SetBoolean(bool value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:164
int64_t GetLastChange() const
Gets the last time the entry's value was changed.
Definition: NetworkTableEntry.inc:43
bool SetDefaultFloatArray(std::span< const float > defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:145
std::vector< double > GetDoubleArray(std::span< const double > defaultValue) const
Gets the entry's value as a double array.
Definition: NetworkTableEntry.inc:92
bool SetDefaultRaw(std::span< const uint8_t > defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:130
bool IsPersistent() const
Returns whether the value is persistent through program restarts.
Definition: NetworkTableEntry.inc:235
void ClearFlags(unsigned int flags)
Clears flags.
Definition: NetworkTableEntry.inc:223
bool SetValue(const Value &value)
Sets the entry's value.
Definition: NetworkTableEntry.inc:160
bool SetDoubleArray(std::span< const double > value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:209
double GetDouble(double defaultValue) const
Gets the entry's value as a double.
Definition: NetworkTableEntry.inc:63
std::vector< uint8_t > GetRaw(std::span< const uint8_t > defaultValue) const
Gets the entry's value as a raw.
Definition: NetworkTableEntry.inc:72
bool SetDefaultString(std::string_view defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:126
bool SetFloatArray(std::span< const float > value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:204
bool SetInteger(int64_t value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:168
bool SetFloat(float value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:172
int64_t GetInteger(int64_t defaultValue) const
Gets the entry's value as a integer.
Definition: NetworkTableEntry.inc:55
bool Exists() const
Determines if the entry currently exists.
Definition: NetworkTableEntry.inc:27
void Delete()
Deletes the entry.
Definition: NetworkTableEntry.inc:243
bool SetDefaultDouble(double defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:122
bool SetDefaultDoubleArray(std::span< const double > defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:150
Value GetValue() const
Gets the entry's value.
Definition: NetworkTableEntry.inc:47
NetworkTableInstance GetInstance() const
Gets the instance for the entry.
bool SetDefaultBooleanArray(std::span< const int > defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:135
std::vector< NetworkTableValue > ReadQueue()
Get an array of all value changes since the last call to ReadQueue.
Definition: NetworkTableEntry.inc:102
bool operator==(const NetworkTableEntry &) const =default
Equality operator.
NT_Entry m_handle
Definition: NetworkTableEntry.h:525
bool SetRaw(std::span< const uint8_t > value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:184
NT_Entry GetHandle() const
Gets the native handle for the entry.
Definition: NetworkTableEntry.inc:23
bool GetBoolean(bool defaultValue) const
Gets the entry's value as a boolean.
Definition: NetworkTableEntry.inc:51
std::vector< int64_t > GetIntegerArray(std::span< const int64_t > defaultValue) const
Gets the entry's value as a integer array.
Definition: NetworkTableEntry.inc:82
bool SetDefaultBoolean(bool defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:110
Flags
Flag values (as returned by GetFlags()).
Definition: NetworkTableEntry.h:40
@ kPersistent
Definition: NetworkTableEntry.h:40
bool SetBooleanArray(std::span< const bool > value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:189
NetworkTableEntry()
Construct invalid instance.
Definition: NetworkTableEntry.inc:18
bool SetStringArray(std::span< const std::string > value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:214
bool SetDefaultStringArray(std::span< const std::string > defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:155
std::string GetString(std::string_view defaultValue) const
Gets the entry's value as a string.
Definition: NetworkTableEntry.inc:67
bool SetDefaultIntegerArray(std::span< const int64_t > defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:140
bool SetDefaultInteger(int64_t defaultValue)
Sets the entry's value if it does not exist.
Definition: NetworkTableEntry.inc:114
bool SetIntegerArray(std::span< const int64_t > value, int64_t time=0)
Sets the entry's value.
Definition: NetworkTableEntry.inc:199
NetworkTables Instance.
Definition: NetworkTableInstance.h:70
NetworkTables Topic.
Definition: Topic.h:28
A network table entry value.
Definition: NetworkTableValue.h:32
basic_string_view< char > string_view
Definition: core.h:501
NT_Handle NT_Entry
Definition: ntcore_c.h:35
@ NT_PERSISTENT
Definition: ntcore_c.h:69
NetworkTableType
NetworkTable entry type.
Definition: NetworkTableType.h:15
NetworkTables (ntcore) namespace.
Definition: ntcore_cpp.h:36