Struct dynamodb_expression::path::Path

pub struct Path { /* private fields */ }

Represents a DynamoDB document path. For example, foo[3][7].bar[2].baz.

When used in an Expression, attribute names in a Path are automatically handled as expression attribute names, allowing for names that would not otherwise be permitted by DynamoDB. For example, foo[3][7].bar[2].baz would become something similar to #0[3][7].#1[2].#2, and the names would be in the expression_attribute_names.

See also: Element, Name, IndexedField

Examples

Parsing

The safest way to construct a Path is to parse it.

use dynamodb_expression::Path;

let path: Path = "foo".parse().unwrap();
let path: Path = "foo[3]".parse().unwrap();
let path: Path = "foo[3][7]".parse().unwrap();
let path: Path = "foo[3][7].bar".parse().unwrap();
let path: Path = "bar.baz".parse().unwrap();
let path: Path = "baz[0].foo".parse().unwrap();

This makes the common assumption that each path element is separated by a period (.). For example, the path foo.bar gets treated as if foo is a top-level attribute, and bar is a sub-attribute of foo. However, . is also a valid character in an attribute name. See below for examples of how to construct a Path when an attribute name contains a ..

There are many ways to crate a Path

Each of these are ways to create a Path instance for foo[3][7].bar[2].baz.

use dynamodb_expression::{path::Element, Path};

// A `Path` can be parsed from a string
let path: Path = "foo[3][7].bar[2].baz".parse().unwrap();

// `Path` implements `FromIterator` for items that are `Element`s.
let path = Path::from_iter([
    Element::new_indexed_field("foo", [3, 7]),
    Element::new_indexed_field("bar", 2),
    Element::new_name("baz"),
]);

// Of course, that means you can `.collect()` into a `Path`.
let path: Path = [
    Element::new_indexed_field("foo", [3, 7]),
    Element::new_indexed_field("bar", 2),
    Element::new_name("baz"),
]
.into_iter()
.collect();

// `Element` can be converted into from string/index tuples. Where the
// string is the attribute name. In this case, an "index" is an array,
// slice, `Vec` of, or a single `usize`.
//
// It's smart about it, though. If if there's one or zero indexes it'll do
// the right thing. This helps when you're chaining iterator adapters and
// the results are values with inconsistent numbers of indexes.
let path = Path::from_iter(
    [
        ("foo", vec![3, 7]),
        ("bar", vec![2]),
        ("baz", vec![]),
    ]
    .map(Element::from),
);

// `Path` implements `FromIterator` for items that are `Into<Element>`.
// So, the above example can be simplified.
let path = Path::from_iter([
    ("foo", vec![3, 7]),
    ("bar", vec![2]),
    ("baz", vec![]),
]);

// You can append one [`Path`] to another.
let mut path = Path::new_indexed_field("foo", [3, 7]);
path.append(Path::new_indexed_field("bar", 2));
path.append(Path::new_name("baz"));

A Name can be converted into a Path.

use dynamodb_expression::{path::{Element, Name}, Path};

let name = Name::from("foo");
let path = Path::from(name);
assert_eq!(Path::from(Element::new_name("foo")), path);

Attribute names with . in them

If you have an attribute name with a . in it, and need it to not be treated as a separator, you can construct the Path a few different ways. Here are some ways you can correctly construct a Path using attr.name as the problematic attribute name.

use dynamodb_expression::{path::Element, Path};

// As a top-level attribute name:
let path = Path::new_name("attr.name");

// If the top-level attribute, `foo`, has a sub-attribute named `attr.name`:
let path = Path::from_iter([
    Element::new_name("foo"),
    Element::new_name("attr.name"),
]);

// If top-level attribute `foo`, item 3 (i.e., `foo[3]`) has a sub-attribute
// named `attr.name`:
let path = Path::from_iter([
    Element::new_indexed_field("foo", 3),
    Element::new_name("attr.name"),
]);

// If top-level attribute `foo`, item 3, sub-item 7 (i.e., `foo[3][7]`) has
// an attribute named `attr.name`:
let path = Path::from_iter([
    Element::new_indexed_field("foo", [3, 7]),
    Element::new_name("attr.name"),
]);

Implementations

impl Path

pub fn new_name<T>(name: T) -> Selfwhere T: Into<Name>,

