Functions | |
| int | cif_value_create (cif_kind_tp kind, cif_value_tp **value) |
| Allocates and initializes a new value object of the specified kind. | |
| void | cif_value_clean (cif_value_tp *value) |
| Frees any resources associated with the provided value object without freeing the object itself, changing it into an instance of the explicit unknown value. | |
| void | cif_value_free (cif_value_tp *value) |
| Frees the specified value object and all resources associated with it. | |
| int | cif_value_clone (cif_value_tp *value, cif_value_tp **clone) |
| Creates an independent copy of a CIF value object. | |
| int | cif_value_init (cif_value_tp *value, cif_kind_tp kind) |
| Reinitializes the provided value object to a default value of the specified kind. | |
| int | cif_value_init_char (cif_value_tp *value, UChar *text) |
(Re)initializes the specified value object as being of kind CIF_CHAR_KIND, with the specified text | |
| int | cif_value_copy_char (cif_value_tp *value, const UChar *text) |
| (Re)initializes the specified value object as being of kind CIF_CHAR_KIND, with a copy of the specified text. | |
| int | cif_value_parse_numb (cif_value_tp *numb, UChar *text) |
| Parses the specified Unicode string to produce a floating-point number and its standard uncertainty, recording them in the provided value object. | |
| int | cif_value_init_numb (cif_value_tp *numb, double val, double su, int scale, int max_leading_zeroes) |
(Re)initializes the given value as a number with the specified value and uncertainty, with a number of significant figures determined by the specified scale | |
| int | cif_value_autoinit_numb (cif_value_tp *numb, double val, double su, unsigned int su_rule) |
(Re)initializes the given value as a number with the specified value and uncertainty, automatically choosing the number of significant digits to keep based on the specified su and su_rule. | |
| cif_kind_tp | cif_value_kind (cif_value_tp *value) |
| Returns the kind code of the specified value. | |
| cif_quoted_tp | cif_value_is_quoted (cif_value_tp *value) |
| Returns whether the value should be interpreted as if it were presented quoted. | |
| int | cif_value_set_quoted (cif_value_tp *value, cif_quoted_tp quoted) |
| Sets whether the value should be interpreted as if it were presented quoted. | |
| int | cif_value_get_number (cif_value_tp *numb, double *val) |
| Returns the value represented by the given number value object. | |
| int | cif_value_get_su (cif_value_tp *numb, double *su) |
| Returns the uncertainty of the value represented by the given number value object. | |
| int | cif_value_get_text (cif_value_tp *value, UChar **text) |
| Retrieves the text representation of the specified value. | |
| int | cif_value_get_element_count (cif_value_tp *value, size_t *count) |
| Determines the number of elements of a composite data value. | |
| int | cif_value_get_element_at (cif_value_tp *value, size_t index, cif_value_tp **element) |
| Retrieves an element of a list value by its index. | |
| int | cif_value_set_element_at (cif_value_tp *value, size_t index, cif_value_tp *element) |
| Replaces an existing element of a list value with a different value. | |
| int | cif_value_insert_element_at (cif_value_tp *value, size_t index, cif_value_tp *element) |
| Inserts an element into the specified list value at the specified position, pushing back the elements (if any) initially at that and following positions. | |
| int | cif_value_remove_element_at (cif_value_tp *value, size_t index, cif_value_tp **element) |
| Removes an existing element from a list value, optionally returning it to the caller. | |
| int | cif_value_get_keys (cif_value_tp *table, const UChar ***keys) |
| Retrieves an array of the keys of a table value. | |
| int | cif_value_set_item_by_key (cif_value_tp *table, const UChar *key, cif_value_tp *item) |
| Associates a specified value and key in the provided table value. | |
| int | cif_value_get_item_by_key (cif_value_tp *table, const UChar *key, cif_value_tp **value) |
| Looks up a table entry by key and optionally returns the associated value. | |
| int | cif_value_remove_item_by_key (cif_value_tp *table, const UChar *key, cif_value_tp **value) |
| Removes an item from a table value, optionally returning the value. | |
CIF data values are represented by and to CIF API functions via the opaque data type cif_value_tp . Because this type is truly opaque, cif_value_tp objects cannot directly be declared. Independent value objects must instead be created via function cif_value_create(), and independent ones should be released via cif_value_free() when they are no longer needed. Unlike the "handles" on CIF structural components that are used in several other parts of the API, cif_value_tp objects are complete data objects, independent from the backing CIF storage mechanism, albeit sometimes parts of larger aggregate value objects.
CIF permits values' interpretations to be sensitive to whether they are presented whitespace-delimited string form as opposed to being presented in one of the quoted string forms. The CIF API in fact builds in one such distinction in its provision for value kinds CIF_UNK_KIND and CIF_NA_KIND (see below). Technically, that is a matter of convention rather than one of the underlying CIF format or data model, but recognition of the special significance of the values attributed to these kinds is essentially universal.
The API classifies values into several distinct "kinds": character (Unicode string) values, apparently-numeric values, list values, table values, unknown-value place holders, and not-applicable/default-value place holders. These alternatives are represented by the enumeration cif_kind_tp. Value kinds are assigned when values are created, but may be changed by re-initialization. Several functions serve this purpose: cif_value_init(), of course, but also cif_value_init_char(), cif_value_copy_char(), cif_value_parse_numb(), cif_value_init_numb(), and cif_value_autoinit_numb(). Additionally, values of character kind and suitable content will be automatically coerced to numeric kind by functions cif_value_get_number() and cif_value_get_su(), and under some circumstances, values will be coerced between character and n/a or unknown-value kind via function cif_value_set_quoted(). If it is not known, the kind of a value object can be determined via cif_value_kind(); this is important, because many of the value manipulation functions are useful only for values of certain kinds.
Values of list and table kind aggregate other value objects. The aggregates do not accept independent value objects directly into themselves; instead they make copies of values entered into them so as to reduce confusion about object ownership. Such internal copies can still be exposed outside their container objects, however, to reduce copying and facilitate value manipulation. Value objects that belong to a list or table aggregate are dependent on their container object, and must not be directly freed.
Table values associate other values with Unicode string keys. Unlike CIF data values and keywords, table keys are not "case insensitive". They do, however, take Unicode canonical equivalence into account, thus Unicode strings containing different sequences of characters and yet canonically equivalent to each other can be used interchangeably as table keys. When keys are enumerated via cif_value_get_keys(), the form of the key most recently used to enter a value into the table is the form provided. Table keys may contain whitespace, including leading and trailing whitespace, which is significant. The Unicode string consisting of zero characters is a valid table key.
| int cif_value_autoinit_numb | ( | cif_value_tp * | numb, | |
| double | val, | |||
| double | su, | |||
| unsigned int | su_rule | |||
| ) |
(Re)initializes the given value as a number with the specified value and uncertainty, automatically choosing the number of significant digits to keep based on the specified su and su_rule.
Any previous contents of the provided value are released, as if by cif_value_clean().
The number's text representation will be formatted with a standard uncertainty if and only if the given su is greater than zero. In that case, the provided su_rule governs the number of decimal digits with which the value text is formatted, and the number of digits of value and su that are recorded. The largest scale is chosen such that the significant digits of the rounded su, interpreted as an integer, are less than or equal to the su_rule. The most commonly used su_rule is probably 19, but others are used as well, including at least 9, 27, 28, 29, and 99. The su_rule must be at least 2, and behavior is undefined if its decimal representation has more significant digits than the implementation-defined maximum decimal precision of a double. If su_rule is less than 6 then some standard uncertainties may be foratted as (0) in the value's text representation.
If the su is exactly zero then all significant digits are recorded to represent the exact value of val. The su_rule is ignored in this case, and no su is included in the text representation.
The value's text representation is expressed in scientific notation if it would otherwise have more than five leading zeroes or any trailing insignificant zeroes. Otherwise, it is expressed in plain decimal notation.
The value is marked as not quoted; provided it has suitable form, it can subsequently be marked quoted via cif_value_set_quoted().
Behavior is undefined if val or su has a value that does not correspond to a finite real number (i.e. if one of those values represents an infinite value or does not represent any number at all).
| [in,out] | numb | a pointer to the number value object to initialize |
| [in] | val | the numeric value to assign to the number |
| [in] | su | the absolute numeric standard uncertainty in the specified value; must not be negative |
| [in] | su_rule | governs rounding of the value and uncertainty; it is a "rule" in the sense that the rounding conventions it governs are sometimes referred to by names of form "rule of 19" |
CIF_ERROR ) on failure. | void cif_value_clean | ( | cif_value_tp * | value | ) |
Frees any resources associated with the provided value object without freeing the object itself, changing it into an instance of the explicit unknown value.
This function's primary uses are internal, but it is available for anyone to use. External code more often wants cif_value_free() instead. This function does not directly affect any managed CIF.
| [in,out] | value | a valid pointer to the value object to clean |
CIF_OK on success. In principle, an error code such as CIF_ERROR is returned on failure, but no specific failure conditions are currently defined. | int cif_value_clone | ( | cif_value_tp * | value, | |
| cif_value_tp ** | clone | |||
| ) |
Creates an independent copy of a CIF value object.
For composite values (LIST and TABLE), the result is a deep clone -- all members of the original value are themselves cloned, recursively, to create the members of the cloned result. If the referent of the clone parameter is not NULL, then the object it points to is first cleaned up as if by cif_value_clean(), then overwritten with the cloned data; otherwise, a new value object is allocated and a pointer to it is written where clone points.
| [in] | value | a pointer to the value object to clone |
| [in,out] | clone | the location where a pointer to the cloned value should be made to reside, either by replacing the contents of an existing value object or by recording a pointer to a new one; must not be NULL. If *clone is not NULL then it must point to a valid cif value object. |
CIF_OK on success, or an error code (typically CIF_ERROR ) on failure | int cif_value_copy_char | ( | cif_value_tp * | value, | |
| const UChar * | text | |||
| ) |
(Re)initializes the specified value object as being of kind CIF_CHAR_KIND, with a copy of the specified text.
This function performs the same job as cif_value_init_char(), except that it makes a copy of the value text. Responsibility for the text argument does not change, and the value object does not become sensitive to change via the text pointer. Unlike cif_value_init_char(), this function is thus suitable for use with initialization text that resides on the stack (e.g. in a local array variable) or in read-only memory.
The value is marked as quoted; provided it has suitable form, it can subsequently be marked unquoted via cif_value_set_quoted().
| [in,out] | value | a pointer to the value object to be initialized; must not be NULL |
| [in] | text | the new text content for the specified value object; must not be NULL |
CIF_OK on success, or an error code (typically CIF_ERROR ) on failure| int cif_value_create | ( | cif_kind_tp | kind, | |
| cif_value_tp ** | value | |||
| ) |
Allocates and initializes a new value object of the specified kind.
The new object is initialized with a kind-dependent default value:
CIF_CHAR_KIND CIF_NUMB_KIND CIF_LIST_KIND or CIF_TABLE_KIND, respectively CIF_UNK_KIND and CIF_NA_KIND)For CIF_CHAR_KIND and CIF_NUMB_KIND, however, it is somewhat more efficient to create a value object of kind CIF_UNK_KIND and then initialize it with the appropriate kind-specific function.
| [in] | kind | the value kind to create |
| [in,out] | value | the location where a pointer to the new value should be recorded; must not be NULL. The initial value of *value is ignored. |
CIF_OK on success or an error code (typically CIF_ERROR ) on failure | void cif_value_free | ( | cif_value_tp * | value | ) |
Frees the specified value object and all resources associated with it.
This provides only resource management; it has no effect on any managed CIF. This function is a safe no-op when its argument is NULL.
| [in,out] | value | a valid pointer to the value object to free, or NULL |
| int cif_value_get_element_at | ( | cif_value_tp * | value, | |
| size_t | index, | |||
| cif_value_tp ** | element | |||
| ) |
Retrieves an element of a list value by its index.
A pointer to the actual value object contained in the list is returned, so modifications to the value will be reflected in the list. If that is not desired then the caller can make a copy via cif_value_clone() . The caller must not free the returned value, but may modify it in any other way.
It is unsafe for the caller to retain the provided element pointer if and when the list that owns the element ceases to be under its exclusive control, for the lifetime of the referenced value object is then uncertain. It will not outlive the list that owns it, but various operations on the list may cause it to be discarded while the list is still live. Note in particular that a context switch to another thread that has access to the list object constitutes passing out of the caller's control. If multiple threads have unsynchronized concurrent access to the list then no element retrieved from it via this function is ever safe to use, not even to clone it.
| [in] | value | a pointer to the CIF_LIST_KIND value from which to retrieve an element |
| [in] | index | the zero-based index of the requested element; must be less than the number of elements in the list |
| [out] | element | the location where a pointer to the requested value should be written; must not be NULL |
CIF_ARGUMENT_ERROR if the value has kind different from CIF_LIST_KIND; otherwise returns CIF_OK if index is less than the number of elements in the list, else CIF_INVALID_INDEX . | int cif_value_get_element_count | ( | cif_value_tp * | value, | |
| size_t * | count | |||
| ) |
Determines the number of elements of a composite data value.
Composite values are those having kind CIF_LIST_KIND or CIF_TABLE_KIND . For the purposes of this function, the "elements" of a table are its key/value pairs . Only the direct elements of a list or table are counted, not the elements of any lists or tables nested within.
| [in] | value | a pointer to the value object whose elements are to be counted; must not be NULL |
| [out] | count | a pointer to a location where the number of elements should be recorded |
CIF_OK if the value has kind CIF_LIST_KIND or CIF_TABLE_KIND, otherwise CIF_ARGUMENT_ERROR | int cif_value_get_item_by_key | ( | cif_value_tp * | table, | |
| const UChar * | key, | |||
| cif_value_tp ** | value | |||
| ) |
Looks up a table entry by key and optionally returns the associated value.
If the key is present in the table and the value argument is non-NULL, then a pointer to the value associated with the key is written where value points. Otherwise, this function simply indicates via its return value whether the specified key is present in the table. Any value object provided via the value parameter continues to be owned by the table. It must not be freed, and any modifications to it will be reflected in the table. If that is not desired then the caller can make a copy of the value via cif_value_clone() .
| [in] | table | a pointer to the table value in which to look up the specified key |
| [in] | key | the key to look up, as a NUL-terminated Unicode string. |
| [in,out] | value | if not NULL, the location where a pointer to the discovered value, if any, should be written |
CIF_ARGUMENT_ERROR if the value has kind different from CIF_TABLE_KIND , otherwise CIF_OK if the key was found in the table or CIF_NOSUCH_ITEM if the key was not found. CIF_ERROR is returned in the event of a failure other than those already described, but no such failure conditions are currently defined.| int cif_value_get_keys | ( | cif_value_tp * | table, | |
| const UChar *** | keys | |||
| ) |
Retrieves an array of the keys of a table value.
Although tables are insensitive to differences between canonically equivalent keys, this function always provides keys in the form most recently entered into the table.
The caller assumes responsibility for freeing the returned array itself, but not the keys in it. The keys remain the responsibility of the table, and MUST NOT be freed or modified in any way. Each key is a NUL-terminated Unicode string, and the end of the list is marked by a NULL element.
| [in] | table | a pointer to the table value whose keys are requested |
| [out] | keys | the location where a pointer to the array of keys should be written; must not be NULL. |
CIF_ARGUMENT_ERROR if the table has kind different from CIF_TABLE_KIND , otherwise CIF_OK if the keys were successfully retrieved, or CIF_ERROR , if retrieving the keys fails for reasons other than those already described | int cif_value_get_number | ( | cif_value_tp * | numb, | |
| double * | val | |||
| ) |
Returns the value represented by the given number value object.
If the provided value is of character kind then first an attempt is made to convert it to numeric kind, as if by parsing its text value via cif_value_parse_numb(). If the value is not initially of numeric kind, then this function's success depends on such a conversion.
Behavior is implementation-defined if the represented numeric value is outside the representable range of type double . Some of the possible behaviors include raising a floating-point trap and returning a special value, such as an IEEE infinity.
| [in] | numb | a pointer the the value object whose numeric value is requested |
| [in,out] | val | a pointer to the location where the numeric value should be recorded; must be a valid pointer to suitably-aligned storage large enough to accommodate a double. |
CIF_OK on success, CIF_INVALID_NUMBER if the provided object is of character kind and cannot be parsed as a number, CIF_ARGUMENT_ERROR if the provided object is othewise not of numeric kind, or another code, typically CIF_ERROR, if an error occurs. | int cif_value_get_su | ( | cif_value_tp * | numb, | |
| double * | su | |||
| ) |
Returns the uncertainty of the value represented by the given number value object.
If the provided value is of character kind then first an attempt is made to convert it to numeric kind, as if by parsing its text value via cif_value_parse_numb(). If the value is not initially of numeric kind, then this function's success depends on such a conversion.
The uncertainty is zero for an exact number. Behavior is implementation-defined if the uncertainty is outside the representable range of type double .
| [in] | numb | a pointer the the value object whose numeric standard uncertainty is requested |
| [in,out] | su | a pointer to the location where the uncertainty should be recorded; must be a valid pointer to suitably aligned storage large enough to accommodate a double. |
CIF_OK on success, CIF_INVALID_NUMBER if the provided object is of character kind and cannot be parsed as a number, CIF_ARGUMENT_ERROR if the provided object is othewise not of numeric kind, or another code, typically CIF_ERROR, if an error occurs. | int cif_value_get_text | ( | cif_value_tp * | value, | |
| UChar ** | text | |||
| ) |
Retrieves the text representation of the specified value.
It is important to understand that the "text representation" provided by this function is not the same as the CIF format representation in which the same value might be serialized to a CIF file. Instead, it is the parsed text representation, so, among other things, it omits any CIF delimiters and might not adhere to CIF line length limits.
The value text, if any, obtained via this function belongs to then caller.
This function is natural for values of kind CIF_CHAR_KIND. It is also fairly natural for values of kind CIF_NUMB_KIND, as those carry a text representation with them to allow for undelimited number-like values that are intended to be interpreted as text. It is natural, but trivial, for kinds CIF_NA_KIND and CIF_UNK_KIND, for which the text representation is NULL (as opposed to empty). It is decidedly unnatural, however, for the composite value kinds CIF_LIST_KIND and CIF_TABLE_KIND. As such, the text for values of those kinds is also NULL, though that is subject to change in the future.
| [in] | value | a pointer to the value object whose text is requested |
| [in,out] | text | the location where a pointer to copy of the value text (or NULL, as appropriate) should be recorded; must not be NULL |
CIF_OK on success, or CIF_ERROR on failure | int cif_value_init | ( | cif_value_tp * | value, | |
| cif_kind_tp | kind | |||
| ) |
Reinitializes the provided value object to a default value of the specified kind.
The value referenced by the provided handle should have been allocated via cif_value_create(). Any unneeded resources it holds are released. The specified value kind does not need to be the same as the value's present kind. Kind-specific default values are documented as with cif_value_create().
This function is equivalent to cif_value_clean() when the specified kind is CIF_UNK_KIND, and it is less useful than the character- and number-specific (re)initialization functions. It is the only means available to change an existing general value in-place to a list, table, or N/A value, however, and it can be used to efficently empty a list or table value.
On failure, the value is left in a valid but otherwise unspecified state.
| [in,out] | value | a handle on the value to reinitialize; must not be NULL |
| [in] | kind | the cif value kind as which the value should be reinitialized |
CIF_OK on success, or an error code (typically CIF_ERROR ) on failure | int cif_value_init_char | ( | cif_value_tp * | value, | |
| UChar * | text | |||
| ) |
(Re)initializes the specified value object as being of kind CIF_CHAR_KIND, with the specified text
Any previous contents of the provided value object are first cleaned as if by cif_value_clean(). Responsibility for the provided string passes to the value object; it should not subsequently be managed directly by the caller. This implies that the text must be dynamically allocated. The value object will become sensitive to text changes performed afterward via the text pointer. This behavior could be described as wrapping an existing Unicode string in a CIF value object.
The value is marked as quoted; provided it has suitable form, it can subsequently be marked unquoted via cif_value_set_quoted().
| [in,out] | value | a pointer to the value object to be initialized; must not be NULL |
| [in] | text | the new text content for the specified value object; must not be NULL |
CIF_OK on success, or an error code (typically CIF_ERROR ) on failure| int cif_value_init_numb | ( | cif_value_tp * | numb, | |
| double | val, | |||
| double | su, | |||
| int | scale, | |||
| int | max_leading_zeroes | |||
| ) |
(Re)initializes the given value as a number with the specified value and uncertainty, with a number of significant figures determined by the specified scale
Any previous contents of the provided value are released, as if by cif_value_clean() .
The value's text representation will be formatted with a standard uncertainty if and only if the given standard uncertainty (su ) is greater than zero. It is an error for the uncertainty to be less than zero, but it may be exactly equal to zero.
The scale gives the number of significant digits to the right of the units digit; the value and uncertainty will be rounded or extended to this number of decimal places as needed. Any rounding is performed according to the floating-point rounding mode in effect at that time. The scale may be less than zero, indicating that the units digit and possibly some of the digits to its left are insignificant and not to be recorded. If the given su rounds to exactly zero at the specified scale, then the resulting number object represents an exact number, whether the su given was itself exactly zero or not.
If the scale is less than zero or if pure decimal notation would require more than max_leading_zeroes leading zeroes after the decimal point, then the number's text representation is formatted in scientific notation (d.ddde+-dd; the number of digits of mantissa and exponent may vary). Otherwise, it is formatted in decimal notation.
It is an error if a text representation consistent with the arguments would require more characters than the CIF 2.0 maximum line length (2048 characters).
The value is marked as not quoted; provided it has suitable form, it can subsequently be marked quoted via cif_value_set_quoted().
The behavior of this function is constrained by the characteristics of the data type (double ) of the value and su parameters. Behavior is undefined if a scale is specified that exceeds the maximum possible precision of a value of type double, or such that 10^(-scale) is greater than the greatest representable finite double. Behavior is undefined if val or su has a value that does not correspond to a finite real number (i.e. if one of those values represents an infinite value or does not represent any number at all).
| [in,out] | numb | a pointer to the value object to initialize |
| [in] | val | the numeric value to assign to the number |
| [in] | su | the absolute numeric standard uncertainty in the specified value |
| [in] | scale | the number of significant digits to the right of the decimal point in both val and su |
| [in] | max_leading_zeroes | the maximimum number of leading zeroes with which the text representation of numbers having absolute value less than 1 will be formatted; must not be less than zero. |
CIF_ERROR ) on failure. | int cif_value_insert_element_at | ( | cif_value_tp * | value, | |
| size_t | index, | |||
| cif_value_tp * | element | |||
| ) |
Inserts an element into the specified list value at the specified position, pushing back the elements (if any) initially at that and following positions.
The provided value is copied into the list (if not NULL); responsibility for the original object is not transferred. The list may be extended by inserting at the index one past its last element.
| [in,out] | value | a pointer to the list value to modify |
| [in] | index | the zero-based index of the element to replace; must be less than or equal to the number of elements in the list |
| [in] | element | a pointer to the value to insert, or NULL to insert a CIF_UNK_KIND value |
CIF_ARGUMENT_ERROR if the value has kind different from CIF_LIST_KIND , otherwise CIF_INVALID_INDEX if the index is greater than the initial number of list elements, or CIF_OK if a value was successfully inserted, or CIF_ERROR , if inserting the value fails for reasons other than those already described| cif_quoted_tp cif_value_is_quoted | ( | cif_value_tp * | value | ) |
Returns whether the value should be interpreted as if it were presented quoted.
Unlike most CIF functions, the return value is not an error code, as no error conditions are defined for or detectable by this function.
| [in] | value | a pointer to the value object whose quoting status is requested; must point at an initialized value |
| cif_kind_tp cif_value_kind | ( | cif_value_tp * | value | ) |
Returns the kind code of the specified value.
Unlike most CIF functions, the return value is not an error code, as no error conditions are defined for or detectable by this function.
| [in] | value | a pointer to the value object whose kind is requested; must point at an initialized value |
| int cif_value_parse_numb | ( | cif_value_tp * | numb, | |
| UChar * | text | |||
| ) |
Parses the specified Unicode string to produce a floating-point number and its standard uncertainty, recording them in the provided value object.
For success, the entire input string must be successfully parsed. On success (only), any previous contents of the value object are released as if by cif_value_clean() ; otherwise, the value object is not modified. The value object takes ownership of the parsed text on success. The caller is responsible for ensuring that the text pointer is not afterward used to modify its referrent. The representable values that can be initialized in this manner are not limited to those representable the machine's native floating-point format.
This behavior could be described as wrapping an existing Unicode string in a (numeric) CIF value object.
The value is marked as not quoted; provided it has suitable form, it can subsequently be marked quoted via cif_value_set_quoted().
| [in,out] | numb | the value object into which to parse the text |
| [in] | text | the text to parse as a NUL-terminated Unicode string, in one of the forms documented forms documented for numbers in CIF text |
CIF_OK on success, or else an error code characterizing the nature of the failure, normally one of: CIF_INVALID_NUMBER if the text cannot be fully parsed as a number CIF_ERROR in most other cases | int cif_value_remove_element_at | ( | cif_value_tp * | value, | |
| size_t | index, | |||
| cif_value_tp ** | element | |||
| ) |
Removes an existing element from a list value, optionally returning it to the caller.
Any elements following the removed one in the list are moved forward to fill the gap. The removed element is returned via the element parameter if that parameter is not NULL; in that case the caller assumes responsibility for freeing that value when it is no longer needed. Otherwise, the value is freed by this function.
| [in,out] | value | the list value to modify |
| [in] | index | the zero-based index of the element to remove; must be less than the initial number of elements in the list |
| [in,out] | element | if not NULL, then a pointer to the removed element is written at this location |
CIF_ARGUMENT_ERROR if the value has kind different from CIF_LIST_KIND , otherwise CIF_INVALID_INDEX if the index is greater than the initial number of list elements, else CIF_OK if a value was successfully inserted CIF_ERROR may be returned if removing the value fails for reasons other than those already described, but no such failure conditions are currently defined| int cif_value_remove_item_by_key | ( | cif_value_tp * | table, | |
| const UChar * | key, | |||
| cif_value_tp ** | value | |||
| ) |
Removes an item from a table value, optionally returning the value.
If the key is present in the table and the value parameter is non-NULL, then a pointer to the value associated with the key is written where value points, and the caller assumes responsibility for freeing the value when it is no longer needed. Otherwise, this function automatically frees the value object, if any, of the removed entry.
| [in,out] | table | a pointer to the table value to modify |
| [in] | key | the key of the entry to remove, as a NUL-terminated Unicode string |
| [in,out] | value | if not NULL, the location where a pointer to the removed value, if any, should be written |
CIF_ARGUMENT_ERROR if the value has kind different from CIF_TABLE_KIND , otherwise CIF_OK if the key was found in the table (and the entry removed) or CIF_NOSUCH_ITEM if the key was not found. CIF_ERROR is returned in the event of a failure other than those already described, but no such failure conditions are currently defined.| int cif_value_set_element_at | ( | cif_value_tp * | value, | |
| size_t | index, | |||
| cif_value_tp * | element | |||
| ) |
Replaces an existing element of a list value with a different value.
The provided value is copied into the list (if not NULL); responsibility for the original object is not transferred. The replaced value is first cleaned as if by cif_value_clean(), then the new value is copied onto it. That will be visible to code that holds a reference to the value (obtained via cif_value_get_element_at()).
Special case: if the replacement value is the same object as the one currently at the specified position in the list, then this function succeeds without changing anything.
| [in,out] | value | a pointer to the CIF_LIST_KIND value to modify |
| [in] | index | the zero-based index of the element to replace; must be less than the number of elements in the list |
| [in] | element | a pointer to the replacement value, or NULL to set a CIF_UNK_KIND value |
CIF_ARGUMENT_ERROR if the value has kind different from CIF_LIST_KIND , otherwise CIF_INVALID_INDEX if the index is greater than or equal to the number of list elements, or CIF_OK if a value was successfully set, or CIF_ERROR , if setting the value fails for reasons other than those already described| int cif_value_set_item_by_key | ( | cif_value_tp * | table, | |
| const UChar * | key, | |||
| cif_value_tp * | item | |||
| ) |
Associates a specified value and key in the provided table value.
The value and key are copied into the table; responsibility for the originals does not transfer. If a value was already associated with the given key then it is first cleaned as if by cif_value_clean(), then the new value is copied onto it. That will be visible to code that holds a reference to the value (obtained via cif_value_get_item_by_key()).
Special case: if the item value is the same object as one currently associated with the given key in the table, then this function succeeds without changing anything.
| [in,out] | table | a pointer to the table value to modify |
| [in] | key | the key of the table entry to set or modify, as a NUL-terminated Unicode string; must meet CIF validity criteria |
| [in] | item | a pointer to the value object to enter into the table, or NULL to enter a CIF_UNK_KIND value |
CIF_ARGUMENT_ERROR if the table has kind different from CIF_TABLE_KIND , otherwise CIF_INVALID_INDEX if the given key does not meet CIF validity criteria CIF_OK if the entry was successfully set / updated, or CIF_ERROR , if setting or updating the entry fails for reasons other than those already described| int cif_value_set_quoted | ( | cif_value_tp * | value, | |
| cif_quoted_tp | quoted | |||
| ) |
Sets whether the value should be interpreted as if it were presented quoted.
This function may coerce values in-place between kind CIF_CHAR_KIND and either CIF_UNK_KIND or CIF_NA_KIND. It must must not be called with QUOTED as its second argument when the first has kind CIF_LIST_KIND or CIF_TABLE_KIND.
Values of character kind representing reserved strings (see cif_is_reserved_string()) cannot be set unquoted. Values of list or table kind cannot be set quoted, regardless of their contents. If this function is asked to perform such an action then it will instead return CIF_ARGUMENT_ERROR.
| [in,out] | value | a pointer to the value object whose quoting status is requested; must point at an initialized value |
| [in] | quoted | the quoting status to set |
CIF_ARGUMENT_ERROR or CIF_ERROR ) on failure. In particular, if value is of CHAR kind then a return code of CIF_ARGUMENT_ERROR means the value cannot be presented in CIF unquoted, not even via coercion to a different kind. Copyright 2014, 2015 John C. Bollinger