go-sdk-common.v1: gopkg.in/launchdarkly/go-sdk-common.v1/ldvalue Index | Files

package ldvalue

import "gopkg.in/launchdarkly/go-sdk-common.v1/ldvalue"

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

Package Files

optional_string.go package_info.go value_base.go value_complex_types.go value_serialization.go value_unsafe_conversion.go

type ArrayBuilder Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (o OptionalString) AsValue() Value

AsValue converts the OptionalString to a Value, which is either Null() or a string value.

func (OptionalString) IsDefined Uses

func (o OptionalString) IsDefined() bool

IsDefined returns true if the OptionalString contains a string value, or false if it is empty.

func (OptionalString) MarshalJSON Uses

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 Uses

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 Uses

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 Uses

func (o OptionalString) StringValue() string

StringValue returns the OptionalString's value, or an empty string if it has no value.

func (*OptionalString) UnmarshalJSON Uses

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 Uses

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 Uses

func ArrayOf(items ...Value) Value

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 Bool Uses

func Bool(value bool) Value

Bool creates a boolean Value.

func CopyArbitraryValue Uses

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 Uses

func CopyObject(m map[string]Value) Value

CopyObject creates a Value by copying an existing map[string]Value.

If you want to copy a map[string]interface{} instead, use CopyArbitraryValue.

func Float64 Uses

func Float64(value float64) Value

Float64 creates a numeric Value from a float64.

func Int Uses

func Int(value int) Value

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 Null Uses

func Null() Value

Null creates a null Value.

func Raw Uses

func Raw(value json.RawMessage) Value

Raw creates an unparsed JSON Value.

func String Uses

func String(value string) Value

String creates a string Value.

func UnsafeUseArbitraryValue Uses

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 Uses

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 Uses

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 Uses

func (v Value) AsPointer() *Value

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 Uses

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 Uses

func (v Value) BoolValue() bool

BoolValue returns the Value as a boolean.

If the Value is not a boolean, it returns false.

func (Value) Count Uses

func (v Value) Count() int

Count returns the number of elements in an array or JSON object.

For values of any other type, it returns zero.

func (Value) Equal Uses

func (v Value) Equal(other Value) bool

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 Uses

func (v Value) Float64Value() float64

Float64Value returns the value as a float64.

If the Value is not numeric, it returns zero.

func (Value) GetByIndex Uses

func (v Value) GetByIndex(index int) Value

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 Uses

func (v Value) GetByKey(name string) Value

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 Uses

func (v Value) IntValue() int

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 Uses

func (v Value) IsInt() bool

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) IsNull Uses

func (v Value) IsNull() bool

IsNull returns true if the Value is a null.

func (Value) IsNumber Uses

func (v Value) IsNumber() bool

IsNumber returns true if the Value is numeric.

func (Value) JSONString Uses

func (v Value) JSONString() string

JSONString returns the JSON representation of the value.

func (Value) Keys Uses

func (v Value) Keys() []string

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 Uses

func (v Value) MarshalJSON() ([]byte, error)

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 Uses

func (v Value) String() 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 Uses

func (v Value) StringValue() string

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 Uses

func (v Value) TryGetByIndex(index int) (Value, bool)

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 Uses

func (v Value) TryGetByKey(name string) (Value, bool)

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) Type Uses

func (v Value) Type() ValueType

Type returns the ValueType of the Value.

func (*Value) UnmarshalJSON Uses

func (v *Value) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a Value from JSON.

func (Value) UnsafeArbitraryValue Uses

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 Uses

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
)

func (ValueType) String Uses

func (t ValueType) String() string

String returns the name of the value type.

Package ldvalue imports 4 packages (graph) and is imported by 5 packages. Updated 2020-04-01. Refresh now. Tools for package owners.