Constructs a Path for a single attribute name (with no indexes or sub-attributes). If you have a attribute name with one or more indexes, use Path::new_indexed_field.

pub fn new_indexed_field<N, I>(name: N, indexes: I) -> Selfwhere N: Into<Name>, I: Indexes,

Constructs a Path for an indexed field element of a document path. For example, foo[3] or foo[7][4]. If you have a attribute name with no indexes, you can pass an empty collection, or use Path::new_name.

indexes here can be an array, slice, Vec of, or single usize.

assert_eq!("foo[3]", Path::new_indexed_field("foo", 3).to_string());
assert_eq!("foo[3]", Path::new_indexed_field("foo", [3]).to_string());
assert_eq!("foo[3]", Path::new_indexed_field("foo", &[3]).to_string());
assert_eq!("foo[3]", Path::new_indexed_field("foo", vec![3]).to_string());

assert_eq!("foo[7][4]", Path::new_indexed_field("foo", [7, 4]).to_string());
assert_eq!("foo[7][4]", Path::new_indexed_field("foo", &[7, 4]).to_string());
assert_eq!("foo[7][4]", Path::new_indexed_field("foo", vec![7, 4]).to_string());

assert_eq!("foo", Path::new_indexed_field("foo", []).to_string());
assert_eq!("foo", Path::new_indexed_field("foo", &[]).to_string());
assert_eq!("foo", Path::new_indexed_field("foo", vec![]).to_string());

See also: IndexedField, Element::new_indexed_field

pub fn append(&mut self, other: Path)

Appends another Path to the end of this one.

use dynamodb_expression::Path;

let mut path: Path = "foo[2]".parse().unwrap();
let sub_path: Path = "bar".parse().unwrap();
path.append(sub_path);
assert_eq!("foo[2].bar".parse::<Path>().unwrap(), path);

impl Path

Methods relating to building condition and filter expressions.

pub fn equal<T>(self, right: T) -> Conditionwhere T: Into<Operand>,

Check if the value at this Path is equal to the given value.

DynamoDB documentation.

pub fn not_equal<T>(self, right: T) -> Conditionwhere T: Into<Operand>,

Check if the value at this Path is not equal to the given value.

DynamoDB documentation.

pub fn greater_than<T>(self, right: T) -> Conditionwhere T: Into<Operand>,

Check if the value at this Path is greater than the given value.

DynamoDB documentation.

pub fn greater_than_or_equal<T>(self, right: T) -> Conditionwhere T: Into<Operand>,

Check if the value at this Path is greater than or equal to the given value.

DynamoDB documentation.

pub fn less_than<T>(self, right: T) -> Conditionwhere T: Into<Operand>,

Check if the value at this Path is less than the given value.

DynamoDB documentation.

pub fn less_than_or_equal<T>(self, right: T) -> Conditionwhere T: Into<Operand>,

Check if the value at this Path is less than or equal to the given value.

DynamoDB documentation.

pub fn between<L, U>(self, lower: L, upper: U) -> Conditionwhere L: Into<Operand>, U: Into<Operand>,

The DynamoDB BETWEEN operator. True if self is greater than or equal to lower, and less than or equal to upper.

use dynamodb_expression::{Num, Path};

