Show / Hide Table of Contents

Class AttributeRef

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

Inheritance
System.Object
AttributeRef
Implements
System.IEquatable<AttributeRef>
IJsonSerializable
Namespace: LaunchDarkly.Sdk
Assembly: LaunchDarkly.CommonSdk.dll
Syntax
public sealed class AttributeRef : ValueType, 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(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
System.Boolean
See Also
Valid
Error

Depth

The number of path components in the AttributeRef.

Declaration
public int Depth { get; }
Property Value
Type Description
System.Int32
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(Int32)

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
System.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
System.Boolean
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
System.Boolean

Equals(Object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
System.Object obj
Returns
Type Description
System.Boolean

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
System.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
System.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(Int32)

Retrieves a single path component from the attribute reference.

Declaration
public string GetComponent(int index)
Parameters
Type Name Description
System.Int32 index

the zero-based index of the desired path component

Returns
Type Description
System.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
System.Int32

ToString()

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

Declaration
public override string ToString()
Returns
Type Description
System.String

the attribute reference string (guaranteed non-null)

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

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