Struct Transaction 

pub struct Transaction<'a, 'pg, St> { /* private fields */ }

Transaction for modifying properties within a PropertyGroup.

Transaction uses a type-state pattern where methods are only available in particular states. The lifecycle of a Transaction is:

1. Begin in the TransactionReset state
2. Call Transaction::start() to begin the transaction, transitioning to the TransactionStarted state.
3. Call any number of methods to delete, add, or change properties. A given property may only have one entry in a single transaction.
4. Either call Transaction::reset() (return to 1) or Transaction::commit() to commit the transaction. On success, transitions to the terminal TransactionCommitted state; on “out of date” (i.e., the property group was concurrently modified), transitions back to the reset state (1).

Implementations

impl<'a, 'pg, St> Transaction<'a, 'pg, St>

pub fn reset(self) -> Transaction<'a, 'pg, TransactionReset>

Reset the transaction, clearing any pending entries.

pub fn is_empty(&self) -> bool

Returns true if this transaction has no entries.

impl<'a, 'pg> Transaction<'a, 'pg, TransactionReset>

pub fn start( self, ) -> Result<Transaction<'a, 'pg, TransactionStarted>, TransactionBuildError>

Start the transaction.

Committing a transaction will return TransactionCommitResult::OutOfDate if the property group is modified between start() and commit().

impl<'a, 'pg> Transaction<'a, 'pg, TransactionStarted>

pub fn property_delete( &mut self, name: &str, ) -> Result<(), TransactionBuildError>

Delete a property by name.

pub fn property_new( &mut self, name: &str, value: ValueRef<'_>, ) -> Result<(), TransactionBuildError>

Add a new property with a single value.

Errors

This method will fail if the property already exists. Consider Transaction::property_ensure() for “add or update” semantics.

pub fn property_new_multiple<'b, I>( &mut self, name: &str, value_kind: ValueKind, values: I, ) -> Result<(), TransactionBuildError>

where I: IntoIterator<Item = ValueRef<'b>>,

Add a new property with the given values.

Errors

This method will fail if the property already exists or if any element of values has a kind inconsistent with value_kind. Consider Transaction::property_ensure_multiple() for “add or update” semantics.

pub fn property_change( &mut self, name: &str, value: ValueRef<'_>, ) -> Result<(), TransactionBuildError>

Change an existing property to have a single value.

Errors

This method will fail if the property does not exist or if the type of value is not consistent with the existing property value(s). Consider Transaction::property_ensure() for “add or update” semantics.

pub fn property_change_multiple<'b, I>( &mut self, name: &str, value_kind: ValueKind, values: I, ) -> Result<(), TransactionBuildError>

where I: IntoIterator<Item = ValueRef<'b>>,

Change an existing property to have the given values.

Errors

This method will fail if the property does not exist, if any element of values has a kind inconsistent with value_kind, or if value_kind is not consistent with the existing property value(s). Consider Transaction::property_ensure_multiple() for “add or update” semantics.

pub fn property_change_type( &mut self, name: &str, value: ValueRef<'_>, ) -> Result<(), TransactionBuildError>

Change an existing property to have a single value, changing its type if necessary.

Errors

This method will fail if the property does not exist. Consider Transaction::property_ensure() for “add or update” semantics.

pub fn property_change_type_multiple<'b, I>( &mut self, name: &str, value_kind: ValueKind, values: I, ) -> Result<(), TransactionBuildError>

where I: IntoIterator<Item = ValueRef<'b>>,

Change an existing property to have the given values, changing its type if necessary.

Errors

This method will fail if the property does not exist or if any element of values has a kind inconsistent with value_kind. Consider Transaction::property_ensure_multiple() for “add or update” semantics.

pub fn property_ensure( &mut self, name: &str, value: ValueRef<'_>, ) -> Result<(), TransactionBuildError>

Ensure a property exists with the given single value.

This method will create the property if it does not exist, and will change its value (and type if necessary) if it does.

pub fn property_ensure_multiple<'b, I>( &mut self, name: &str, value_kind: ValueKind, values: I, ) -> Result<(), TransactionBuildError>

where I: IntoIterator<Item = ValueRef<'b>>,

Ensure a property exists with the given values.

This method will create the property if it does not exist, and will change its values (and type if necessary) if it does.

Errors

Fails if any element of values has a kind inconsistent with value_kind.

pub fn commit( self, ) -> Result<TransactionCommitResult<'a, 'pg>, TransactionCommitError>

Commit this transaction.

Trait Implementations

impl<'a, 'pg, St: Debug> Debug for Transaction<'a, 'pg, St>

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

Formats the value using the given formatter.