ldvalue

package
v2.0.0-alpha.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 24, 2020 License: Apache-2.0 Imports: 5 Imported by: 29

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.

This package also provides the helper type OptionalString, a safer alternative to using string pointers.

Index

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) Get 

func (o OptionalString) Get() (string, bool)

Get is a combination of StringValue and IsDefined. If the OptionalString contains a string value, it returns that value and true; otherwise it returns an empty string and false.

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.

func (OptionalString) WriteToJSONBuffer 

func (o OptionalString) WriteToJSONBuffer(j *jsonstream.JSONBuffer)

WriteToJSONBuffer provides JSON serialization for OptionalString with the jsonstream API.

The JSON output format is identical to what is produced by json.Marshal, but this implementation is more efficient when building output with JSONBuffer. See the jsonstream package for more details.

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 will also work.

Value instances are immutable when used by code outside of this package.

func ArrayOf 

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 

func Bool(value bool) Value

Bool creates a boolean Value.

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.

If it is a pointer to any of the above types, then it is dereferenced and treated the same as above, unless the pointer is nil, in which case it becomes Null().

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 

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 

func Float64(value float64) Value

Float64 creates a numeric Value from a float64.

func Int 

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 

func Null() Value

Null creates a null Value.

func Parse 

func Parse(jsonData []byte) Value

Parse returns a Value parsed from a JSON string, or Null if it cannot be parsed.

This is simply a shortcut for calling json.Unmarshal and disregarding errors. It is meant for use in test scenarios where malformed data is not a concern.

func Raw 

func Raw(value json.RawMessage) Value

Raw creates an unparsed JSON Value.

func String 

func String(value string) Value

String creates a string Value.

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 

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 

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 

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 

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) Enumerate 

func (v Value) Enumerate(fn func(index int, key string, value Value) bool)

Enumerate calls a function for each value within a Value.

If the input value is Null(), the function is not called.

If the input value is an array, fn is called for each element, with the element's index in the first parameter, "" in the second, and the element value in the third.

If the input value is an object, fn is called for each key-value pair, with 0 in the first parameter, the key in the second, and the value in the third.

For any other value type, fn is called once for that value.

The return value of fn is true to continue enumerating, false to stop.

func (Value) Equal 

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. This method behaves the same as reflect.DeepEqual, but is slightly more efficient.

func (Value) Float64Value 

func (v Value) Float64Value() float64

Float64Value returns the value as a float64.

If the Value is not numeric, it returns zero.

func (Value) GetByIndex 

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 

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 

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) IsBool 

func (v Value) IsBool() bool

IsBool returns true if the Value is a boolean.

func (Value) IsInt 

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 

func (v Value) IsNull() bool

IsNull returns true if the Value is a null.

func (Value) IsNumber 

func (v Value) IsNumber() bool

IsNumber returns true if the Value is numeric.

func (Value) IsString 

func (v Value) IsString() bool

IsString returns true if the Value is a string.

func (Value) JSONString 

func (v Value) JSONString() string

JSONString returns the JSON representation of the value.

func (Value) Keys 

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 

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 

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 

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) Transform 

func (v Value) Transform(fn func(index int, key string, value Value) (Value, bool)) Value

Transform applies a transformation function to a Value, returning a new Value.

The behavior is as follows:

If the input value is Null(), the return value is always Null() and the function is not called.

If the input value is an array, fn is called for each element, with the element's index in the first parameter, "" in the second, and the element value in the third. The return values of fn can be either a transformed value and true, or any value and false to remove the element. 

ldvalue.ArrayOf(ldvalue.Int(1), ldvalue.Int(2), ldvalue.Int(3)).Build().
    Transform(func(index int, key string, value Value) (Value, bool) {
        if value.IntValue() == 2 {
            return ldvalue.Null(), false
        }
        return ldvalue.Int(value.IntValue() * 10), true
    })
// returns [10, 30]

If the input value is an object, fn is called for each key-value pair, with 0 in the first parameter, the key in the second, and the value in the third. Again, fn can choose to either transform or drop the value. 

ldvalue.ObjectBuild().Set("a", ldvalue.Int(1)).Set("b", ldvalue.Int(2)).Set("c", ldvalue.Int(3)).Build().
    Transform(func(index int, key string, value Value) (Value, bool) {
        if key == "b" {
            return ldvalue.Null(), false
        }
        return ldvalue.Int(value.IntValue() * 10), true
    })
// returns {"a": 10, "c": 30}

For any other value type, fn is called once for that value; if it provides a transformed value and true, the transformed value is returned, otherwise Null(). 

ldvalue.Int(2).Transform(func(index int, key string, value Value) (Value, bool) {
    return ldvalue.Int(value.IntValue() * 10), true
})
// returns numeric value of 20

For array and object values, if the function does not modify or drop any values, the exact same instance is returned without allocating a new slice or map.

func (Value) TryGetByIndex 

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 

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 

func (v Value) Type() ValueType

Type returns the ValueType of the Value.

func (*Value) UnmarshalJSON 

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

UnmarshalJSON parses a Value from JSON.

func (Value) WriteToJSONBuffer 

func (v Value) WriteToJSONBuffer(j *jsonstream.JSONBuffer)

WriteToJSONBuffer provides JSON serialization for Value with the jsonstream API.

The JSON output format is identical to what is produced by json.Marshal, but this implementation is more efficient when building output with JSONBuffer. See the jsonstream package for more details.

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
)

func (ValueType) String 

func (t ValueType) String() string

String returns the name of the value type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.