Set key-value pair in object.
More...
|
| #define | lite3_set_null(buf, inout_buflen, ofs, bufsz, key) |
| | Set null in object.
|
| |
| #define | lite3_set_bool(buf, inout_buflen, ofs, bufsz, key, value) |
| | Set boolean in object.
|
| |
| #define | lite3_set_i64(buf, inout_buflen, ofs, bufsz, key, value) |
| | Set integer in object.
|
| |
| #define | lite3_set_f64(buf, inout_buflen, ofs, bufsz, key, value) |
| | Set floating point in object.
|
| |
| #define | lite3_set_bytes(buf, inout_buflen, ofs, bufsz, key, bytes, bytes_len) |
| | Set bytes in object.
|
| |
| #define | lite3_set_str(buf, inout_buflen, ofs, bufsz, key, str) |
| | Set string in object.
|
| |
| #define | lite3_set_str_n(buf, inout_buflen, ofs, bufsz, key, str, str_len) |
| | Set string in object by length.
|
| |
| #define | lite3_set_obj(buf, inout_buflen, ofs, bufsz, key, out_ofs) |
| | Set object in object.
|
| |
| #define | lite3_set_arr(buf, inout_buflen, ofs, bufsz, key, out_ofs) |
| | Set array in object.
|
| |
Set key-value pair in object.
An empty buffer must first be initialized using lite3_init_obj() or lite3_init_arr() before insertion. See Object / Array Initialization.
Set functions read *inout_buflen to know the currently used portion of the buffer. After modifications, the new length will be written back. The caller must provide sufficient buffer space via bufsz or the call will fail and set errno to ENOBUFS. Retrying is up to the caller.
The number of bytes written to *buf never exceeds bufsz.
The ofs (offset) field is used to target an object or array inside the Lite³ buffer. To target the root-level object/array, use ofs == 0.
- Returns
- Returns 0 on success
- Returns < 0 on error
- Note
- Inserting a value with an existing key will override the current value.
- Warning
- Insertions, like any other buffer mutations, are not thread-safe. The caller must manually synchronize access to the buffer.
- A failed call with return value < 0 can still write to the buffer and increase
*inout_buflen.
- Overriding any value with an existing key can still grow the buffer and increase
*inout_buflen.
- Overriding a variable-length value (string/bytes) will require extra buffer space if the new value is larger than the old. The overridden space is never recovered, causing buffer size to grow indefinitely.
◆ lite3_set_arr
| #define lite3_set_arr |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
out_ofs |
|
) |
| |
Set array in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [out] | out_ofs | (size_t *) offset of the newly inserted array (if not needed, pass NULL) |
- Returns
- 0 on success
-
< 0 on error
Definition at line 1100 of file lite3.h.
◆ lite3_set_bool
| #define lite3_set_bool |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
value |
|
) |
| |
Set boolean in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [in] | value | (bool) boolean value to set |
- Returns
- 0 on success
-
< 0 on error
Definition at line 852 of file lite3.h.
◆ lite3_set_bytes
| #define lite3_set_bytes |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
bytes, |
|
|
|
bytes_len |
|
) |
| |
Set bytes in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [in] | bytes | (const unsigned char *) bytes pointer |
| [in] | bytes_len | (size_t) bytes amount |
- Returns
- 0 on success
-
< 0 on error
Definition at line 949 of file lite3.h.
◆ lite3_set_f64
| #define lite3_set_f64 |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
value |
|
) |
| |
Set floating point in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [in] | value | (double) floating point value to set |
- Returns
- 0 on success
-
< 0 on error
Definition at line 916 of file lite3.h.
◆ lite3_set_i64
| #define lite3_set_i64 |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
value |
|
) |
| |
Set integer in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [in] | value | (uint64_t) integer value to set |
- Returns
- 0 on success
-
< 0 on error
Definition at line 884 of file lite3.h.
◆ lite3_set_null
| #define lite3_set_null |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key |
|
) |
| |
Set null in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
- Returns
- 0 on success
-
< 0 on error
Definition at line 821 of file lite3.h.
◆ lite3_set_obj
| #define lite3_set_obj |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
out_ofs |
|
) |
| |
Set object in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [out] | out_ofs | (size_t *) offset of the newly inserted object (if not needed, pass NULL) |
- Returns
- 0 on success
-
< 0 on error
Definition at line 1059 of file lite3.h.
◆ lite3_set_str
| #define lite3_set_str |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
str |
|
) |
| |
Set string in object.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [in] | str | (const char *) string pointer |
- Returns
- 0 on success
-
< 0 on error
- Note
- This function must call
strlen() to learn the size of the string. If you know the length beforehand, it is more efficient to call lite3_set_str_n().
Definition at line 986 of file lite3.h.
◆ lite3_set_str_n
| #define lite3_set_str_n |
( |
|
buf, |
|
|
|
inout_buflen, |
|
|
|
ofs, |
|
|
|
bufsz, |
|
|
|
key, |
|
|
|
str, |
|
|
|
str_len |
|
) |
| |
Set string in object by length.
- Parameters
-
| [in] | buf | (unsigned char *) buffer pointer |
| [in,out] | inout_buflen | (size_t *) buffer used length |
| [in] | ofs | (size_t) start offset (0 == root) |
| [in] | bufsz | (size_t) buffer max size |
| [in] | key | (const char *) key |
| [in] | str | (const char *) string pointer |
| [in] | str_len | (size_t) string length, exclusive of NULL-terminator. |
- Returns
- 0 on success
-
< 0 on error
- Warning
str_len is exclusive of the NULL-terminator.
Definition at line 1024 of file lite3.h.