kdu_params::parse_string

Parses parameter values for a single attribute from the supplied string. The string may not contain any white space of any form at all. In fact, an error message will generally be produced (through kdu_error) if this requirement is violated.

The syntax of the supplied string may be expressed as "<name>[:<spec>]=<vals>" where "<name>" stands for the name of a paricular attribute, "[...]" denotes an optional sub-string, "<spec>" stands for a tile-, component- or tile-component specifier which may be used to specify the particular object in a cluster in which the attribute is to be set, and "<vals>" stands for a construction which specifies values for the attribute's fields.

The function examines the available attributes in the current object, for one whose name matches the "<name>" portion of the supplied string — i.e., the portion of the string which is delimited by an "=" or a ":" character. If the match fails, and the current object is also the cluster head for the very first cluster in the network of parameter objects describing a particular image (this will generally be a siz_params object in practice), the function proceeds to scan through each cluster in turn, looking for attributes whose name matches the "<name>" prefix of string. Note that this examination of multiple clusters occurs only if the current object is the head of the first cluster. If this process does not turn up a matching attribute in some appropriate cluster, the function returns false.

Once a match is found, the function checks the optional "<spec>" field in the supplied string. This field may contain a tile-specifier of the form "T<num>", a component-specifier of the form "C<num>", or both (in either order). Tile and component numbers start from 0. If a tile- or component-specifier is disallowed by the relevant parameter class, or does not correspond to a valid object, the function generates an appropriate error message through kdu_error. A missing component-specifier means that the string is associated with the tile head object (the one having a component index of -1). Similarly, a missing tile-specifier means that the string is associated with an object with tile index of -1. If no tile- or component-specifier is supplied, the string refers to the first object in which the attribute name was matched, which is either the current object or a cluster head. Remember that cluster heads contain default coding parameters for use in all tile-components of the image except those in which the parameters are explicitly overridden. For more on tiles, components and the multi-dimensional list structure managed by parameter objects, consult the comments appearing with the declaration of kdu_params.

As noted above, the string concludes with parameter values for the relevant attribute; the relevant text immediately follows the "=" character. This "<vals>" portion is structured as a comma-separated list of records, where each record contains one or more fields. Note that multiple records are disallowed unless the MULTI_RECORD flag was supplied when the relevant attribute was defined — i.e., when the relevant parameter class's constructor called the protected define_attribute function.

Within the "<vals>" sub-string, each record consists of one or more fields, surrounded by curly braces. In the special case where there is only one field per record, the braces may optionally be omitted as a convenience. The fields must match the type specifications provided in the pattern string which was supplied to the protected define_attribute function when the attribute was defined. Any failure to obey these rules will cause an informative error message to be generated through kdu_error. Specifically, the following patterns are available (the specific patterns to which any particular attributes fields must conform may be queried by a call to describe_attribute or describe_attributes if desired.)

In the field description pattern: an "I" refers to an integer field; an "F" refers to a floating point value; a "B" refers to a boolean field, taking values of "yes" and "no"; a pattern of the form "(<string1>=<val1>,<string2>=<val2>,...)" refers to an enumerated field, taking one of the values, "<string1>", "<string2>", ..., which are translated into the corresponding integers, "<val1>", "<val2>", ...., respectively; and a pattern of the form "[<string1>=<val1>|<string2>=<val2>|...]" refers to a flags field, taking zero or more of the values, "<string1>", "<string2>", ..., separated by vertical bars, "|", which are translated into corresponding integers, "<val1>", "<val2>", ... and OR'd together.

As an example, the pattern "IIB(go=1,stop=0)" describes a record structure consisting of 4 fields: 2 integer fields; one boolean field; and one enumerated field which must hold one of the strings "go" or "stop". An example of a valid "<vals>" suffix suffix for the string argument setting such an attribute would be "{56,-4,yes,stop},{0,1,no,go}". You will find the pattern strings for each attribute described in the comments appearing with each of the derived parameter classes (e.g., siz_params, cod_params, qcd_params, etc.). Alternatively, you may query the patterns at run-time by calling describe_attribute or describe_attributes, as already mentioned.

In several respects, attribute parsing is unlike the other two methods provided for setting parameter attributes (i.e., the set function and marker segment translation via the translate_marker_segment function). Firstly, it is illegal to parse the same attribute twice — an appropriate error message will be generated through kdu_error if information has already been parsed into the attribute (but not if it has been set using set or translate_marker_segment). The only exception to this rule applies to objects which support multiple instances, in which case a new instance of the object will be created automatically to accommodate multiple occurrences of the same attribute string.

New instances will not be created if previous values were set into an attribute by any means other than string parsing. Quite to the contrary, any information set by any other means is automatically deleted before parsing new information into an attribute. More than that, if the attribute string does not specify a particular component, all values for the relevant attribute will be cleared in all component-specific objects which do not already contain parsed information for that attribute. Similarly, if the attribute string does not specify a particular tile, that attribute's values will be cleared in all tile-component specific objects which do not already contain parsed information for the attribute. This functionality is intended to reflect the most reasonable behaviour for transcoding applications, in which a user may modify some parameter attributes of an existing code-stream; it would be disconcerting to find that tile- or component-specific versions of those same attributes were left intact by a non-specific modification command.

False if no attribute whose name matches that indicated in the "<name>" part of string can be found in the current object or (if the current object is the head of the first cluster) in any cluster in the multi-dimensional list structure.

string [const char *]