Main Page | Modules | Compound List | File List | Compound Members | File Members

# TXMPUtils< tStringObj > Class Template Reference

Template class for the XMP Toolkit utility services. More...

`#include <TXMPUtils.hpp>`

List of all members.

## Static Public Member Functions
Path composition functions
These functions provide support for composing path expressions to deeply nested properties. The functions in `TXMPMeta` such as `GetProperty`, `GetArrayItem`, and `GetStructField` provide easy access to top level simple properties, items in top level arrays, and fields of top level structs. They do not provide convenient access to more complex things like fields several levels deep in a complex struct, or fields within an array of structs, or items of an array that is a field of a struct. These functions can also be used to compose paths to top level array items or struct fields so that you can use the binary accessors like `GetProperty_Int`. You can use these functions is to compose a complete path expression, or all but the last component. Suppose you have a property that is an array of integers within a struct. You can access one of the array items like this:
             SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
             SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
             exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
You could also use this code if you want the string form of the integer:
             SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
             xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
Note: It might look confusing that the `schemaNS` is passed in all of the calls above. This is because the XMP toolkit keeps the top level "schema" namespace separate from the rest of the path expression.
void | ComposeArrayItemPath (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_Index itemIndex, tStringObj *fullPath)
| Compose the path expression for an item in an array.
void | ComposeStructFieldPath (XMP_StringPtr schemaNS, XMP_StringPtr structName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, tStringObj *fullPath)
| Compose the path expression for a field in a struct.
void | ComposeQualifierPath (XMP_StringPtr schemaNS, XMP_StringPtr propName, XMP_StringPtr qualNS, XMP_StringPtr qualName, tStringObj *fullPath)
| Compose the path expression for a qualifier.
void | ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr langName, tStringObj *fullPath)
| Compose the path expression to select an alternate item by language.
void | ComposeLangSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, const tStringObj &langName, tStringObj *fullPath)
| This form of `ComposeLangSelector` is a simple overload in the template that calls the above form passing `langName.c_str()`.
void | ComposeFieldSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, XMP_StringPtr fieldValue, tStringObj *fullPath)
| Compose the path expression to select an alternate item by a field's value.
void | ComposeFieldSelector (XMP_StringPtr schemaNS, XMP_StringPtr arrayName, XMP_StringPtr fieldNS, XMP_StringPtr fieldName, const tStringObj &fieldValue, tStringObj *fullPath)
| This form of ComposeFieldSelector is a simple overload in the template that calls the above form passing `fieldValue.c_str()`.
Binary-String conversion functions
void | ConvertFromBool (bool binValue, tStringObj *strValue)
| Convert from Boolean to string.
void | ConvertFromInt (long binValue, XMP_StringPtr format, tStringObj *strValue)
| Convert from integer to string.
void | ConvertFromFloat (double binValue, XMP_StringPtr format, tStringObj *strValue)
| Convert from floating point to string.
void | ConvertFromDate (const XMP_DateTime &binValue, tStringObj *strValue)
| Convert from date/time to string.
bool | ConvertToBool (XMP_StringPtr strValue)
| Convert from string to Boolean.
bool | ConvertToBool (const tStringObj &strValue)
| This form of `ConvertToBool` is a simple overload in the template that calls the above form passing `strValue.c_str()`.
long | ConvertToInt (XMP_StringPtr strValue)
| Convert from string to integer.
long | ConvertToInt (const tStringObj &strValue)
| This form of `ConvertToInt` is a simple overload in the template that calls the above form passing `strValue.c_str()`.
long long | ConvertToInt64 (XMP_StringPtr strValue)
| Convert from string to 64 bit integer.
long long | ConvertToInt64 (const tStringObj &strValue)
| This form of ConvertToInt64 is a simple overload in the template that calls the above form passing `strValue.c_str()`.
double | ConvertToFloat (XMP_StringPtr strValue)
| Convert from string to floating point.
double | ConvertToFloat (const tStringObj &strValue)
| This form of `ConvertToFloat` is a simple overload in the template that calls the above form passing `strValue.c_str()`.
void | ConvertToDate (XMP_StringPtr strValue, XMP_DateTime *binValue)
| Convert from string to date/time.
void | ConvertToDate (const tStringObj &strValue, XMP_DateTime *binValue)
| This form of `ConvertToDate` is a simple overload in the template that calls the above form passing s`strValue.c_str()`.
Date/Time functions
void | CurrentDateTime (XMP_DateTime *time)
| Obtain the current date and time.
void | SetTimeZone (XMP_DateTime *time)
| Set the local time zone.
void | ConvertToUTCTime (XMP_DateTime *time)
| Make sure a time is UTC.
void | ConvertToLocalTime (XMP_DateTime *time)
| Make sure a time is local.
int | CompareDateTime (const XMP_DateTime &left, const XMP_DateTime &right)
| Compare the order of two date/time values.
Base 64 Encoding and Decoding
void | EncodeToBase64 (XMP_StringPtr rawStr, XMP_StringLen rawLen, tStringObj *encodedStr)
| Convert from raw data to Base64 encoded string.
void | EncodeToBase64 (const tStringObj &rawStr, tStringObj *encodedStr)
| This form of `EncodeToBase64` is a simple overload in the template that calls the above form passing `rawStr.c_str()`, and `rawStr.size()`.
void | DecodeFromBase64 (XMP_StringPtr encodedStr, XMP_StringLen encodedLen, tStringObj *rawStr)
| Decode from Base64 encoded string to raw data.
void | DecodeFromBase64 (const tStringObj &encodedStr, tStringObj *rawStr)
| This form of `DecodeFromBase64` is a simple overload in the template that calls the above form passing `encodedStr.c_str()`, and `encodedStr.size()`.

