Struct xmp_toolkit::XmpMeta

pub struct XmpMeta { /* private fields */ }

An XmpMeta struct allows you to inspect and modify the data model of an XMP packet.

You can create an XmpMeta struct by:

• Creating an empty struct (XmpMeta::new)
• Reading metadata from a file (XmpFile::xmp)
• Parsing a string containing metadata (XmpMeta::from_str)

Accessing properties

Many of the methods on this struct allow you to access or modify a property. Every property in XMP is identified using two arguments:

• namespace may be either a URI or a prefix. If a URI is used, it must have been registered via (XmpMeta::register_namespace) or be built-in to the XMP Toolkit (see xmp_ns for constants you may use in this way). If a prefix is used, it must be a prefix returned after having called XmpMeta::register_namespace. If both a URI and path prefix are present, they must be corresponding parts of a registered namespace.
• path specifies a path to the property. In the simplest case, this is a simple string identifier within namespace, but it can also be a path expression. Must not be an empty string. The first component of a path expression can be a namespace prefix; if so, the prefix must have been registered via XmpMeta::register_namespace.

Implementations

impl XmpMeta

pub const LAST_ITEM: i32 = -1i32

Special index value which references the last item in an array, regardless of the array index.

pub fn new() -> XmpResult<Self>

Creates a new, empty metadata struct.

An error result from this function is unlikely but possible if, for example, the C++ XMP Toolkit fails to initialize or reports an out-of-memory condition.

pub fn from_file<P: AsRef<Path>>(path: P) -> XmpResult<Self>

Reads the XMP from a file without keeping the file open.

This is a convenience function for read-only workflows.

Arguments

• path: Path to the file to be read

pub fn register_namespace(
    namespace_uri: &str,
    suggested_prefix: &str
) -> XmpResult<String>

Registers a namespace URI with a suggested prefix.

If the URI is not registered but the suggested prefix is in use, a unique prefix is created from the suggested one. The actual registered prefix is returned. It is not an error if the URI is already registered, regardless of the prefix.

Arguments

• namespace_uri: The URI for the namespace. Must be a valid XML URI.

• suggested_prefix: The suggested prefix to be used if the URI is not yet registered. Must be a valid XML name.

Returns the prefix actually registered for this URI.

pub fn namespace_prefix(namespace_uri: &str) -> Option<String>

Returns the prefix for a registered namespace URI if it exists.

Arguments

• namespace_uri: The URI for the namespace. Must be a valid XML URI.

pub fn namespace_uri(namespace_prefix: &str) -> Option<String>

Returns the URL for a registered namespace prefix if it exists.

Arguments

• namespace_prefix: The prefix for the namespace.

pub fn debug_dump_namespaces() -> String

Returns a list of registered namespaces as a string.

Intended for debugging/logging use.

pub fn contains_property(&self, namespace: &str, path: &str) -> bool

Returns true if the metadata block contains a property by this name.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return false in such cases.

pub fn contains_struct_field(
    &self,
    struct_ns: &str,
    struct_path: &str,
    field_ns: &str,
    field_name: &str
) -> bool

Returns true if the metadata block contains a struct field by this name.

Arguments

• struct_ns and struct_path: See Accessing properties.
• field_ns and field_name take the same form (i.e. see Accessing properties again.)

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return false in such cases.

pub fn contains_qualifier(
    &self,
    prop_ns: &str,
    prop_path: &str,
    qual_ns: &str,
    qual_name: &str
) -> bool

Returns true if the metadata block contains the named qualifier.

Arguments

• prop_ns and prop_path: See Accessing properties.
• qual and qual_name take the same form (i.e. see Accessing properties again.)

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return false in such cases.

pub fn property(&self, namespace: &str, path: &str) -> Option<XmpValue<String>>

Gets a simple string property value.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

pub fn property_array(&self, namespace: &str, path: &str) -> ArrayProperty<'_>

Creates an iterator for an array property value.

Arguments

• namespace and path: See Accessing properties.

pub fn property_bool(&self, namespace: &str, path: &str) -> Option<XmpValue<bool>>

Gets a simple property value and interprets it as a bool.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

If the value can not be parsed as a boolean (for example, it is an unrecognizable string), the function will return None.

pub fn property_i32(&self, namespace: &str, path: &str) -> Option<XmpValue<i32>>

