Struct AttributeRef

An attribute name or path expression identifying a value within a Context.

Implements

IEquatable<AttributeRef>

IJsonSerializable

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Namespace: LaunchDarkly.Sdk

Assembly: LaunchDarkly.CommonSdk.dll

Syntax

[JsonConverter(typeof(LdJsonConverters.AttributeRefConverter))]
public readonly struct AttributeRef : IEquatable<AttributeRef>, IJsonSerializable

Remarks

This type is mainly intended to be used internally by LaunchDarkly SDK and service code, where efficiency is a major concern so it's desirable to do any parsing or preprocessing just once. Applications are unlikely to need to use the AttributeRef type directly.

It can be used to retrieve a value with GetValue(in AttributeRef), or to identify an attribute or nested value that should be considered private with Builder.Private() (the SDK configuration can also have a list of private attribute references).

Parsing and validation are done at the time that FromPath(string) or FromLiteral(string) is called. If an AttributeRef instance was created from an invalid string, or if it is an uninitialized struct (new AttributeRef()), it is considered invalid and its Error property will return a non-null error.

The string representation of an attribute reference in LaunchDarkly JSON data uses the following syntax:

• If the first character is not a slash, the string is interpreted literally as an attribute name. An attribute name can contain any characters, but must not be empty.
• If the first character is a slash, the string is interpreted as a slash-delimited path where the first path component is an attribute name, and each subsequent path component is the name of a property in a JSON object. Any instances of the characters "/" or "~" in a path component are escaped as "~1" or "~0" respectively. This syntax deliberately resembles JSON Pointer, but no JSON Pointer behaviors other than those mentioned here are supported.

For example, suppose there is a context whose JSON representation looks like this:

{
  "kind": "user",
  "key": "value1",
  "address": {
    "street": {
      "line1": "value2",
      "line2": "value3"
    },
    "city": "value4"
  },
  "good/bad": "value5"
}

• The attribute references "key" and "/key" would both point to "value1".
• The attribute reference "/address/street/line1" would point to "value2".
• The attribute references "good/bad" and "/good~1bad" would both point to "value5".

Properties

Defined

True if the AttributeRef has a value, meaning that it is not an uninitialized struct (new AttributeRef()). That does not guarantee that the value is valid; use Valid or Error to test that.

Declaration

public bool Defined { get; }

Property Value

Type	Description
bool

See Also

Valid

Error

Depth

The number of path components in the AttributeRef.

Declaration

public int Depth { get; }

Property Value

Type	Description
int

Remarks

For a simple attribute reference such as "name" with no leading slash, this returns 1.

For an attribute reference with a leading slash, it is the number of slash-delimited path components after the initial slash. For instance, AttributeRef.FromPath("/a/b").Depth returns 2.

For an invalid attribute reference, it returns zero.

See Also

GetComponent(int)

Error

Null for a valid AttributeRef, or a non-null error message for an invalid AttributeRef.

Declaration

public string Error { get; }

Property Value

Type	Description
string

Remarks

If this is null, then Valid is true. If it is non-null, then Valid is false.

See Also

Valid

Defined

Valid

True for a valid AttributeRef, false for an invalid AttributeRef.

Declaration

public bool Valid { get; }

Property Value

Type	Description
bool

Remarks

An AttributeRef can only be invalid for the following reasons:

1. The input string was empty, or consisted only of "/".
2. A slash-delimited string had a double slash causing one component to be empty, such as "/a//b".
3. A slash-delimited string contained a "~" character that was not followed by "0" or "1".

Otherwise, the AttributeRef is valid, but that does not guarantee that such an attribute exists in any given Context. For instance, AttributeRef.FromLiteral("name") is a valid Ref, but a specific Context might or might not have a name.

See comments on the AttributeRef type for more details of the attribute reference syntax.

See Also

Defined

Error

Methods

Equals(AttributeRef)

Declaration

public bool Equals(AttributeRef other)

Parameters

Type	Name	Description
AttributeRef	other

Returns

Type	Description
bool

Equals(object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj

Returns

Type	Description
bool

Overrides

ValueType.Equals(object)

FromLiteral(string)

Similar to FromPath(string), except that it always interprets the string as a literal attribute name, never as a slash-delimited path expression. There is no escaping or unescaping, even if the name contains literal '/' or '~' characters. Since an attribute name can contain any characters, this method always returns a valid AttributeRef unless the name is empty.

Declaration

public static AttributeRef FromLiteral(string attributeName)

Parameters

Type	Name	Description
string	attributeName	an attribute name

Returns

Type	Description
AttributeRef	an AttributeRef

Remarks

For example: AttributeRef.FromLiteral("name") is exactly equivalent to AttributeRef.FromPath("name"). AttributeRef.FromLiteral("a/b") is exactly equivalent to AttributeRef.FromPath("a/b") (since the syntax used by FromPath(string) treats the whole string as a literal as long as it does not start with a slash), or to AttributeRef.FromPath("/a~1b").

See Also

FromPath(string)

FromPath(string)

Creates an AttributeRef from a string. For the supported syntax and examples, see comments on the AttributeRef type.

Declaration

public static AttributeRef FromPath(string refPath)

Parameters

Type	Name	Description
string	refPath	an attribute name or path

Returns

Type	Description
AttributeRef	an AttributeRef

Remarks

This method always returns an AttributeRef that preserves the original string, even if validation fails, so that calling ToString() (or serializing the AttributeRef to JSON) will produce the original string. If validation fails, Error will return a non-null error and any SDK method that takes this AttributeRef as a parameter will consider it invalid.

See Also

FromLiteral(string)

GetComponent(int)

Retrieves a single path component from the attribute reference.

Declaration

public string GetComponent(int index)

Parameters

Type	Name	Description
int	index	the zero-based index of the desired path component

Returns

Type	Description
string	the path component or null

Remarks

For a simple attribute reference such as "name" with no leading slash, if index is zero, TryGetComponent returns the attribute name.

For an attribute reference with a leading slash, if index is non-negative and less than Depth, TryGetComponent returns the path component.

It returns null if the index is out of range.

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

Overrides

ValueType.GetHashCode()

ToString()

Returns the attribute reference as a string, in the same format used by FromPath(string)

Declaration

public override string ToString()

Returns

Type	Description
string	the attribute reference string (guaranteed non-null)

Overrides

ValueType.ToString()

Remarks

If the AttributeRef was created with FromPath(string), this value is identical to the original string. If it was created with FromLiteral(string), the value may be different due to unescaping (for instance, an attribute whose name is "/a" would be represented as "~1a"). For an uninitialized struct (new AttributeRef()), it returns an empty string.

Implements

IEquatable<T>

IJsonSerializable