The query functions described below return the null object (as opposed to an empty string or a zero number) if:
The location path does not point to a leaf property (i.e. the property is not present or it is present but it is an array or a struct rather than a leaf).
The string value does not conform to the format for the requested data type.
Returns the value of the leaf property at the specified XMP location path.
Same as getString but interprets the string as a decimal number (with or without a decimal point) or as a rational number (two decimal integer numbers separated by a forward slash). For example, "1.25" and "5/4" represent the same number.
Same as getString but interprets the string as a Boolean value. The preferred strings are "True" and "False". If these do not match, a case insensitive comparison is tried, then simply "t" or "f", and finally non-zero and zero integer representations.
Same as getString but interprets the string as a date-time in the ISO 8601 format. The class of the returned Date object is specific to the scripting environment in use.
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.
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 may 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.
RFC 3066 language tags must be treated in a case insensitive manner.
The XMP specification defines an artificial language, "x-default", that is used to explicitly denote a default item in an alt-text array. The localized text functions have several special features related to the x-default item.
The selection of the array item is performed as follows:
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.
It is fine to 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.
Returns the localized string in the specified alt-text array selected according to the rules described above or null if there is no such string (even no default).