Gets a simple property value and interprets it as a 32-bit integer.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

If the value can not be parsed as a number, the function will return None.

pub fn property_i64(&self, namespace: &str, path: &str) -> Option<XmpValue<i64>>

Gets a simple property value and interprets it as a 64-bit integer.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

If the value can not be parsed as a number, the function will return None.

pub fn property_f64(&self, namespace: &str, path: &str) -> Option<XmpValue<f64>>

Gets a simple property value and interprets it as a 64-bit float.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

If the value can not be parsed as a number, the function will return None. Note that ratio values, such as those found in TIFF and EXIF blocks, are not parsed.

pub fn property_date(
    &self,
    namespace: &str,
    path: &str
) -> Option<XmpValue<XmpDateTime>>

Gets a simple property value and interprets it as a date/time value.

Arguments

• namespace and path: See Accessing properties.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

If the value can not be parsed as a date (for example, it is an unrecognizable string), the function will return None.

pub fn struct_field(
    &self,
    struct_ns: &str,
    struct_path: &str,
    field_ns: &str,
    field_name: &str
) -> Option<XmpValue<String>>

Gets a field value from within an nested structure.

Arguments

• struct_ns and struct_path: See Accessing properties.
• field_ns and field_name take the same form (i.e. see Accessing properties again.)

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

pub fn set_property(
    &mut self,
    namespace: &str,
    path: &str,
    new_value: &XmpValue<String>
) -> XmpResult<()>

Creates or sets a property value.

This is the simplest property setter. Use it for top-level simple properties.

Arguments

• namespace and path: See Accessing properties.
• new_value: The new value.

pub fn set_property_bool(
    &mut self,
    namespace: &str,
    path: &str,
    new_value: &XmpValue<bool>
) -> XmpResult<()>

Creates or sets a property value using a bool value.

Since XMP only stores strings, the bool value will be converted to a string ("True" or "False") as part of this operation.

Arguments

• namespace and path: See Accessing properties.
• new_value: The new value.

pub fn set_property_i32(
    &mut self,
    namespace: &str,
    path: &str,
    new_value: &XmpValue<i32>
) -> XmpResult<()>

Creates or sets a property value using a 32-bit integer value.

Since XMP only stores strings, the integer value will be converted to a string as part of this operation.

Arguments

• namespace and path: See Accessing properties.
• new_value: The new value.

pub fn set_property_i64(
    &mut self,
    namespace: &str,
    path: &str,
    new_value: &XmpValue<i64>
) -> XmpResult<()>

Creates or sets a property value using a 64-bit integer value.

Since XMP only stores strings, the integer value will be converted to a string as part of this operation.

Arguments

• namespace and path: See Accessing properties.
• new_value: The new value.

pub fn set_property_f64(
    &mut self,
    namespace: &str,
    path: &str,
    new_value: &XmpValue<f64>
) -> XmpResult<()>

Creates or sets a property value using a 64-bit floating-point value.

Since XMP only stores strings, the float value will be converted to a string as part of this operation.

Arguments

• namespace and path: See Accessing properties.
• new_value: The new value.

pub fn set_property_date(
    &mut self,
    namespace: &str,
    path: &str,
    new_value: &XmpValue<XmpDateTime>
) -> XmpResult<()>

Creates or sets a property value using an XmpDateTime structure.

Since XMP only stores strings, the date/time will be converted to ISO 8601 format as part of this operation.

Arguments

• namespace and path: See Accessing properties.
• new_value: The new value.

pub fn delete_property(&mut self, namespace: &str, path: &str) -> XmpResult<()>

Deletes an XMP subtree rooted at a given property.

It is not an error if the qualifier does not exist.

Arguments

• namespace and path: See Accessing properties.

pub fn array_item(
    &self,
    namespace: &str,
    array_name: &str,
    item_index: i32
) -> Option<XmpValue<String>>

Provides access to items within an array.

Use XmpMeta::compose_array_item_path() to create a complex path.

Arguments

• namespace and array_name: See Accessing properties.
• item_index: Index into the array. IMPORTANT: Indices in XMP are 1-based, unlike Rust where indices are typically 0-based. Use XmpMeta::LAST_ITEM to specify the last existing array item.

