Class LdValue
An immutable instance of any data type that is allowed in JSON.
Inheritance
Namespace: LaunchDarkly.Sdk
Assembly: LaunchDarkly.CommonSdk.dll
Syntax
public sealed class LdValue : ValueType, IEquatable<LdValue>, IJsonSerializableRemarks
This is used as the return type of the client's JsonVariation method, and also as the type of custom attributes in User and IUserBuilder.
LaunchDarkly allows feature flag variations and custom user attributes to be of any JSON type, with some restrictions (notably, regarding numeric precision). For more details, see our documentation on flag value types.
Note that this is a langword_csharp_struct, not a class, so it is always passed by value and is not nullable; JSON nulls are represented by the constant Null and can be detected with IsNull. Whenever possible, LdValue stores primitive types within the struct rather than allocating an object on the heap.
There are several ways to create an LdValue. For primitive types, use the various overloads of "Of" such as Of(Boolean); these are very efficient since they do not allocate any objects on the heap. For arrays and objects (dictionaries), use ArrayFrom(IEnumerable<LdValue>), ArrayOf(LdValue[]), ObjectFrom(IReadOnlyDictionary<String, LdValue>), or the corresponding methods in the type-specific LdValue.Convert instances.
To convert to other types, there are the "As" properties such as use the various overloads of "Of" such as Of(Boolean); these are very efficient since they do not allocate any objects on the heap. For arrays and objects (dictionaries), use AsList<T>(LdValue.Converter<T>) or AsDictionary<T>(LdValue.Converter<T>).
Properties
AsBool
Gets the boolean value if this is a boolean.
Declaration
public bool AsBool { get; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
Remarks
If the value is null or is not a boolean, this returns false. It will never throw an exception.
This is equivalent to calling ToType(LdValue) on Bool.
AsDouble
Gets the value as an double if it is numeric.
Declaration
public double AsDouble { get; }Property Value
| Type | Description |
|---|---|
| System.Double |
Remarks
If the value is null or is not numeric, this returns zero. It will never throw an exception.
This is equivalent to calling ToType(LdValue) on Double.
AsFloat
Gets the value as an float if it is numeric.
Declaration
public float AsFloat { get; }Property Value
| Type | Description |
|---|---|
| System.Single |
Remarks
If the value is null or is not numeric, this returns zero. It will never throw an exception.
This is equivalent to calling ToType(LdValue) on Float.
AsInt
Gets the value as an int if it is numeric.
Declaration
public int AsInt { get; }Property Value
| Type | Description |
|---|---|
| System.Int32 |
Remarks
If the value is null or is not numeric, this returns zero. It will never throw an exception.
If the value is a number but not an integer, it will be rounded toward zero.
This is equivalent to calling ToType(LdValue) on Int.
AsLong
Gets the value as an langword_csharp_long if it is numeric.
Declaration
public long AsLong { get; }Property Value
| Type | Description |
|---|---|
| System.Int64 |
Remarks
If the value is null or is not numeric, this returns zero. It will never throw an exception.
If the value is a number but not an integer, it will be rounded toward zero.
This is equivalent to calling ToType(LdValue) on Long.
AsString
Gets the string value if this is a string.
Declaration
public string AsString { get; }Property Value
| Type | Description |
|---|---|
| System.String |
Remarks
If the value is null or is not a string, this returns null. It will never throw an exception. To get a JSON representation of the value as a string, use ToJsonString() instead.
This is equivalent to calling ToType(LdValue) on String.
Count
The number of values if this is an array or object; otherwise zero.
Declaration
public int Count { get; }Property Value
| Type | Description |
|---|---|
| System.Int32 |
Dictionary
Returns an immutable dictionary of values if this value is an object; otherwise an empty dictionary.
Declaration
public ImmutableDictionary<string, LdValue> Dictionary { get; }Property Value
| Type | Description |
|---|---|
| System.Collections.Immutable.ImmutableDictionary<System.String, LdValue> |
IsInt
True if the wrapped value is an integer.
Declaration
public bool IsInt { get; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
Remarks
JSON does not have separate types for integer and floating-point values; they are both just
numbers. IsInt returns true if and only if the actual numeric value has no
fractional component, so LdValue(2).IsInt and LdValue(2.0f).IsInt
are both true.
IsNull
True if the wrapped value is null.
Declaration
public bool IsNull { get; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
IsNumber
True if the wrapped value is numeric.
Declaration
public bool IsNumber { get; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
IsString
True if the wrapped value is a string.
Declaration
public bool IsString { get; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
List
Returns an immutable list of values if this value is an array; otherwise an empty list.
Declaration
public ImmutableList<LdValue> List { get; }Property Value
| Type | Description |
|---|---|
| System.Collections.Immutable.ImmutableList<LdValue> |
Null
Convenience property for an LdValue that wraps a null value.
Declaration
public static LdValue Null { get; }Property Value
| Type | Description |
|---|---|
| LdValue |
Type
The type of the JSON value.
Declaration
public LdValueType Type { get; }Property Value
| Type | Description |
|---|---|
| LdValueType |
Methods
ArrayFrom(IEnumerable<LdValue>)
Initializes an LdValue as an array, from a sequence of JSON values.
Declaration
public static LdValue ArrayFrom(IEnumerable<LdValue> values)Parameters
| Type | Name | Description |
|---|---|---|
| System.Collections.Generic.IEnumerable<LdValue> | values | a sequence of values |
Returns
| Type | Description |
|---|---|
| LdValue | a struct representing a JSON array, or Null if the parameter was null |
Remarks
To create an array from values of some other type, use ArrayFrom(IEnumerable<T>)
Examples
var listOfValues = new List<LdValue> { LdValue.Of(1), LdValue.Of("x") };
var arrayValue = LdValue.ArrayFrom(listOfValues);ArrayOf(LdValue[])
Initializes an LdValue as an array, from a sequence of JSON values.
Declaration
public static LdValue ArrayOf(params LdValue[] values)Parameters
| Type | Name | Description |
|---|---|---|
| LdValue[] | values | any number of values |
Returns
| Type | Description |
|---|---|
| LdValue | a struct representing a JSON array |
Remarks
To create an array from values of some other type, use ArrayOf(T[])
Examples
var arrayValue = LdValue.ArrayFrom(LdValue.Of("a"), LdValue.Of("b"));AsDictionary<T>(LdValue.Converter<T>)
Converts the value to a read-only dictionary.
Declaration
public IReadOnlyDictionary<string, T> AsDictionary<T>(LdValue.Converter<T> desiredType)Parameters
| Type | Name | Description |
|---|---|---|
| LdValue.Converter<T> | desiredType |
Returns
| Type | Description |
|---|---|
| System.Collections.Generic.IReadOnlyDictionary<System.String, T> | a read-only dictionary |
Type Parameters
| Name | Description |
|---|---|
| T |
Remarks
The first parameter is one of the type converters from LdValue.Convert, or your own implementation of LdValue.Converter<T> for some type.
This is an efficient method because it does not copy values to a new dictionary, but returns a read-only view into the existing object.
AsList<T>(LdValue.Converter<T>)
Converts the value to a read-only list of elements of some type.
Declaration
public IReadOnlyList<T> AsList<T>(LdValue.Converter<T> desiredType)Parameters
| Type | Name | Description |
|---|---|---|
| LdValue.Converter<T> | desiredType |
Returns
| Type | Description |
|---|---|
| System.Collections.Generic.IReadOnlyList<T> | an array of elements of the specified type |
Type Parameters
| Name | Description |
|---|---|
| T | the element type |
Remarks
The first parameter is one of the type converters from LdValue.Convert, or your own implementation of LdValue.Converter<T> for some type.
If the value is not a JSON array at all, an empty list is returned. This method will never throw an exception.
This is an efficient method because it does not copy values to a new list, but returns a read-only view into the existing array.
BuildArray()
Starts building an array value.
Declaration
public static LdValue.ArrayBuilder BuildArray()Returns
| Type | Description |
|---|---|
| LdValue.ArrayBuilder |
BuildObject()
Starts building an object value.
Declaration
public static LdValue.ObjectBuilder BuildObject()Returns
| Type | Description |
|---|---|
| LdValue.ObjectBuilder |
Equals(LdValue)
Performs a deep-equality comparison.
Declaration
public bool Equals(LdValue o)Parameters
| Type | Name | Description |
|---|---|---|
| LdValue | o |
Returns
| Type | Description |
|---|---|
| System.Boolean |
Equals(Object)
Performs a deep-equality comparison.
Declaration
public override bool Equals(object o)Parameters
| Type | Name | Description |
|---|---|---|
| System.Object | o |
Returns
| Type | Description |
|---|---|
| System.Boolean |
Get(Int32)
Retrieves an array item or object key by index. Never throws an exception.
Declaration
public LdValue Get(int index)Parameters
| Type | Name | Description |
|---|---|---|
| System.Int32 | index | the item index |
Returns
| Type | Description |
|---|---|
| LdValue | the item value if this is an array; the key if this is an object; otherwise Null |
Get(String)
Retrieves a object value by key. Never throws an exception.
Declaration
public LdValue Get(string key)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | key | the key to retrieve |
Returns
| Type | Description |
|---|---|
| LdValue | the value for the key, if this is an object; Null if not found, or if this is not an object |
GetHashCode()
Declaration
public override int GetHashCode()Returns
| Type | Description |
|---|---|
| System.Int32 |
ObjectFrom(IReadOnlyDictionary<String, LdValue>)
Initializes an LdValue as a JSON object, from a dictionary.
Declaration
public static LdValue ObjectFrom(IReadOnlyDictionary<string, LdValue> dictionary)Parameters
| Type | Name | Description |
|---|---|---|
| System.Collections.Generic.IReadOnlyDictionary<System.String, LdValue> | dictionary | a dictionary with string keys and values of the specified type |
Returns
| Type | Description |
|---|---|
| LdValue | a struct representing a JSON object, or Null if the parameter was null |
Remarks
To use a dictionary with values of some other type, use ObjectFrom(IReadOnlyDictionary<String, T>).
Of(Boolean)
Initializes an LdValue from a boolean value.
Declaration
public static LdValue Of(bool value)Parameters
| Type | Name | Description |
|---|---|---|
| System.Boolean | value | the initial value |
Returns
| Type | Description |
|---|---|
| LdValue | a struct that wraps the value |
Of(Double)
Initializes an LdValue from a double value.
Declaration
public static LdValue Of(double value)Parameters
| Type | Name | Description |
|---|---|---|
| System.Double | value | the initial value |
Returns
| Type | Description |
|---|---|
| LdValue | a struct that wraps the value |
Remarks
Numeric values in LaunchDarkly have some precision limitations. For more details, see our documentation on flag value types.
Of(Int32)
Initializes an LdValue from an int value.
Declaration
public static LdValue Of(int value)Parameters
| Type | Name | Description |
|---|---|---|
| System.Int32 | value | the initial value |
Returns
| Type | Description |
|---|---|
| LdValue | a struct that wraps the value |
Of(Int64)
Initializes an LdValue from a langword_csharp_long value.
Declaration
public static LdValue Of(long value)Parameters
| Type | Name | Description |
|---|---|---|
| System.Int64 | value | the initial value |
Returns
| Type | Description |
|---|---|
| LdValue | a struct that wraps the value |
Remarks
Numeric values in LaunchDarkly have some precision limitations. For more details, see our documentation on flag value types.
Of(Single)
Initializes an LdValue from a float value.
Declaration
public static LdValue Of(float value)Parameters
| Type | Name | Description |
|---|---|---|
| System.Single | value | the initial value |
Returns
| Type | Description |
|---|---|
| LdValue | a struct that wraps the value |
Remarks
Numeric values in LaunchDarkly have some precision limitations. For more details, see our documentation on flag value types.
Of(String)
Initializes an LdValue from a string value.
Declaration
public static LdValue Of(string value)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | value | the initial value |
Returns
| Type | Description |
|---|---|
| LdValue | a struct that wraps the value |
Remarks
A null string reference will be stored as Null rather than as a string.
Parse(String)
Parses a value from a JSON-encoded string.
Declaration
public static LdValue Parse(string jsonString)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | jsonString | a JSON string |
Returns
| Type | Description |
|---|---|
| LdValue | the equivalent LdValue |
Examples
var myValue = LdValue.Parse("[1,2]");
Assert.Equal(LdValue.BuildArray().Add(1).Add(2).Build(), myValue); // trueExceptions
| Type | Condition |
|---|---|
| System.Text.Json.JsonException | if the string could not be parsed as JSON |
ToJsonString()
Converts the value to its JSON encoding.
Declaration
public string ToJsonString()Returns
| Type | Description |
|---|---|
| System.String | the JSON encoding of the value |
Remarks
For instance, LdValue.Of(1).ToJsonString() returns "1";
LdValue.Of("x").ToJsonString() returns ""x""; and
LdValue.Null.ToJsonString() returns "null".
ToString()
Converts the value to its JSON encoding (same as ToJsonString()).
Declaration
public override string ToString()Returns
| Type | Description |
|---|---|
| System.String | the JSON encoding of the value |
Operators
Equality(LdValue, LdValue)
Declaration
public static bool operator ==(LdValue a, LdValue b)Parameters
| Type | Name | Description |
|---|---|---|
| LdValue | a | |
| LdValue | b |
Returns
| Type | Description |
|---|---|
| System.Boolean |
Inequality(LdValue, LdValue)
Declaration
public static bool operator !=(LdValue a, LdValue b)Parameters
| Type | Name | Description |
|---|---|---|
| LdValue | a | |
| LdValue | b |
Returns
| Type | Description |
|---|---|
| System.Boolean |