## Detailed Description

### template<class tStringObj>
class TXMPUtils< tStringObj >

Template class for the XMP Toolkit utility services.

`TXMPUtils` is the template class providing utility services for the XMP Toolkit. It should be instantiated with a string class such as `std::string`. Please read the general toolkit usage notes for information about the overall architecture of the XMP API.

This is a class for C++ scoping purposes only. It has only static functions, you cannot create an object. These are all functions that layer cleanly on top of the core XMP toolkit. The template wraps a string class around the raw XMP API, so that output strings are automatically copied and access is fully thread safe. String objects are only necessary for output strings. Input strings are literals and passed as typical C `const char *`.

The template parameter, class `tStringObj`, must have the following member functions (which match those for `std::string`):

         tStringObj& assign ( const char * str, size_t len )
         size_t size() const
         const char * c_str() const

## Member Function Documentation

template<class tStringObj>
int TXMPUtils< tStringObj >::CompareDateTime | ( | const XMP_DateTime & | left,
|  | const XMP_DateTime & | right
| ) | `[static]`

  | Compare the order of two date/time values. Parameters:
  left | The "lefthand" date/time.
  right | The "righthand" date/time.
Returns: -1 if left is before right 0 if left matches right +1 if left is after right

template<class tStringObj>
void TXMPUtils< tStringObj >::ComposeArrayItemPath | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_Index | itemIndex,
|  | tStringObj * | fullPath
| ) | `[static]`

  | Compose the path expression for an item in an array. Parameters:
  schemaNS | The namespace URI for the array. Must not be null or the empty string.
  arrayName | The name of the array. May be a general path expression, must not be null or the empty string.
  itemIndex | The index of the desired item. Arrays in XMP are indexed from 1. The constant `kXMP_ArrayLastItem` always refers to the last existing array item.
  fullPath | A pointer to the string that will be assigned the composed path. This will be of the form `ns:arrayName[i]`, where "ns" is the prefix for `schemaNS` and "i" is the decimal representation of `itemIndex`. If the value of `itemIndex` is `kXMP_ArrayLastItem`, the path is `ns:arrayName[last()]`.

template<class tStringObj>
void TXMPUtils< tStringObj >::ComposeFieldSelector | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName,
|  | XMP_StringPtr | fieldValue,
|  | tStringObj * | fullPath
| ) | `[static]`

| Compose the path expression to select an alternate item by a field's value. The path syntax allows two forms of "content addressing" that may be used to select an item in an array of alternatives. The form used in `ComposeFieldSelector` 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 `ComposeLangSelector`. For 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. You can then get the corresponding URI as follows:
             ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
             exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
  Parameters:
  schemaNS | The namespace URI for the array. Must not be null or the empty string.
  arrayName | The name of the array. May be a general path expression, must not be null or the empty string.
  fieldNS | The namespace URI for the field used as the selector. Must not be null or the empty string.
  fieldName | The name of the field used as the selector. Must be a simple XML name, must not be null or the empty string. It must be the name of a field that is itself simple.
  fieldValue | The desired value of the field.
  fullPath | A pointer to the string that will be assigned the composed path. This will be of the form `ns:arrayName[fNS:fieldName='fieldValue']`, where "ns" is the prefix for `schemaNS` and "fNS" is the prefix for `fieldNS`.