pub fn set_array_item(
    &mut self,
    namespace: &str,
    array_name: &str,
    item_placement: ItemPlacement,
    item_value: &XmpValue<String>
) -> XmpResult<()>

Creates or sets the value of an item within an array.

Items are accessed by an integer index, where the first item has index

1. This function creates the item if necessary, but the array itself must already exist. Use XmpMeta::append_array_item() to create arrays. A new item is automatically appended if the index is the array size plus 1.

Use XmpMeta::compose_array_item_path() to create a complex path.

Arguments

• namespace and array_name: See Accessing properties. NOTE: array_name is an XmpValue<String> which contains any necessary flags for the array.
• item_placement: Describes where to place the new item. See ItemPlacement.
• item_value: Contains value and flags for the item to be added to the array.

pub fn append_array_item(
    &mut self,
    namespace: &str,
    array_name: &XmpValue<String>,
    item_value: &XmpValue<String>
) -> XmpResult<()>

Adds an item to an array, creating the array if necessary.

This function simplifies construction of an array by not requiring that you pre-create an empty array. The array that is assigned is created automatically if it does not yet exist. If the array exists, it must have the form specified by the flags on array_name.

Each call appends a new item to the array.

Use XmpMeta::compose_array_item_path() to create a complex path.

Arguments

• namespace and array_name: See Accessing properties. NOTE: array_name is an XmpValue<String> which contains any necessary flags for the array.
• item_value: Contains value and flags for the item to be added to the array.

pub fn delete_array_item(
    &mut self,
    namespace: &str,
    array_name: &str,
    item_index: i32
) -> XmpResult<()>

Deletes an XMP subtree rooted at a given array item.

It is not an error if the array item does not exist. Use XmpMeta::compose_array_item_path() to create a complex path.

Arguments

• namespace and array_name: See Accessing properties. NOTE: array_name is an XmpValue<String> which contains any necessary flags for the array.
• item_index: The index of the desired item. Use XmpMeta::LAST_ITEM to specify the last existing array item. IMPORTANT: Indices in XMP are 1-based, not zero-based as in most of Rust.

pub fn array_len(&self, array_ns: &str, array_name: &str) -> usize

Reports the number of items currently defined in an array.

Arguments

• array_ns and array_name: See Accessing properties.

If any error occurs (for instance, the array does not exist), this function will return 0.

pub fn set_struct_field(
    &mut self,
    namespace: &str,
    struct_name: &str,
    field_ns: &str,
    field_name: &str,
    item_value: &XmpValue<String>
) -> XmpResult<()>

Creates or sets the value of a field within a nested structure, using a string value.

Use this function to set a value within an existing structure, create a new field within an existing structure, or create an empty structure of any depth. If you set a field in a structure that does not exist, the structure is automatically created.

Use XmpMeta::compose_struct_field_path() to create a complex path.

Arguments

• namespace and struct_name: See Accessing properties.
• field_ns and field_name take the same form (i.e. see Accessing properties again.)
• item_value: Contains value and flags for the item to be added to the struct.

pub fn delete_struct_field(
    &mut self,
    namespace: &str,
    struct_name: &str,
    field_ns: &str,
    field_name: &str
) -> XmpResult<()>

Deletes an XMP subtree rooted at a given struct field.

It is not an error if the field does not exist.

Use XmpMeta::compose_struct_field_path() to create a complex path.

Arguments

• namespace and struct_name: See Accessing properties.
• field_ns and field_name take the same form (i.e. see Accessing properties again.)

pub fn qualifier(
    &self,
    prop_ns: &str,
    prop_path: &str,
    qual_ns: &str,
    qual_name: &str
) -> Option<XmpValue<String>>

Provides access to a qualifier attached to a property.

Arguments

• prop_ns and prop_path: See Accessing properties.
• qual_ns and qual_name take the same form (i.e. see Accessing properties again.)

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return None in such cases.

pub fn set_qualifier(
    &mut self,
    namespace: &str,
    prop_name: &str,
    qual_ns: &str,
    qual_name: &str,
    qual_value: &XmpValue<String>
) -> XmpResult<()>

Creates or sets a qualifier attached to a property.

Use this to set a value for an existing qualifier, or create a new qualifier.

Use XmpMeta::compose_qualifier_path() to create a complex path.

Arguments