let condition = Path::new_name("age").between(Num::new(10), Num::new(90));
assert_eq!(r#"age BETWEEN 10 AND 90"#, condition.to_string());

See also: Key::between

pub fn in_<I, T>(self, items: I) -> Conditionwhere I: IntoIterator<Item = T>, T: Into<Operand>,

A DynamoDB IN operation. True if the value at this Path is equal to any value in the list.

The list can contain up to 100 values. It must have at least 1.

use dynamodb_expression::Path;

let condition = Path::new_name("name").in_(["Jack", "Jill"]);
assert_eq!(r#"name IN ("Jack","Jill")"#, condition.to_string());

pub fn attribute_exists(self) -> Condition

The DynamoDB attribute_exists function. True if the item contains the attribute specified by Path.

use dynamodb_expression::Path;

let condition = Path::new_name("foo").attribute_exists();
assert_eq!("attribute_exists(foo)", condition.to_string());

pub fn attribute_not_exists(self) -> Condition

The DynamoDB attribute_not_exists function. True if the item does not contain the attribute specified by Path.

use dynamodb_expression::Path;

let condition = Path::new_name("foo").attribute_not_exists();
assert_eq!("attribute_not_exists(foo)", condition.to_string());

pub fn attribute_type(self, attribute_type: Type) -> Condition

The DynamoDB attribute_type function. True if the attribute at the specified Path is of the specified data type.

use dynamodb_expression::{condition::attribute_type::Type, Path};

let condition = Path::new_name("foo").attribute_type(Type::String);
assert_eq!("attribute_type(foo, S)", condition.to_string());

pub fn begins_with<T>(self, prefix: T) -> Conditionwhere T: Into<StringOrRef>,

The DynamoDB begins_with function. True if the attribute specified by the Path begins with a particular substring.

begins_with can take a string or a reference to an extended attribute value. Here’s an example.

use dynamodb_expression::{condition::BeginsWith, value::Ref, Path};

let begins_with = Path::new_name("foo").begins_with("T");
assert_eq!(r#"begins_with(foo, "T")"#, begins_with.to_string());

let begins_with = Path::new_name("foo").begins_with(Ref::new("prefix"));
assert_eq!(r#"begins_with(foo, :prefix)"#, begins_with.to_string());

See also: Ref

pub fn contains<V>(self, operand: V) -> Conditionwhere V: Into<Value>,

The DynamoDB contains function. True if the attribute specified by Path is one of the following:

• A String that contains a particular substring.
• A Set that contains a particular element within the set.
• A List that contains a particular element within the list.

The operand must be a String if the attribute specified by path is a String. If the attribute specified by path is a Set, the operand must be the sets element type.

use dynamodb_expression::{Num, Path};

// String
let condition = Path::new_name("foo").contains("Quinn");
assert_eq!(r#"contains(foo, "Quinn")"#, condition.to_string());

// Number
let condition = Path::new_name("foo").contains(Num::new(42));
assert_eq!(r#"contains(foo, 42)"#, condition.to_string());

// Binary
let condition = Path::new_name("foo").contains(Vec::<u8>::from("fish"));
assert_eq!(r#"contains(foo, "ZmlzaA==")"#, condition.to_string());

See also: Contains

pub fn size(self) -> Size

The DynamoDB size function. Returns a number representing an attributes size.

use dynamodb_expression::{Num, Path};

let condition = Path::new_name("foo").size().greater_than(Num::new(0));
assert_eq!("size(foo) > 0", condition.to_string());

impl Path

Methods relating to building update expressions.

See also: Update

pub fn assign<T>(self, value: T) -> Assignwhere T: Into<Value>,

Represents assigning a value of a attribute, list, or map.

See also: Update

use dynamodb_expression::{Num, Path, update::Update};

let assign = Path::new_name("name").assign("Jill");
assert_eq!(r#"name = "Jill""#, assign.to_string());

let update = Update::from(assign);
assert_eq!(r#"SET name = "Jill""#, update.to_string());

pub fn math(self) -> MathBuilder

Use for doing math on a numeric attribute.

Sets this as the destination in a Math builder.

See also: Update

Examples

use dynamodb_expression::{Path, update::Update};

let math = Path::new_name("foo").math().add(4);
assert_eq!("foo = foo + 4", math.to_string());

let math = Path::new_name("foo").math().src(Path::new_name("bar")).sub(7);
assert_eq!("foo = bar - 7", math.to_string());

let update = Update::from(math);
assert_eq!("SET foo = bar - 7", update.to_string());

pub fn list_append(self) -> ListAppendBuilder

Represents an update expression to append elements to a list.

See also: Update

Examples

use dynamodb_expression::{Num, Path, update::Update};

let list_append = Path::new_name("foo").list_append().list([7, 8, 9].map(Num::new));
assert_eq!("foo = list_append(foo, [7, 8, 9])", list_append.to_string());

let update = Update::from(list_append);
assert_eq!("SET foo = list_append(foo, [7, 8, 9])", update.to_string());

If you want to add the new values to the beginning of the list instead, use the .before() method.

use dynamodb_expression::{Num, Path, update::Update};

let list_append = Path::new_name("foo").list_append().before().list([1, 2, 3].map(Num::new));
assert_eq!("foo = list_append([1, 2, 3], foo)", list_append.to_string());

let update = Update::from(list_append);
assert_eq!("SET foo = list_append([1, 2, 3], foo)", update.to_string());

pub fn if_not_exists(self) -> IfNotExistsBuilder

Represents an update expression to set an attribute if it doesn’t exist.

See also: Update

Examples

use dynamodb_expression::{Num, Path, update::Update};

let if_not_exists = Path::new_name("foo").if_not_exists().assign(Num::new(7));
assert_eq!("foo = if_not_exists(foo, 7)", if_not_exists.to_string());

let update = Update::from(if_not_exists);
assert_eq!("SET foo = if_not_exists(foo, 7)", update.to_string());

pub fn delete<T>(self, set: T) -> Deletewhere T: Into<Set>,

Creates a DELETE statement for an update expression, for removing one or more items from a value that is a set.

See also: Update

Examples

use dynamodb_expression::{Path, update::Update, value::StringSet};

let delete = Path::new_name("foo").delete(StringSet::new(["a", "b", "c"]));
assert_eq!(r#"DELETE foo ["a", "b", "c"]"#, delete.to_string());

let update = Update::from(delete);
assert_eq!(r#"DELETE foo ["a", "b", "c"]"#, update.to_string());

pub fn add<T>(self, value: T) -> Addwhere T: Into<AddValue>,

Represents an DynamoDB ADD statement in an update expression.

The DynamoDB documentation recommends against using ADD:

In general, we recommend using SET rather than ADD.

See also: AddValue, Update, Set

Examples

use dynamodb_expression::{Num, Path, update::{Add, Update}};

let add = Path::new_name("foo").add(Num::from(1));
assert_eq!("ADD foo 1", add.to_string());

let update = Update::from(add);
assert_eq!("ADD foo 1", update.to_string());

pub fn remove(self) -> Remove

Creates an update expression to remove attributes from an item, or elements from a list.

See also: Remove, Update

Examples

use dynamodb_expression::{Path, update::{Remove, Update}};

let remove = Path::new_name("foo").remove();
assert_eq!(r#"REMOVE foo"#, remove.to_string());

let update = Update::from(remove);
assert_eq!(r#"REMOVE foo"#, update.to_string());

let remove = Path::new_indexed_field("foo", [8]).remove();
assert_eq!(r#"REMOVE foo[8]"#, remove.to_string());

let update = Update::from(remove);
assert_eq!(r#"REMOVE foo[8]"#, update.to_string());

impl Path

pub fn key(self) -> Key

Turns this Path into a Key, for building a key condition expression.

See also: Key

use dynamodb_expression::{Num, Path};

let key_condition = Path::new_name("id").key().equal(Num::new(42))
    .and(Path::new_name("category").key().begins_with("hardware."));
assert_eq!(r#"id = 42 AND begins_with(category, "hardware.")"#, key_condition.to_string());

Trait Implementations

impl Clone for Path

fn clone(&self) -> Path

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Path

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

Formats the value using the given formatter.

impl Display for Path

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

Formats the value using the given formatter.

impl From<Path> for String

fn from(path: Path) -> Self

Converts to this type from the input type.

impl From<Path> for Vec<Element>

fn from(path: Path) -> Self

Converts to this type from the input type.

impl<T> From<T> for Pathwhere T: Into<Element>,

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T> FromIterator<T> for Pathwhere T: Into<Element>,

fn from_iter<I>(iter: I) -> Selfwhere I: IntoIterator<Item = T>,

Creates a value from an iterator.

impl FromStr for Path

type Err = PathParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Path

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 Ord for Path

fn cmp(&self, other: &Path) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Path

fn eq(&self, other: &Path) -> 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 PartialOrd for Path

fn partial_cmp(&self, other: &Path) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<Path> for Name

fn try_from(path: Path) -> Result<Self, Self::Error>

A Path consisting of a single, unindexed attribute can be converted into a Name.

use dynamodb_expression::path::{Element, Name, Path};

let path: Path = "foo".parse().unwrap();
let name = Name::try_from(path).unwrap();
assert_eq!(Name::from("foo"), name);

If the Path has indexes, or has sub-attributes, it cannot be converted, and the original Path is returned.

let path: Path = "foo[0]".parse().unwrap();
let err = Name::try_from(path.clone()).unwrap_err();
assert_eq!(path, err);

let path: Path = "foo.bar".parse().unwrap();
let err = Name::try_from(path.clone()).unwrap_err();
assert_eq!(path, err);

type Error = Path

The type returned in the event of a conversion error.

impl Eq for Path

impl StructuralEq for Path

impl StructuralPartialEq for Path