template<class tStringObj>
void TXMPUtils< tStringObj >::ComposeLangSelector | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | arrayName,
|  | XMP_StringPtr | langName,
|  | tStringObj * | fullPath
| ) | `[static]`

  | Compose the path expression to select an alternate item by language. The path syntax allows two forms of "content addressing" that may be used to select an item in an array of alternatives. The form used in `ComposeLangSelector` 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 `ComposeFieldSelector`. Note: `ComposeLangSelector` does not supplant `SetLocalizedText` or `GetLocalizedText`. They should generally be used, as they provide extra logic to choose the appropriate language and maintain consistency with the 'x-default' value. `ComposeLangSelector` gives you an path expression that is explicitly and only for the language given in the `langName` parameter. Parameters:
  schemaNS | The namespace URI for the array. Must not be null or the empty string.
  arrayName | The name of the array. May be a general path expression, must not be null or the empty string.
  langName | The RFC 3066 code for the desired language.
  fullPath | A pointer to the string that will be assigned the composed path. This will be of the form `ns:arrayName[@xml:lang='langName']`, where "ns" is the prefix for `schemaNS`.

template<class tStringObj>
void TXMPUtils< tStringObj >::ComposeQualifierPath | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | propName,
|  | XMP_StringPtr | qualNS,
|  | XMP_StringPtr | qualName,
|  | tStringObj * | fullPath
| ) | `[static]`

  | Compose the path expression for a qualifier. Parameters:
  schemaNS | The namespace URI for the property to which the qualifier is attached. Must not be null or the empty string.
  propName | The name of the property to which the qualifier is attached. May be a general path expression, must not be null or the empty string.
  qualNS | The namespace URI for the qualifier. May be null or the empty string if the qualifier is in the XML empty namespace.
  qualName | The name of the qualifier. Must be a simple XML name, must not be null or the empty string.
  fullPath | A pointer to the string that will be assigned the composed path. This will be of the form `ns:propName/?qNS:qualName`, where "ns" is the prefix for `schemaNS` and "qNS" is the prefix for `qualNS`.

template<class tStringObj>
void TXMPUtils< tStringObj >::ComposeStructFieldPath | ( | XMP_StringPtr | schemaNS,
|  | XMP_StringPtr | structName,
|  | XMP_StringPtr | fieldNS,
|  | XMP_StringPtr | fieldName,
|  | tStringObj * | fullPath
| ) | `[static]`

  | Compose the path expression for a field in a struct. Parameters:
  schemaNS | The namespace URI for the struct. Must not be null or the empty string.
  structName | The name of the struct. May be a general path expression, must not be null or the empty string.
  fieldNS | The namespace URI for the field. Must not be null or the empty string.
  fieldName | The name of the field. Must be a simple XML name, must not be null or the empty string.
  fullPath | A pointer to the string that will be assigned the composed path. This will be of the form `ns:structName/fNS:fieldName`, where "ns" is the prefix for `schemaNS` and "fNS" is the prefix for `fieldNS`.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromBool | ( | bool | binValue,
|  | tStringObj * | strValue
| ) | `[static]`

  | Convert from Boolean to string. Parameters:
  binValue | The Boolean value to be converted.
  strValue | The string representation of the Boolean. The values used are given by the macros `kXMP_TrueStr` and `kXMP_FalseStr` found in `XMP_Const.h`.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromDate | ( | const XMP_DateTime & | binValue,
|  | tStringObj * | strValue
| ) | `[static]`

  | Convert from date/time to string. Parameters:
  binValue | The `XMP_DateTime` value to be converted.
  strValue | The ISO 8601 string representation of the date/time.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromFloat | ( | double | binValue,
|  | XMP_StringPtr | format,
|  | tStringObj * | strValue
| ) | `[static]`

  | Convert from floating point to string. Parameters:
  binValue | The floating point value to be converted.
  format | Optional C sprintf format for the conversion. Defaults to "%f".
  strValue | The string representation of the floating point value.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertFromInt | ( | long | binValue,
|  | XMP_StringPtr | format,
|  | tStringObj * | strValue
| ) | `[static]`

  | Convert from integer to string. Parameters:
  binValue | The integer value to be converted.
  format | Optional C sprintf format for the conversion. Defaults to "%d".
  strValue | The string representation of the integer.

