Lite³
A JSON-Compatible Zero-Copy Serialization Format
Loading...
Searching...
No Matches
Macros
Object Set
Context API

Set key-value pair in object. More...

Macros

#define lite3_ctx_set_null(ctx, ofs, key)
 Set null in object.
 
#define lite3_ctx_set_bool(ctx, ofs, key, value)
 Set boolean in object.
 
#define lite3_ctx_set_i64(ctx, ofs, key, value)
 Set integer in object.
 
#define lite3_ctx_set_f64(ctx, ofs, key, value)
 Set floating point in object.
 
#define lite3_ctx_set_bytes(ctx, ofs, key, bytes, bytes_len)
 Set bytes in object.
 
#define lite3_ctx_set_str(ctx, ofs, key, str)
 Set string in object.
 
#define lite3_ctx_set_str_n(ctx, ofs, key, str, str_len)
 Set string in object by length.
 
#define lite3_ctx_set_obj(ctx, ofs, key, out_ofs)
 Set object in object.
 
#define lite3_ctx_set_arr(ctx, ofs, key, out_ofs)
 Set array in object.
 

Detailed Description

Set key-value pair in object.

An empty buffer must first be initialized using lite3_ctx_init_obj() or lite3_ctx_init_arr() before insertion. See Object / Array Initialization.

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
  1. Insertions, like any other buffer mutations, are not thread-safe. The caller must manually synchronize access to the buffer.
  2. A failed call with return value < 0 can still write to the buffer and increase message size.
  3. Overriding any value with an existing key can still grow the buffer and increase message size.
  4. 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.

Macro Definition Documentation

◆ lite3_ctx_set_arr

#define lite3_ctx_set_arr (   ctx,
  ofs,
  key,
  out_ofs 
)

Set array in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[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 637 of file lite3_context_api.h.

◆ lite3_ctx_set_bool

#define lite3_ctx_set_bool (   ctx,
  ofs,
  key,
  value 
)

Set boolean in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[in]key(const char *) key
[in]value(bool) boolean value to set
Returns
0 on success
< 0 on error

Definition at line 365 of file lite3_context_api.h.

◆ lite3_ctx_set_bytes

#define lite3_ctx_set_bytes (   ctx,
  ofs,
  key,
  bytes,
  bytes_len 
)

Set bytes in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[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 474 of file lite3_context_api.h.

◆ lite3_ctx_set_f64

#define lite3_ctx_set_f64 (   ctx,
  ofs,
  key,
  value 
)

Set floating point in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[in]key(const char *) key
[in]value(double) floating point value to set
Returns
0 on success
< 0 on error

Definition at line 437 of file lite3_context_api.h.

◆ lite3_ctx_set_i64

#define lite3_ctx_set_i64 (   ctx,
  ofs,
  key,
  value 
)

Set integer in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[in]key(const char *) key
[in]value(uint64_t) integer value to set
Returns
0 on success
< 0 on error

Definition at line 401 of file lite3_context_api.h.

◆ lite3_ctx_set_null

#define lite3_ctx_set_null (   ctx,
  ofs,
  key 
)

Set null in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[in]key(const char *) key
Returns
0 on success
< 0 on error

Definition at line 330 of file lite3_context_api.h.

◆ lite3_ctx_set_obj

#define lite3_ctx_set_obj (   ctx,
  ofs,
  key,
  out_ofs 
)

Set object in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[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 596 of file lite3_context_api.h.

◆ lite3_ctx_set_str

#define lite3_ctx_set_str (   ctx,
  ofs,
  key,
  str 
)

Set string in object.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[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_ctx_set_str_n().

Definition at line 515 of file lite3_context_api.h.

◆ lite3_ctx_set_str_n

#define lite3_ctx_set_str_n (   ctx,
  ofs,
  key,
  str,
  str_len 
)

Set string in object by length.

Parameters
[in]ctx(lite3_ctx *) context pointer
[in]ofs(size_t) start offset (0 == root)
[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 557 of file lite3_context_api.h.