ldvalue.h File Reference

LDValues represent immutable JSON values. More...

#include <launchdarkly/boolean.h>
#include <launchdarkly/export.h>

Include dependency graph for ldvalue.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	LDValueType { LDValueType_Unrecognized, LDValueType_Null, LDValueType_Bool, LDValueType_Number, LDValueType_String, LDValueType_Array, LDValueType_Object }

Functions
struct LDValue *	LDValue_Bool (LDBoolean boolean)
struct LDValue *	LDValue_True (void)
struct LDValue *	LDValue_False (void)
struct LDValue *	LDValue_Null (void)
struct LDValue *	LDValue_Number (double number)
struct LDValue *	LDValue_ConstantString (const char *string)
struct LDValue *	LDValue_OwnedString (const char *string)
struct LDValue *	LDValue_Array (struct LDArray *array)
struct LDValue *	LDValue_Object (struct LDObject *obj)
struct LDValue *	LDValue_Clone (struct LDValue *source)
enum LDValueType	LDValue_Type (struct LDValue *value)
LDBoolean	LDValue_Equal (struct LDValue *a, struct LDValue *b)
void	LDValue_Free (struct LDValue *value)
struct LDValue *	LDValue_ParseJSON (const char *json)
char *	LDValue_SerializeFormattedJSON (struct LDValue *value)
char *	LDValue_SerializeJSON (struct LDValue *value)
double	LDValue_GetNumber (struct LDValue *value)
LDBoolean	LDValue_GetBool (struct LDValue *value)
const char *	LDValue_GetString (struct LDValue *value)
struct LDIter *	LDValue_GetIter (struct LDValue *value)
unsigned int	LDValue_Count (struct LDValue *value)
struct LDObject *	LDObject_New (void)
void	LDObject_Free (struct LDObject *obj)
void	LDObject_AddConstantKey (struct LDObject *obj, const char *key, struct LDValue *value)
void	LDObject_AddOwnedKey (struct LDObject *obj, const char *key, struct LDValue *value)
struct LDValue *	LDObject_Build (struct LDObject *obj)
struct LDArray *	LDArray_New (void)
void	LDArray_Free (struct LDArray *array)
struct LDValue *	LDArray_Build (struct LDArray *array)
void	LDArray_Add (struct LDArray *array, struct LDValue *value)
struct LDIter *	LDIter_Next (struct LDIter *iterator)
const char *	LDIter_Key (struct LDIter *iterator)
struct LDValue *	LDIter_Val (struct LDIter *iterator)

Detailed Description

LDValues represent immutable JSON values.

Enumeration Type Documentation

LDValueType

enum LDValueType

Describes the type of an LDValue. These correspond to the standard types in JSON.

Enumerator
LDValueType_Unrecognized	The value's type is unrecognized.
LDValueType_Null	The value is null.
LDValueType_Bool	The value is a boolean.
LDValueType_Number	The value is a number. JSON does not have separate types for integers and floats.
LDValueType_String	The value is a string.
LDValueType_Array	The value is an array.
LDValueType_Object	The value is an object.

Function Documentation

LDArray_Add()

void LDArray_Add	(	struct LDArray *	array,
		struct LDValue *	value
	)

Transfers ownership of an LDValue into an LDArray.

Parameters

array	LDArray to mutate. Cannot be NULL.
value	LDValue to move; cannot be NULL. Treat the value as freed; it is unsafe to pass it to any other function.

LDArray_Build()

struct LDValue* LDArray_Build

(

struct LDArray *

array

)

Creates a new LDValue from an LDArray. The type of the LDValue is LDValueType_Array. The LDArray is not freed; this function can be called multiple times.

Parameters

array

Source LDArray. Cannot be NULL.

Returns

New LDValue. Free with LDValue_Free.

LDArray_Free()

void LDArray_Free

(

struct LDArray *

array

)

Recursively frees an LDArray and any elements added with LDArray_Add.

Parameters

array

LDArray to free.

LDArray_New()

struct LDArray* LDArray_New

(

void

)

Creates a new LDArray, which is a mutable builder for an array.

LDArrays may be turned into LDValues via LDArray_Build, or LDValue_Array, depending on the use-case.

Returns

New LDArray. Free with LDArray_Free, or transform into LDValue with LDValue_Array.

LDIter_Key()

const char* LDIter_Key

(

struct LDIter *

iterator

)

Obtain key of current element, if source LDValue was object-type.

Parameters

iterator

Target LDIter. Cannot be NULL. Iterator must be created from object-type LDValue.

Returns

Key or NULL if not object-type.

LDIter_Next()

struct LDIter* LDIter_Next