template<class tStringObj>
bool TXMPUtils< tStringObj >::ConvertToBool | ( | XMP_StringPtr | strValue | ) | `[static]`

  | Convert from string to Boolean. Parameters:
  strValue | The string representation of the Boolean.
Returns: The appropriate C++ bool value for the string. The preferred strings are `kXMP_TrueStr` and `kXMP_FalseStr`. If these do not match, a case insensitive comparison is tried, then simply 't' or 'f', and finally non-zero and zero integer representations.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertToDate | ( | XMP_StringPtr | strValue,
|  | XMP_DateTime * | binValue
| ) | `[static]`

  | Convert from string to date/time. Parameters:
  strValue | The ISO 8601 string representation of the date/time.
  binValue | A pointer to the `XMP_DateTime` variable to be assigned the date/time components.

template<class tStringObj>
double TXMPUtils< tStringObj >::ConvertToFloat | ( | XMP_StringPtr | strValue | ) | `[static]`

  | Convert from string to floating point. Parameters:
  strValue | The string representation of the floating point value.
Returns: The floating point value.

template<class tStringObj>
long TXMPUtils< tStringObj >::ConvertToInt | ( | XMP_StringPtr | strValue | ) | `[static]`

  | Convert from string to integer. Parameters:
  strValue | The string representation of the integer.
Returns: The integer value as a C long.

template<class tStringObj>
long long TXMPUtils< tStringObj >::ConvertToInt64 | ( | XMP_StringPtr | strValue | ) | `[static]`

  | Convert from string to 64 bit integer. Parameters:
  strValue | The string representation of the integer.
Returns: The integer value as a C long long.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertToLocalTime | ( | XMP_DateTime * | time | ) | `[static]`

  | Make sure a time is local. Parameters:
  time | A pointer to the `XMP_DateTime` variable containing the time to be modified. If the time zone is not the local zone, the time is adjusted and the time zone set to be local.

template<class tStringObj>
void TXMPUtils< tStringObj >::ConvertToUTCTime | ( | XMP_DateTime * | time | ) | `[static]`

  | Make sure a time is UTC. Parameters:
  time | A pointer to the `XMP_DateTime` variable containing the time to be modified. If the time zone is not UTC, the time is adjusted and the time zone set to be UTC.

template<class tStringObj>
void TXMPUtils< tStringObj >::CurrentDateTime | ( | XMP_DateTime * | time | ) | `[static]`

  | Obtain the current date and time. Parameters:
  time | A pointer to the `XMP_DateTime` variable to be assigned the current date and time. The returned time is UTC, properly adjusted for the local time zone. The resolution of the time is not guaranteed to be finer than seconds.

template<class tStringObj>
void TXMPUtils< tStringObj >::DecodeFromBase64 | ( | XMP_StringPtr | encodedStr,
|  | XMP_StringLen | encodedLen,
|  | tStringObj * | rawStr
| ) | `[static]`

  | Decode from Base64 encoded string to raw data. Parameters:
  encodedStr | The pointer to encoded data to be converted.
  encodedLen | The length of encoded datavto be converted.
  rawStr | The XMP object to contain the decoded string.

template<class tStringObj>
void TXMPUtils< tStringObj >::EncodeToBase64 | ( | XMP_StringPtr | rawStr,
|  | XMP_StringLen | rawLen,
|  | tStringObj * | encodedStr
| ) | `[static]`

  | Convert from raw data to Base64 encoded string. Parameters:
  rawStr | The pointer to raw data to be converted.
  rawLen | The length of raw data to be converted.
  encodedStr | The XMP object to contain the encoded string.

template<class tStringObj>
void TXMPUtils< tStringObj >::SetTimeZone | ( | XMP_DateTime * | time | ) | `[static]`

  | Set the local time zone. Parameters:
  time | A pointer to the `XMP_DateTime` variable containing the value to be modified. Any existing time zone value is replaced, the other date/time fields are not adjusted in any way.

The documentation for this class was generated from the following file:

- TXMPUtils.hpp