• namespace and prop_name: See Accessing properties. The name of the property to which the qualifier is attached.
• qual_ns and qual_name take the same form (i.e. see Accessing properties again.) Specifies the qualifier.
• qual_value: Contains value and flags for the qualifier to be added to the property.

pub fn delete_qualifier(
    &mut self,
    prop_ns: &str,
    prop_name: &str,
    qual_ns: &str,
    qual_name: &str
) -> XmpResult<()>

Deletes an XMP subtree rooted at a given qualifier.

It is not an error if the qualifier does not exist.

Arguments

• prop_ns and prop_name: See Accessing properties.
• qual_ns and qual_name take the same form (i.e. see Accessing properties again.)

pub fn localized_text(
    &self,
    namespace: &str,
    path: &str,
    generic_lang: Option<&str>,
    specific_lang: &str
) -> Option<(XmpValue<String>, String)>

Retrieves information about a selected item from an alt-text array.

Localized text properties are stored in alt-text arrays. They allow multiple concurrent localizations of a property value, for example a document title or copyright in several languages. These functions provide convenient support for localized text properties, including a number of special and obscure aspects. The most important aspect of these functions is that they select an appropriate array item based on one or two RFC 3066 language tags. One of these languages, the “specific” language, is preferred and selected if there is an exact match. For many languages it is also possible to define a “generic” language that can be used if there is no specific language match. The generic language must be a valid RFC 3066 primary subtag, or the empty string.

For example, a specific language of en-US should be used in the US, and a specific language of en-UK should be used in England. It is also appropriate to use en as the generic language in each case. If a US document goes to England, the en-US title is selected by using the en generic language and the en-UK specific language.

It is considered poor practice, but allowed, to pass a specific language that is just an RFC 3066 primary tag. For example en is not a good specific language, it should only be used as a generic language. Passing i or x as the generic language is also considered poor practice but allowed.

Advice from the W3C about the use of RFC 3066 language tags can be found at https://www.w3.org/International/articles/language-tags/.

Note: RFC 3066 language tags must be treated in a case insensitive manner. The XMP toolkit does this by normalizing their capitalization:

• The primary subtag is lower case, the suggested practice of ISO 639.
• All 2-letter secondary subtags are upper case, the suggested practice of ISO 3166.
• All other subtags are lower case. The XMP specification defines an artificial language, x-default, that is used to explicitly denote a default item in an alt-text array. The XMP toolkit normalizes alt-text arrays such that the x-default item is the first item. The XmpMeta::set_localized_text() function has several special features related to the x-default item. See its description for details. The array item is selected according to these rules:
• Look for an exact match with the specific language.
• If a generic language is given, look for a partial match.
• Look for an x-default item.
• Choose the first item.

A partial match with the generic language is where the start of the item’s language matches the generic string and the next character is -. An exact match is also recognized as a degenerate case.

You can pass x-default as the specific language. In this case, selection of an x-default item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to produce a match.

Arguments

• namespace and path: See Accessing properties.
• generic_lang: The name of the generic language as an RFC 3066 primary subtag. Can be None or the empty string if no generic language is wanted.
• specific_lang: The name of the specific language as an RFC 3066 tag, or x-default. Must not be an empty string.

Return value

If a suitable match is found, returns Some(XmpValue<String>, String) where the second string is the actual language that was matched.

Error handling

Any errors (for instance, empty or invalid namespace or property name) are ignored; the function will return false in such cases.

pub fn set_localized_text(
    &mut self,
    namespace: &str,
    path: &str,
    generic_lang: Option<&str>,
    specific_lang: &str,
    item_value: &str
) -> XmpResult<()>

Modifies the value of a selected item in an alt-text array using a string object.

Creates an appropriate array item if necessary, and handles special cases for the x-default item.

The array item is selected according to these rules:

• Look for an exact match with the specific language.
• If a generic language is given, look for a partial match.
• Look for an x-default item.
• Choose the first item.

A partial match with the generic language is where the start of the item’s language matches the generic string and the next character is -. An exact match is also recognized as a degenerate case.

You can pass x-default as the specific language. In this case, selection of an x-default item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to produce a match.

Item values are modified according to these rules:

