The highest tagged major version is
Documentation
¶
Overview ¶
Package ldvalue provides an abstraction of the LaunchDarkly SDK's general value type. LaunchDarkly supports the standard JSON data types of null, boolean, number, string, array, and object (map), for any feature flag variation or custom user attribute. The ldvalue.Value type can contain any of these.
For backward compatibility, some SDK methods and types still represent these values with the general Go type "interface{}". Whenever there is an alternative that uses ldvalue.Value, that is preferred; in the next major version release of the SDK, the uses of interface{} will be removed. There are two reasons. First, interface{} can contain values that have no JSON encoding. Second, interface{} could be an array, slice, or map, all of which are passed by reference and could be modified in one place causing unexpected effects in another place. Value is guaranteed to be immutable and to contain only JSON-compatible types as long as you do not use the UnsafeUseArbitraryValue() and UnsafeArbitraryValue() methods (which will be removed in the future).
This package also provides the helper type OptionalString, a safer alternative to using string pointers.
Index ¶
- type ArrayBuilder
- type ObjectBuilder
- type OptionalString
- func (o OptionalString) AsPointer() *string
- func (o OptionalString) AsValue() Value
- func (o OptionalString) IsDefined() bool
- func (o OptionalString) MarshalJSON() ([]byte, error)
- func (o OptionalString) OrElse(valueIfEmpty string) string
- func (o OptionalString) String() string
- func (o OptionalString) StringValue() string
- func (o *OptionalString) UnmarshalJSON(data []byte) error
- type Value
- func ArrayOf(items ...Value) Value
- func Bool(value bool) Value
- func CopyArbitraryValue(valueAsInterface interface{}) Value
- func CopyObject(m map[string]Value) Value
- func Float64(value float64) Value
- func Int(value int) Value
- func Null() Value
- func Raw(value json.RawMessage) Value
- func String(value string) Value
- func UnsafeUseArbitraryValue(valueAsInterface interface{}) Valuedeprecated
- func (v Value) AsArbitraryValue() interface{}
- func (v Value) AsOptionalString() OptionalString
- func (v Value) AsPointer() *Value
- func (v Value) AsRaw() json.RawMessage
- func (v Value) BoolValue() bool
- func (v Value) Count() int
- func (v Value) Equal(other Value) bool
- func (v Value) Float64Value() float64
- func (v Value) GetByIndex(index int) Value
- func (v Value) GetByKey(name string) Value
- func (v Value) IntValue() int
- func (v Value) IsInt() bool
- func (v Value) IsNull() bool
- func (v Value) IsNumber() bool
- func (v Value) JSONString() string
- func (v Value) Keys() []string
- func (v Value) MarshalJSON() ([]byte, error)
- func (v Value) String() string
- func (v Value) StringValue() string
- func (v Value) TryGetByIndex(index int) (Value, bool)
- func (v Value) TryGetByKey(name string) (Value, bool)
- func (v Value) Type() ValueType
- func (v *Value) UnmarshalJSON(data []byte) error
- func (v Value) UnsafeArbitraryValue() interface{}deprecated
- type ValueType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ArrayBuilder ¶
type ArrayBuilder interface {
// Add appends an element to the array builder.
Add(value Value) ArrayBuilder
// Build creates a Value containing the previously added array elements. Continuing to modify the
// same builder by calling Add after that point does not affect the returned array.
Build() Value
}
ArrayBuilder is a builder created by ArrayBuild(), for creating immutable arrays.
func ArrayBuild ¶
func ArrayBuild() ArrayBuilder
ArrayBuild creates a builder for constructing an immutable array Value.
arrayValue := ldvalue.ArrayBuild().Add(ldvalue.Int(100)).Add(ldvalue.Int(200)).Build()
func ArrayBuildWithCapacity ¶
func ArrayBuildWithCapacity(capacity int) ArrayBuilder
ArrayBuildWithCapacity creates a builder for constructing an immutable array Value.
The capacity parameter is the same as the capacity of a slice, allowing you to preallocate space if you know the number of elements; otherwise you can pass zero.
arrayValue := ldvalue.ArrayBuildWithCapacity(2).Add(ldvalue.Int(100)).Add(ldvalue.Int(200)).Build()
type ObjectBuilder ¶
type ObjectBuilder interface {
// Set sets a key-value pair in the object builder.
Set(key string, value Value) ObjectBuilder
// Build creates a Value containing the previously specified key-value pairs. Continuing to modify
// the same builder by calling Set after that point does not affect the returned object.
Build() Value
}
ObjectBuilder is a builder created by ObjectBuild(), for creating immutable JSON objects.
func ObjectBuild ¶
func ObjectBuild() ObjectBuilder
ObjectBuild creates a builder for constructing an immutable JSON object Value.
objValue := ldvalue.ObjectBuild().Set("a", ldvalue.Int(100)).Set("b", ldvalue.Int(200)).Build()
func ObjectBuildWithCapacity ¶
func ObjectBuildWithCapacity(capacity int) ObjectBuilder
ObjectBuildWithCapacity creates a builder for constructing an immutable JSON object Value.
The capacity parameter is the same as the capacity of a map, allowing you to preallocate space if you know the number of elements; otherwise you can pass zero.
objValue := ldvalue.ObjectBuildWithCapacity(2).Set("a", ldvalue.Int(100)).Set("b", ldvalue.Int(200)).Build()
type OptionalString ¶
type OptionalString struct {
// contains filtered or unexported fields
}
OptionalString represents a string that may or may not have a value. This is similar to using a string pointer to distinguish between an empty string and nil, but it is safer because it does not expose a pointer to any mutable value.
Unlike Value, which can contain a value of any JSON-compatible type, OptionalString either contains a string or nothing. To create an instance with a string value, use NewOptionalString. There is no corresponding method for creating an instance with no value; simply use the empty literal OptionalString{}.
os1 := NewOptionalString("this has a value")
os2 := NewOptionalString("") // this has a value which is an empty string
os2 := OptionalString{} // this does not have a value
This can also be used as a convenient way to construct a string pointer within an expression. For instance, this example causes myStringPointer to point to the string "x":
var myStringPointer *string = NewOptionalString("x").AsPointer()
func NewOptionalString ¶
func NewOptionalString(value string) OptionalString
NewOptionalString constructs an OptionalString that has a string value.
There is no corresponding method for creating an OptionalString with no value; simply use the empty literal OptionalString{}.
func NewOptionalStringFromPointer ¶
func NewOptionalStringFromPointer(valuePointer *string) OptionalString
NewOptionalStringFromPointer constructs an OptionalString from a string pointer. If the pointer is non-nil, then the OptionalString copies its value; otherwise the OptionalString is empty.
func (OptionalString) AsPointer ¶
func (o OptionalString) AsPointer() *string
AsPointer returns the OptionalString's value as a string pointer if it has a value, or nil otherwise.
The string value, if any, is copied rather than returning to a pointer to the internal field.
func (OptionalString) AsValue ¶
func (o OptionalString) AsValue() Value
AsValue converts the OptionalString to a Value, which is either Null() or a string value.
func (OptionalString) IsDefined ¶
func (o OptionalString) IsDefined() bool
IsDefined returns true if the OptionalString contains a string value, or false if it is empty.
func (OptionalString) MarshalJSON ¶
func (o OptionalString) MarshalJSON() ([]byte, error)
MarshalJSON converts the OptionalString to its JSON representation.
The output will be either a JSON string or null. Note that the "omitempty" tag for a struct field will not cause an empty OptionalString field to be omitted; it will be output as null. If you want to completely omit a JSON property when there is no value, it must be a string pointer instead of an OptionalString; use the AsPointer() method to get a pointer.
func (OptionalString) OrElse ¶
func (o OptionalString) OrElse(valueIfEmpty string) string
OrElse returns the OptionalString's value if it has one, or else the specified fallback value.
func (OptionalString) String ¶
func (o OptionalString) String() string
String is a debugging convenience method that returns a description of the OptionalString. This is either the same as its string value, "[empty]" if it has a string value that is empty, or "[none]" if it has no value.
Since String() is used by methods like fmt.Printf, if you want to use the actual string value of the OptionalString instead of this special representation, you should call StringValue():
s := OptionalString{}
fmt.Printf("it is '%s'", s) // prints "it is '[none]'"
fmt.Printf("it is '%s'", s.StringValue()) // prints "it is ''"
func (OptionalString) StringValue ¶
func (o OptionalString) StringValue() string
StringValue returns the OptionalString's value, or an empty string if it has no value.
func (*OptionalString) UnmarshalJSON ¶
func (o *OptionalString) UnmarshalJSON(data []byte) error
UnmarshalJSON parses an OptionalString from JSON.
The input must be either a JSON string or null.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value represents any of the data types supported by JSON, all of which can be used for a LaunchDarkly feature flag variation or a custom user attribute.
You cannot compare Value instances with the == operator, because the struct may contain a slice. Value has an Equal method for this purpose; reflect.DeepEqual should not be used because it may not always work correctly (see below).
Values constructed with the regular constructors in this package are immutable. However, in the current implementation, the SDK may also return a Value that is a wrapper for an interface{} value that was parsed from JSON, which could be a mutable slice or map. For backward compatibility with code that expects to be able to get the interface{} value without an extra deep-copy step, this value is accessible directly with the UnsafeArbitraryValue method. Application code should not use the Unsafe methods and does not need to be concerned with the difference between these two kinds of Value, except that it is the reason why reflect.DeepEqual should not be used (that is, two Values that are logically equal might not have exactly the same fields internally because one might be a wrapper for an interface{}).
func ArrayOf ¶
ArrayOf creates an array Value from a list of Values.
This requires a slice copy to ensure immutability; otherwise, an existing slice could be passed using the spread operator, and then modified. However, since Value is itself immutable, it does not need to deep-copy each item.
func CopyArbitraryValue ¶
func CopyArbitraryValue(valueAsInterface interface{}) Value
CopyArbitraryValue creates a Value from an arbitrary interface{} value of any type.
If the value is nil, a boolean, an integer, a floating-point number, or a string, it becomes the corresponding JSON primitive value type. If it is a slice of values ([]interface{} or []Value), it is deep-copied to an array value. If it is a map of strings to values (map[string]interface{} or map[string]Value), it is deep-copied to an object value.
For all other types, the value is marshaled to JSON and then converted to the corresponding Value type (unless marshalling returns an error, in which case it becomes Null()). This is somewhat inefficient since it involves parsing the marshaled JSON.
func CopyObject ¶
CopyObject creates a Value by copying an existing map[string]Value.
If you want to copy a map[string]interface{} instead, use CopyArbitraryValue.
func Int ¶
Int creates a numeric Value from an integer.
Note that all numbers are represented internally as the same type (float64), so Int(2) is exactly equal to Float64(2).
func UnsafeUseArbitraryValue
deprecated
func UnsafeUseArbitraryValue(valueAsInterface interface{}) Value
UnsafeUseArbitraryValue creates a Value that wraps an arbitrary Go value as-is. Application code should never use this method, since it can break the immutability contract of Value.
This method and Value.UnsafeArbitraryValue() are provided for backward compatibility in v4 of the Go SDK, where flag values are stored internally as interface{} and can be accessed as interface{} with JsonVariation() or JsonVariationDetail(); using the original value avoids adding an unexpected deep-copy step for code that is using those methods. In a future version, that behavior will be removed and the SDK will use only immutable Value instances.
The allowable value types are the same as for CopyArbitraryValue.
Deprecated: Application code should use CopyArbitraryValue instead of this (or just use the regular value constructors such as Bool() and ObjectBuild()). This method will be removed in a future version.
func (Value) AsArbitraryValue ¶
func (v Value) AsArbitraryValue() interface{}
AsArbitraryValue returns the value in its simplest Go representation, typed as interface{}.
This is nil for a null value; for primitive types, it is bool, float64, or string (all numbers are represented as float64 because that is Go's default when parsing from JSON).
Arrays and objects are represented as []interface{} and map[string]interface{}. They are deep-copied, which preserves immutability of the Value but may be an expensive operation. To examine array and object values without copying the whole data structure, use getter methods: Count, Keys, GetByIndex, TryGetByIndex, GetByKey, TryGetByKey.
func (Value) AsOptionalString ¶
func (v Value) AsOptionalString() OptionalString
AsOptionalString converts the value to the OptionalString type, which contains either a string value or nothing if the original value was not a string.
func (Value) AsPointer ¶
AsPointer returns either a pointer to a copy of this Value, or nil if it is a null value.
This may be desirable if you are serializing a struct that contains a Value, and you want that field to be completely omitted if the Value is null; since the "omitempty" tag only works for pointers, you can declare the field as a *Value like so:
type MyJsonStruct struct {
AnOptionalField *Value `json:"anOptionalField,omitempty"`
}
s := MyJsonStruct{AnOptionalField: someValue.AsPointer()}
func (Value) AsRaw ¶
func (v Value) AsRaw() json.RawMessage
AsRaw returns the value as a json.RawMessage.
If the value was originally created from a RawMessage, it returns the same value. For all other values, it converts the value to its JSON representation and returns that representation.
func (Value) BoolValue ¶
BoolValue returns the Value as a boolean.
If the Value is not a boolean, it returns false.
func (Value) Count ¶
Count returns the number of elements in an array or JSON object.
For values of any other type, it returns zero.
func (Value) Equal ¶
Equal tests whether this Value is equal to another, in both type and value.
For arrays and objects, this is a deep equality test. Do not use reflect.DeepEqual with Value; it currently is not guaranteed to work due to possible differences in how the same value may be represented internally.
func (Value) Float64Value ¶
Float64Value returns the value as a float64.
If the Value is not numeric, it returns zero.
func (Value) GetByIndex ¶
GetByIndex gets an element of an array by index.
If the value is not an array, or if the index is out of range, it returns Null().
func (Value) GetByKey ¶
GetByKey gets a value from a JSON object by key.
If the value is not an object, or if the key is not found, it returns Null().
func (Value) IntValue ¶
IntValue returns the value as an int.
If the Value is not numeric, it returns zero. If the value is a number but not an integer, it is rounded toward zero (truncated).
func (Value) IsInt ¶
IsInt returns true if the Value is an integer.
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 Int(2).IsInt() and Float64(2.0).IsInt() are both true.
func (Value) JSONString ¶
JSONString returns the JSON representation of the value.
func (Value) Keys ¶
Keys returns the keys of a JSON object as a slice.
The method copies the keys. If the value is not an object, it returns an empty slice.
func (Value) MarshalJSON ¶
MarshalJSON converts the Value to its JSON representation.
Note that the "omitempty" tag for a struct field will not cause an empty Value field to be omitted; it will be output as null. If you want to completely omit a JSON property when there is no value, it must be a pointer; use AsPointer().
func (Value) String ¶
String converts the value to a string representation, equivalent to JSONString().
This is different from StringValue, which returns the actual string for a string value or an empty string for anything else. For instance, Int(2).StringValue() returns "2" and String("x").StringValue() returns "\"x\"", whereas Int(2).AsString() returns "" and String("x").AsString() returns "x".
This method is provided because it is common to use the Stringer interface as a quick way to summarize the contents of a value. The simplest way to do so in this case is to use the JSON representation.
func (Value) StringValue ¶
StringValue returns the value as a string.
If the value is not a string, it returns an empty string.
This is different from String(), which returns a concise string representation of any value type.
func (Value) TryGetByIndex ¶
TryGetByIndex gets an element of an array by index, with a second return value of true if successful.
If the value is not an array, or if the index is out of range, it returns (Null(), false).
func (Value) TryGetByKey ¶
TryGetByKey gets a value from a JSON object by key, with a second return value of true if successful.
If the value is not an object, or if the key is not found, it returns (Null(), false).
func (*Value) UnmarshalJSON ¶
UnmarshalJSON parses a Value from JSON.
func (Value) UnsafeArbitraryValue
deprecated
func (v Value) UnsafeArbitraryValue() interface{}
UnsafeArbitraryValue converts the Value to its corresponding Go type as an interface{} - or, if it was created from an existing slice or map using UnsafeUseArbitraryValue, it returns that original value as an interface{} without deep-copying. See UnsafeUseArbitraryValue for more information.
Deprecated: Application code should use AsArbitraryValue instead. This method will be removed in a future version.
type ValueType ¶
type ValueType int
ValueType indicates which JSON type is contained in a Value.
const ( // NullType describes a null value. Note that the zero value of ValueType is NullType, so the // zero of Value is a null value. NullType ValueType = iota // BoolType describes a boolean value. BoolType ValueType = iota // NumberType describes a numeric value. JSON does not have separate types for int and float, but // you can convert to either. NumberType ValueType = iota // StringType describes a string value. StringType ValueType = iota // ArrayType describes an array value. ArrayType ValueType = iota // ObjectType describes an object (a.k.a. map). ObjectType ValueType = iota // RawType describes a json.RawMessage value. This value will not be parsed or interpreted as // any other data type, and can be accessed only by calling AsRaw(). RawType ValueType = iota )
Source Files