(

struct LDIter *

iterator

)

Advance iterator to the next element, if present.

Parameters

iterator

Target LDIter. Cannot be NULL.

Returns

Iterator for next element.

LDIter_Val()

struct LDValue* LDIter_Val

(

struct LDIter *

iterator

)

Obtain non-owned reference to LDValue of current iterator element.

Parameters

iterator

Target LDIter. Cannot be NULL.

Returns

Non-owning reference to LDValue. The LDValue lives only as long as the source LDValue from which the LDIter was originally created. It should not be freed.

LDObject_AddConstantKey()

void LDObject_AddConstantKey	(	struct LDObject *	obj,
		const char *	key,
		struct LDValue *	value
	)

Transfers ownership of an LDValue into an LDObject, named by the given key. The key is a constant string reference and will not be freed.

It is the responsibility of the caller to ensure key uniqueness. If called with the same key multiple times, the JSON object will have duplicate keys, i.e:

{"key1" : "foo", "key1" : "bar"}

Parameters

obj	LDObject to mutate. Cannot be NULL.
key	Constant string reference serving as a key. Cannot be NULL.
value	LDValue to move; cannot be NULL. Since ownership is transferred, the caller must not interact with the LDValue in any way after this call.

LDObject_AddOwnedKey()

void LDObject_AddOwnedKey	(	struct LDObject *	obj,
		const char *	key,
		struct LDValue *	value
	)

Transfers ownership of an LDValue into an LDObject, named by the given key. The key will be cloned.

It is the responsibility of the caller to ensure key uniqueness. If called with the same key multiple times, the JSON object will have duplicate keys, i.e:

{"key1" : "foo", "key1" : "bar"}

Parameters

obj	LDObject to mutate. Cannot be NULL.
key	Constant string reference serving as a key. Cannot be NULL. Will be cloned.
value	LDValue to move; cannot be NULL. Since ownership is transferred, the caller must not interact with the LDValue in any way after this call.

LDObject_Build()

struct LDValue* LDObject_Build

(

struct LDObject *

obj

)

Creates a new LDValue from an LDObject. The type of the LDValue is LDValueType_Object. The LDObject is not freed; this function can be called multiple times.

Parameters

obj	Source LDObject. Cannot be NULL.

Returns

New LDValue. Free with LDValue_Free.

LDObject_Free()

void LDObject_Free

(

struct LDObject *

obj

)

Recursively frees an LDObject and any children added with LDObject_Add(Constant|Owned)Key.

Parameters

obj	LDObject to free.

LDObject_New()

struct LDObject* LDObject_New

(

void

)

Creates a new LDObject, which is a mutable builder for a key-value object.

LDObjects may be turned into LDValues via LDObject_Build, or LDValue_Object, depending on the use-case.

Returns

New LDObject. Free with LDObject_Free, or transform into an LDValue with LDValue_Object.

LDValue_Array()

struct LDValue* LDValue_Array

(

struct LDArray *

array

)

Creates an array-type LDValue from an LDArray.

The input LDArray is consumed. Calling any functions on the LDArray may result in undefined behavior.

To generate an LDValue without consuming the builder, see LDArray_Build.

Parameters

array

LDArray to consume. Cannot be NULL.

Returns

New LDValue.

LDValue_Bool()

struct LDValue* LDValue_Bool

(

LDBoolean

boolean

)

Allocates a new boolean-type LDValue.

Parameters

boolean

LDBooleanTrue or LDBooleanFalse.

Returns

New LDValue.

LDValue_Clone()

struct LDValue* LDValue_Clone

(

struct LDValue *

source

)

Allocates a deep clone of an existing LDValue.

Parameters

source

Source LDValue. Must not be NULL.

Returns

New LDValue.

LDValue_ConstantString()

struct LDValue* LDValue_ConstantString

(

const char *

string

)

Allocates a new non-owning string-type LDValue.

Since the input is not owned by the LDValue, it will not be freed and MUST outlive the LaunchDarkly SDK. See LDValue_OwnedString for a constructor that owns a copy of the input string.

Note that this function still allocates in order to create the LDValue container itself.

Parameters

string

Constant reference to a string. Cannot be NULL.

Returns

New LDValue.

LDValue_Count()

unsigned int LDValue_Count

(

struct LDValue *

value

)

Obtain number of LDValue elements stored in an array-type LDValue, or number of key/LDValue pairs stored in an object-type LDValue.

If not an array-type or object-type, returns 0.

Parameters

value

Target LDValue. Cannot be NULL.

Returns

Count of LDValue elements, or 0 if not array-type/object-type.

