Struct launchdarkly_server_sdk::Reference

pub struct Reference { /* private fields */ }

Represents an attribute name or path expression identifying a value within a crate::Context.

This can be used to retrieve a value with crate::Context::get_value, or to identify an attribute or nested value that should be considered private with crate::ContextBuilder::add_private_attribute (the SDK configuration can also have a list of private attribute references).

This is represented as a separate type, rather than just a string, so that validation and parsing can be done ahead of time if an attribute reference will be used repeatedly later (such as in flag evaluations).

If the string starts with ‘/’, then this is treated as a slash-delimited path reference where the first component is the name of an attribute, and subsequent components are the names of nested JSON object properties. In this syntax, the escape sequences “~0” and “~1” represent ‘~’ and ‘/’ respectively within a path component.

If the string does not start with ‘/’, then it is treated as the literal name of an attribute.

Example

// Given the following JSON representation of a context:
{
  "kind": "user",
  "key": "123",
  "name": "xyz",
  "address": {
    "street": "99 Main St.",
    "city": "Westview"
  },
  "a/b": "ok"
}

assert_eq!(context.get_value(&Reference::new("name")),
    Some(AttributeValue::String("xyz".to_owned())));
assert_eq!(context.get_value(&Reference::new("/address/street")),
    Some(AttributeValue::String("99 Main St.".to_owned())));
assert_eq!(context.get_value(&Reference::new("a/b")),
    Some(AttributeValue::String("ok".to_owned())));
assert_eq!(context.get_value(&Reference::new("/a~1b")),
    Some(AttributeValue::String("ok".to_owned())));

Implementations

impl Reference

pub fn new<S>(value: S) -> Referencewhere
    S: AsRef<str>,

Construct a new context attribute reference.

This constructor always returns a reference that preserves the original string, even if validation fails, so that serializing the reference to JSON will produce the original string.

pub fn is_valid(&self) -> bool

Returns true if the reference is valid.

pub fn error(&self) -> String

If the reference is invalid, this method returns an error description; otherwise, it returns an empty string.

pub fn depth(&self) -> usize

Returns the number of path components in the reference.

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.

Example

assert_eq!(Reference::new("a").depth(), 1);
assert_eq!(Reference::new("/a/b").depth(), 2);

pub fn component(&self, index: usize) -> Option<&str>

Retrieves a single path component from the attribute reference.

Returns the attribute name for a simple attribute reference such as “name” with no leading slash, if index is zero.

Returns the specified path component if index is less than Reference::depth, and the reference begins with a slash.

If index is out of range, it returns None.

Examples

assert_eq!(Reference::new("a").component(0), Some("a"));
assert_eq!(Reference::new("/a/b").component(1), Some("b"));
assert_eq!(Reference::new("/a/b").component(2), None);

Trait Implementations

impl Clone for Reference

fn clone(&self) -> Reference

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Reference

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Reference

fn default() -> Reference

A default Reference is empty and invalid.

impl<'de> Deserialize<'de> for Reference

fn deserialize<D>(
    deserializer: D
) -> Result<Reference, <D as Deserializer<'de>>::Error>where
    D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Reference

Displays the input string used to construct the Reference.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<AttributeName> for Reference

fn from(name: AttributeName) -> Reference

AttributeNames are converted into References based on the presence or absence of a leading ‘/’.

Although References are able to represent plain, top-level attribute names, they cannot represent those that begin with a leading ‘/’ because that signifies the pointer syntax.

Therefore, if the first character is a ‘/’ the string must be escaped.

This results in the equivalent Reference representation of that [AttributeName].

Note that References constructed from an AttributeName will serialize to the string passed into the Reference constructor, not the original AttributeName. This is desirable since data should be “upgraded” into the new format as it is encountered.

impl From<Reference> for String

fn from(r: Reference) -> String

Converts to this type from the input type.

impl<S> From<S> for Referencewhere
    S: AsRef<str>,

fn from(reference: S) -> Reference

Converts to this type from the input type.

impl Hash for Reference

fn hash<__H>(&self, state: &mut __H)where
    __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<Reference> for Reference

fn eq(&self, other: &Reference) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Reference

fn serialize<S>(
    &self,
    serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
    S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Reference

impl StructuralEq for Reference

impl StructuralPartialEq for Reference