• If the selected item is from a match with the specific language, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.
• If the selected item is from a match with the generic language and there are no other generic matches, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.
• If the selected item is from a partial match with the generic language and there are other partial matches, a new item is created for the specific language. The x-default item is not modified.
• If the selected item is from the last 2 rules then a new item is created for the specific language. If the array only had an x-default item, the x-default item is also modified. If the array was empty, items are created for the specific language and x-default.

pub fn compose_array_item_path(
    array_ns: &str,
    array_path: &str,
    index: i32
) -> XmpResult<String>

Composes the path expression for an item in an array.

Arguments

• array_ns and array_path: See Accessing properties.
• item_index: The index of the desired item. Use XmpMeta::LAST_ITEM to specify the last existing array item. IMPORTANT: Indices in XMP are 1-based, not zero-based as in most of Rust.

Return

If successful, the returned string is in the form array_name[array_index].

pub fn compose_qualifier_path(
    schema_ns: &str,
    prop_path: &str,
    qual_ns: &str,
    qual_name: &str
) -> XmpResult<String>

Composes the path expression for a qualifier.

Arguments

• schema_ns and prop_path: See Accessing properties.
• qual_ns and qual_name take the same form (i.e. see Accessing properties again.)

Return

If successful, the returned string is in the form schema_ns:prop_name/?qual_ns:qual_name.

pub fn compose_struct_field_path(
    struct_ns: &str,
    struct_path: &str,
    field_ns: &str,
    field_name: &str
) -> XmpResult<String>

Composes the path expression for a field in a struct.

Arguments

• struct_ns and struct_path: See Accessing properties.
• field_ns and field_name take the same form (i.e. see Accessing properties again.)

Return

If successful, the returned string is in the form struct_ns:struct_name/field_ns:field_name.

pub fn name(&self) -> String

Returns the client-assigned name of this XMP object.

This name is the empty string by default.

See also XmpMeta::set_name.

pub fn set_name(&mut self, name: &str) -> XmpResult<()>

Assigns a name to this XMP object.

This name can be retrieved via XmpMeta::name.

This name is for client use only and it not interpreted by the XMP Toolkit.

pub fn from_str_with_options(s: &str, options: FromStrOptions) -> XmpResult<Self>

Creates a new XmpMeta struct and populates it with metadata from a string containing serialized RDF. This string must be a complete RDF parse stream.

pub fn to_string_with_options(
    &self,
    options: ToStringOptions
) -> XmpResult<String>

Converts metadata in this XMP object into a string as RDF.

This struct also implements std::fmt::Display which will provide a reasonable default behavior via XmpMeta::to_string().

Use this function, together with ToStringOptions if you need more control over output formats.

impl<'a> XmpMeta

pub fn iter(&'a self, options: IterOptions) -> XmpIterator<'a>

Returns an iterator over the schema and properties within an XMP object.

The top of the XMP data tree is a single root node. This does not explicitly in an iteration.

Beneath the root are schema nodes; these collect the top-level properties in the same namespace. They are created and destroyed implicitly.

Beneath the schema nodes are the property nodes. The nodes below a property node depend on its type (simple, struct, or array) and whether it has qualifiers.

The IterOptions struct defines a starting point for the iteration, and options that control how it proceeds. By default, iteration starts at the root and visits all nodes beneath it in a depth-first manner. The root node iteself is not visited; the first visited node is a schema node. You can provide a schema name or property path to select a different starting node. By default, this visits the named root node first then all nodes beneath it in a depth-first manner.

Trait Implementations

impl Clone for XmpMeta

fn clone(&self) -> Self

Returns a deep copy of the XMP metadata packet.

In the unlikely event of a C++ error reported from the underlying C++ XMP Toolkit operation, this function will fail silently and generate an empty XMP data model.

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

Performs copy-assignment from source.

impl Debug for XmpMeta

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

Formats the value using the given formatter.

impl Default for XmpMeta

fn default() -> Self

Returns the “default value” for a type.

impl Display for XmpMeta

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

Convert the XMP data model to RDF using a compact formatting.

impl Drop for XmpMeta

fn drop(&mut self)

Executes the destructor for this type.

impl FromStr for XmpMeta

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

Creates a new XmpMeta struct and populates it with metadata from a string containing serialized RDF. This string must be a complete RDF parse stream.

Arguments

• s: XMP string to be read

type Err = XmpError

The associated error which can be returned from parsing.