Show / Hide Table of Contents

Class LdValue

An immutable instance of any data type that is allowed in JSON.

Inheritance
System.Object
LdValue
Implements
System.IEquatable<LdValue>
IJsonSerializable
Namespace: LaunchDarkly.Sdk
Assembly: LaunchDarkly.CommonSdk.dll
Syntax
public sealed class LdValue : ValueType, IEquatable<LdValue>, IJsonSerializable
Remarks

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

an LdValue.ArrayBuilder

BuildObject()

Starts building an object value.

Declaration
public static LdValue.ObjectBuilder BuildObject()
Returns
Type Description
LdValue.ObjectBuilder

an 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); // true
Exceptions
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 "&quot;x&quot;"; 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

Implements

System.IEquatable<>
IJsonSerializable
In This Article
Back to top Generated by DocFX