Struct xmp_toolkit::XmpMeta
source · pub struct XmpMeta { /* private fields */ }
Expand description
Represents 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
).
There are many methods on this struct which allow you to inspect and modify the XMP data model.
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 (seexmp_ns
for constants you may use in this way). If a prefix is used, it must be a prefix returned after having calledXmpMeta::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 withinnamespace
, 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 viaXmpMeta::register_namespace
.
Implementations§
source§impl XmpMeta
impl XmpMeta
sourcepub const LAST_ITEM: i32 = -1i32
pub const LAST_ITEM: i32 = -1i32
Special index value which references the last item in an array, regardless of the array index.
sourcepub fn new() -> XmpResult<Self>
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.
sourcepub fn from_file<P: AsRef<Path>>(path: P) -> XmpResult<Self>
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
sourcepub fn register_namespace(
namespace_uri: &str,
suggested_prefix: &str
) -> XmpResult<String>
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.
IMPORTANT: Namespace registrations are global state in the C++ XMP Toolkit and not related to any single data model. For this reason, the corresponding function (i.e. to unregister a namespace) is not provided.
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.
sourcepub fn namespace_prefix(namespace_uri: &str) -> Option<String>
pub fn namespace_prefix(namespace_uri: &str) -> Option<String>
Returns the prefix for a registered namespace URI if it exists.
IMPORTANT: Namespace registrations are global state in the C++ XMP Toolkit and not related to any single data model.
Arguments
namespace_uri
: The URI for the namespace. Must be a valid XML URI.
sourcepub fn namespace_uri(namespace_prefix: &str) -> Option<String>
pub fn namespace_uri(namespace_prefix: &str) -> Option<String>
Returns the URL for a registered namespace prefix if it exists.
IMPORTANT: Namespace registrations are global state in the C++ XMP Toolkit and not related to any single data model.
Arguments
namespace_prefix
: The prefix for the namespace.
sourcepub fn debug_dump_namespaces() -> String
pub fn debug_dump_namespaces() -> String
Returns a list of registered namespaces as a string.
Intended for debugging/logging use.
IMPORTANT: Namespace registrations are global state in the C++ XMP Toolkit and not related to any single data model.
sourcepub fn contains_property(&self, namespace: &str, path: &str) -> bool
pub fn contains_property(&self, namespace: &str, path: &str) -> bool
Returns true
if the metadata block contains a property by this name.
Arguments
namespace
andpath
: 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.
sourcepub fn contains_struct_field(
&self,
struct_ns: &str,
struct_path: &str,
field_ns: &str,
field_name: &str
) -> bool
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
andstruct_path
: See Accessing properties.field_ns
andfield_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.
sourcepub fn contains_qualifier(
&self,
prop_ns: &str,
prop_path: &str,
qual_ns: &str,
qual_name: &str
) -> bool
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
andprop_path
: See Accessing properties.qual
andqual_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.
sourcepub fn property(&self, namespace: &str, path: &str) -> Option<XmpValue<String>>
pub fn property(&self, namespace: &str, path: &str) -> Option<XmpValue<String>>
Gets a simple string property value.
Arguments
namespace
andpath
: 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.
sourcepub fn property_array(&self, namespace: &str, path: &str) -> ArrayProperty<'_> ⓘ
pub fn property_array(&self, namespace: &str, path: &str) -> ArrayProperty<'_> ⓘ
Creates an iterator for an array property value.
Arguments
namespace
andpath
: See Accessing properties.
sourcepub fn property_bool(
&self,
namespace: &str,
path: &str
) -> Option<XmpValue<bool>>
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
andpath
: 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
.
sourcepub fn property_i32(&self, namespace: &str, path: &str) -> Option<XmpValue<i32>>
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
andpath
: 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
.
sourcepub fn property_i64(&self, namespace: &str, path: &str) -> Option<XmpValue<i64>>
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
andpath
: 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
.
sourcepub fn property_f64(&self, namespace: &str, path: &str) -> Option<XmpValue<f64>>
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
andpath
: 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.
sourcepub fn property_date(
&self,
namespace: &str,
path: &str
) -> Option<XmpValue<XmpDateTime>>
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
andpath
: 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
.
sourcepub fn struct_field(
&self,
struct_ns: &str,
struct_path: &str,
field_ns: &str,
field_name: &str
) -> Option<XmpValue<String>>
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
andstruct_path
: See Accessing properties.field_ns
andfield_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.
sourcepub fn set_property(
&mut self,
namespace: &str,
path: &str,
new_value: &XmpValue<String>
) -> XmpResult<()>
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
andpath
: See Accessing properties.new_value
: The new value.
sourcepub fn set_property_bool(
&mut self,
namespace: &str,
path: &str,
new_value: &XmpValue<bool>
) -> XmpResult<()>
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
andpath
: See Accessing properties.new_value
: The new value.
sourcepub fn set_property_i32(
&mut self,
namespace: &str,
path: &str,
new_value: &XmpValue<i32>
) -> XmpResult<()>
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
andpath
: See Accessing properties.new_value
: The new value.
sourcepub fn set_property_i64(
&mut self,
namespace: &str,
path: &str,
new_value: &XmpValue<i64>
) -> XmpResult<()>
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
andpath
: See Accessing properties.new_value
: The new value.
sourcepub fn set_property_f64(
&mut self,
namespace: &str,
path: &str,
new_value: &XmpValue<f64>
) -> XmpResult<()>
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
andpath
: See Accessing properties.new_value
: The new value.
sourcepub fn set_property_date(
&mut self,
namespace: &str,
path: &str,
new_value: &XmpValue<XmpDateTime>
) -> XmpResult<()>
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
andpath
: See Accessing properties.new_value
: The new value.
sourcepub fn delete_property(&mut self, namespace: &str, path: &str) -> XmpResult<()>
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
andpath
: See Accessing properties.
sourcepub fn array_item(
&self,
namespace: &str,
array_name: &str,
item_index: i32
) -> Option<XmpValue<String>>
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
andarray_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. UseXmpMeta::LAST_ITEM
to specify the last existing array item.
sourcepub fn set_array_item(
&mut self,
namespace: &str,
array_name: &str,
item_placement: ItemPlacement,
item_value: &XmpValue<String>
) -> XmpResult<()>
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
- 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
andarray_name
: See Accessing properties. NOTE:array_name
is anXmpValue<String>
which contains any necessary flags for the array.item_placement
: Describes where to place the new item. SeeItemPlacement
.item_value
: Contains value and flags for the item to be added to the array.
sourcepub fn append_array_item(
&mut self,
namespace: &str,
array_name: &XmpValue<String>,
item_value: &XmpValue<String>
) -> XmpResult<()>
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
andarray_name
: See Accessing properties. NOTE:array_name
is anXmpValue<String>
which contains any necessary flags for the array.item_value
: Contains value and flags for the item to be added to the array.
sourcepub fn delete_array_item(
&mut self,
namespace: &str,
array_name: &str,
item_index: i32
) -> XmpResult<()>
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
andarray_name
: See Accessing properties. NOTE:array_name
is anXmpValue<String>
which contains any necessary flags for the array.item_index
: The index of the desired item. UseXmpMeta::LAST_ITEM
to specify the last existing array item. IMPORTANT: Indices in XMP are 1-based, not zero-based as in most of Rust.
sourcepub fn array_len(&self, array_ns: &str, array_name: &str) -> usize
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
andarray_name
: See Accessing properties.
If any error occurs (for instance, the array does not exist), this function will return 0.
sourcepub fn set_struct_field(
&mut self,
namespace: &str,
struct_name: &str,
field_ns: &str,
field_name: &str,
item_value: &XmpValue<String>
) -> XmpResult<()>
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
andstruct_name
: See Accessing properties.field_ns
andfield_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.
sourcepub fn delete_struct_field(
&mut self,
namespace: &str,
struct_name: &str,
field_ns: &str,
field_name: &str
) -> XmpResult<()>
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
andstruct_name
: See Accessing properties.field_ns
andfield_name
take the same form (i.e. see Accessing properties again.)
sourcepub fn qualifier(
&self,
prop_ns: &str,
prop_path: &str,
qual_ns: &str,
qual_name: &str
) -> Option<XmpValue<String>>
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
andprop_path
: See Accessing properties.qual_ns
andqual_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.
sourcepub fn set_qualifier(
&mut self,
namespace: &str,
prop_name: &str,
qual_ns: &str,
qual_name: &str,
qual_value: &XmpValue<String>
) -> XmpResult<()>
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
andprop_name
: See Accessing properties. The name of the property to which the qualifier is attached.qual_ns
andqual_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.
sourcepub fn delete_qualifier(
&mut self,
prop_ns: &str,
prop_name: &str,
qual_ns: &str,
qual_name: &str
) -> XmpResult<()>
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
andprop_name
: See Accessing properties.qual_ns
andqual_name
take the same form (i.e. see Accessing properties again.)
sourcepub fn localized_text(
&self,
namespace: &str,
path: &str,
generic_lang: Option<&str>,
specific_lang: &str
) -> Option<(XmpValue<String>, String)>
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. TheXmpMeta::set_localized_text
function has several special features related to thex-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
andpath
: See Accessing properties.generic_lang
: The name of the generic language as an RFC 3066 primary subtag. Can beNone
or the empty string if no generic language is wanted.specific_lang
: The name of the specific language as an RFC 3066 tag, orx-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 None
in such cases.
sourcepub fn set_localized_text(
&mut self,
namespace: &str,
path: &str,
generic_lang: Option<&str>,
specific_lang: &str,
item_value: &str
) -> XmpResult<()>
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, thex-default
item is also modified. If the array only has 1 existing item (which is notx-default
), anx-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, thex-default
item is also modified. If the array only has 1 existing item (which is notx-default
), anx-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, thex-default
item is also modified. If the array was empty, items are created for the specific language andx-default
.
sourcepub fn compose_array_item_path(
array_ns: &str,
array_path: &str,
index: i32
) -> XmpResult<String>
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
andarray_path
: See Accessing properties.item_index
: The index of the desired item. UseXmpMeta::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 value
If successful, the returned string is in the form
array_name[array_index]
.
sourcepub fn compose_lang_selector(
schema_ns: &str,
array_name: &str,
lang_name: &str
) -> XmpResult<String>
pub fn compose_lang_selector( schema_ns: &str, array_name: &str, lang_name: &str ) -> XmpResult<String>
Composes the path expression to select an alternate item by language.
Path syntax allows two forms of “content addressing” to select an item
in an array of alternatives. The form used in this function lets you
select an item in an alt-text array based on the value of its
xml:lang
qualifier. The other form of content addressing is shown
in XmpMeta::compose_field_selector
.
Arguments
schema_ns
andarray_name
: See Accessing properties.lang_name
: The RFC 3066 code for the desired language.
Return
If successful, the returned string is in the form
schema_ns:array_name[@xml:lang='lang_name']
, where schema_ns
is the
prefix for the schema namespace.
This function provides a path expression that is explicitly and only for
a specific language. In most cases,
XmpMeta::set_localized_text
and XmpMeta::localized_text
are
preferred, because they provide extra logic to choose the appropriate
language and maintain consistency with the x-default
value.
sourcepub fn compose_field_selector(
schema_ns: &str,
struct_name: &str,
field_ns: &str,
field_name: &str,
field_value: Option<&str>
) -> XmpResult<String>
pub fn compose_field_selector( schema_ns: &str, struct_name: &str, field_ns: &str, field_name: &str, field_value: Option<&str> ) -> XmpResult<String>
Composes a path expression to select an alternate item by a field’s value.
Path syntax allows two forms of “content addressing” to select an item
in an array of alternatives. The form used in this function lets you
select an item in an array of structs based on the value of one of the
fields in the structs. The other form of content addressing is shown in
XmpMeta::compose_lang_selector
.
Arguments
schema_ns
andstruct_name
: See Accessing properties.field_ns
andfield_name
: See Accessing properties again.field_value
: The desired value of the field, specified as a string object.
Example
Consider a simple struct that has two fields, the name of a city and the URI of an FTP site in that city. Use this to create an array of download alternatives. You can show the user a popup built from the values of the city fields, then get the corresponding URI as follows:
use xmp_toolkit::{XmpMeta, XmpResult};
XmpMeta::register_namespace("ns:struct_example/", "struct")?;
XmpMeta::register_namespace("ns:field_example/", "field")?;
let meta = XmpMeta::default();
let path = XmpMeta::compose_field_selector(
"ns:struct_example/",
"Downloads",
"ns:field_example/",
"City",
Some("Seattle"),
)?;
assert_eq!(path, "Downloads[field:City=\"Seattle\"]");
println!(
"field {} exists: {}",
path,
meta.struct_field("ns:struct_example/", &path, "ns:field_example/", "URI")
.is_some()
);
Return value
If successful, the returned string is in the form `schema_ns:struct_name[field_ns:field_name=‘field_value’].
sourcepub fn compose_qualifier_path(
schema_ns: &str,
prop_path: &str,
qual_ns: &str,
qual_name: &str
) -> XmpResult<String>
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
andprop_path
: See Accessing properties.qual_ns
andqual_name
take the same form (i.e. see Accessing properties again.)
Return value
If successful, the returned string is in the form
schema_ns:prop_name/?qual_ns:qual_name
.
sourcepub fn compose_struct_field_path(
struct_ns: &str,
struct_path: &str,
field_ns: &str,
field_name: &str
) -> XmpResult<String>
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
andstruct_path
: See Accessing properties.field_ns
andfield_name
take the same form (i.e. see Accessing properties again.)
Return value
If successful, the returned string is in the form
struct_ns:struct_name/field_ns:field_name
.
sourcepub fn sort(&mut self) -> XmpResult<()>
pub fn sort(&mut self) -> XmpResult<()>
Sorts the data model tree of an XMP object.
Use this function to sort the data model of an XMP object into a
canonical order. This can be convenient when comparing data models,
(e.g. by text comparison of {:#?}
output).
At the top level the namespaces are sorted by their prefixes. Within a
namespace, the top level properties are sorted by name. Within a struct,
the fields are sorted by their qualified name, i.e. their XML
prefix:local
form. Unordered arrays of simple items are sorted by
value. Language Alternative arrays are sorted by the xml:lang
qualifiers, with the x-default
item placed first.
If this function is not called, the data model will typically appear in order of construction. In other words, content parsed from a file or string will appear in the order that it did in the source material. Properties added subsequently will generally be appended in the order of addition within each container.
sourcepub fn name(&self) -> String
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
.
sourcepub fn set_name(&mut self, name: &str) -> XmpResult<()>
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.
sourcepub fn from_str_with_options(
s: &str,
options: FromStrOptions
) -> XmpResult<Self>
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.
sourcepub fn to_string_with_options(
&self,
options: ToStringOptions
) -> XmpResult<String>
pub fn to_string_with_options( &self, options: ToStringOptions ) -> XmpResult<String>
Converts metadata in this XMP object into a string as RDF.
In many cases, this struct’s implementation of Display
will provide reasonable default behavior. (In other words,
you can often call xmp.to_string()
or include an XmpMeta
object directly in a format string).
Use this function, together with ToStringOptions
if you
need more control over output formats.
source§impl<'a> XmpMeta
impl<'a> XmpMeta
sourcepub fn iter(&'a self, options: IterOptions) -> XmpIterator<'a> ⓘ
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§
source§impl Clone for XmpMeta
impl Clone for XmpMeta
source§fn clone(&self) -> Self
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.
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl FromStr for XmpMeta
impl FromStr for XmpMeta
impl Send for XmpMeta
Per XMP Toolkit SDK Programmer’s Guide, section Multi-threading in the API:
The functions in XMPCore and XMPFiles are thread safe. You must call the initialization and termination functions in a single-threaded manner; between those calls, you can use threads freely, following a multi-read, single-writer locking model. All locking is automatic and transparent.