LDValue_Equal()

LDBoolean LDValue_Equal	(	struct LDValue *	a,
		struct LDValue *	b
	)

Performs a deep equality comparison between 'a' and 'b'.

Warning: if the type of 'a' and 'b' are LDValueType_Object, the comparison is O(N^2).

Parameters

a	First LDValue to compare. Cannot be NULL.
b	Second LDValue to compare. Cannot be NULL.

Returns

True if the LDValues are equal.

LDValue_False()

struct LDValue* LDValue_False

(

void

)

Equivalent to LDValue_Bool(LDBooleanFalse).

Returns

New LDValue.

LDValue_Free()

void LDValue_Free

(

struct LDValue *

value

)

Frees an LDValue.

An LDValue should only be freed when directly owned by the caller, i.e., it was never moved into an LDArray or LDObject.

Parameters

value

LDValue to free. No-op if NULL.

LDValue_GetBool()

LDBoolean LDValue_GetBool

(

struct LDValue *

value

)

Obtain value of a boolean-type LDValue, otherwise returns LDBooleanFalse.

Parameters

value

Target LDValue. Cannot be NULL.

Returns

Boolean value, or LDBooleanFalse if not boolean-type.

LDValue_GetIter()

struct LDIter* LDValue_GetIter

(

struct LDValue *

value

)

Obtain iterator over an object or array-type LDValue, otherwise returns NULL.

The iterator starts at the first element.

Parameters

value

Target LDValue. Cannot be NULL.

Returns

Iterator, or NULL if not object-type or array-type. The iterator does not need to be freed. Its lifetime is that of the LDValue.

LDValue_GetNumber()

double LDValue_GetNumber

(

struct LDValue *

value

)

Obtain value of a number-type LDValue, otherwise return 0.

Parameters

value

Target LDValue. Cannot be NULL.

Returns

Number value, or 0 if not number-type.

LDValue_GetString()

const char* LDValue_GetString

(

struct LDValue *

value

)

Obtain value of a string-type LDValue, otherwise returns pointer to an empty string.

Parameters

value

Target LDValue. Cannot be NULL.

Returns

String value, or empty string if not string-type.

LDValue_Null()

struct LDValue* LDValue_Null

(

void

)

Allocates a new null-type LDValue. Note that a NULL pointer is not a valid LDValue; to represent null (the JSON type), use this constructor.

Returns

New LDValue.

LDValue_Number()

struct LDValue* LDValue_Number

(

double

number

)

Allocates a new number-type LDValue.

Parameters

number

Double value.

Returns

New LDValue.

LDValue_Object()

struct LDValue* LDValue_Object

(

struct LDObject *

obj

)

Creates an object-type LDValue from an LDObject.

The input LDObject is consumed. Calling any functions on the LDObject may result in undefined behavior.

To generate an LDValue without consuming the builder, see LDObject_Build.

Parameters

obj	LDObject to consume. Cannot be NULL.

Returns

New LDValue.

LDValue_OwnedString()

struct LDValue* LDValue_OwnedString

(

const char *

string

)

Allocates a new owning string-type LDValue.

The input string will be copied. To avoid the copy, see LDValue_ConstantString.

Parameters

string

Constant reference to a string. The string is copied. Cannot be NULL.

Returns

New LDValue.

LDValue_ParseJSON()

struct LDValue* LDValue_ParseJSON

(

const char *

json

)

Parses a JSON string into a new LDValue.

The string is not consumed.

Parameters

json	Input JSON string. Cannot be NULL.

Returns

New LDValue if parsing succeeds, otherwise NULL.

LDValue_SerializeFormattedJSON()

char* LDValue_SerializeFormattedJSON

(

struct LDValue *

value

)

Serializes the LDValue to a new, formatted JSON string.

Parameters

value

LDValue to serialize. Cannot be NULL.

Returns

Pointer to formatted JSON string. Free with LDFree.

LDValue_SerializeJSON()

char* LDValue_SerializeJSON

(

struct LDValue *

value

)

Serializes the LDValue to a new, un-formatted JSON string.

Parameters

value

LDValue to serialize. Cannot be NULL.

Returns

Pointer to JSON string. Free with LDFree.

LDValue_True()

struct LDValue* LDValue_True

(

void

)

Equivalent to LDValue_Bool(LDBooleanTrue).

Returns

New LDValue.

LDValue_Type()

enum LDValueType LDValue_Type

(

struct LDValue *

value

)

Returns the type of an LDValue.

Parameters

value

LDValue to inspect. Cannot be NULL.

Returns

Type of the LDValue, or LDValueType_Unrecognized if the type is unrecognized.