Struct 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: AsRef<str>>(value: S) -> Self

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

Formats the value using the given formatter.

impl Default for Reference

fn default() -> Self

A default Reference is empty and invalid.

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

fn deserialize<D>(deserializer: D) -> Result<Self, D::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<Reference> for String

fn from(r: Reference) -> Self

Converts to this type from the input type.

impl<S> From<S> for Reference

where S: AsRef<str>,

fn from(reference: S) -> Self

Converts to this type from the input type.

impl Hash for Reference

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

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 for Reference

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

Tests for self and other values to be equal, and is used by ==.

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

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::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Reference

impl StructuralPartialEq for Reference