#include <xfn/xfn.h>
FN_composite_name_t *fn_composite_name_create(void);
void fn_composite_name_destroy(FN_composite_name_t *name);
FN_composite_name_t *fn_composite_name_from_string( const FN_string_t *str);
FN_string_t *fn_string_from_composite_name( const FN_composite_name_t *name, unsigned int *status);
FN_composite_name_t *fn_composite_name_copy( const FN_composite_name_t *name);
FN_composite_name_t *fn_composite_name_assign( FN_composite_name_t *dst, const FN_composite_name_t *src);
int fn_composite_name_is_empty( const FN_composite_name_t *name);
unsigned int fn_composite_name_count( const FN_composite_name_t *name);
const FN_string_t *fn_composite_name_first( const FN_composite_name_t *name, void **iter_pos);
const FN_string_t *fn_composite_name_next( const FN_composite_name_t *name, void **iter_pos);
const FN_string_t *fn_composite_name_prev( const FN_composite_name_t *name, void **iter_pos);
const FN_string_t *fn_composite_name_last( const FN_composite_name_t *name, void **iter_pos);
FN_composite_name_t *fn_composite_name_prefix( const FN_composite_name_t *name, const void *iter_pos);
FN_composite_name_t *fn_composite_name_suffix( const FN_composite_name_t *name, const void *iter_pos);
int fn_composite_name_is_equal( const FN_composite_name_t *name, const FN_composite_name_t *name2, unsigned int *status);
int fn_composite_name_is_prefix( const FN_composite_name_t *name, const FN_composite_name_t *prefix, void **iter_pos, unsigned int *status);
int fn_composite_name_is_suffix( const FN_composite_name_t *name, const FN_composite_name_t *suffix, void **iter_pos, unsigned int *status);
int fn_composite_name_prepend_comp( FN_composite_name_t *name, const FN_string_t *newcomp);
int fn_composite_name_append_comp( FN_composite_name_t *name, const FN_string_t *newcomp);
int fn_composite_name_insert_comp( FN_composite_name_t *name, void **iter_pos, const FN_string_t *newcomp);
int fn_composite_name_delete_comp( FN_composite_name_t *name, void **iter_pos);
int fn_composite_name_prepend_name( FN_composite_name_t *name, const FN_composite_name_t *newcomps);
int fn_composite_name_append_name( FN_composite_name_t *name, const FN_composite_name_t *newcomps);
int fn_composite_name_insert_name( FN_composite_name_t *name, void **iter_pos, const FN_composite_name_t *newcomps);
A composite name is represented by an object of type FN_composite_name_t. Each component is a string name, of type FN_string_t, from the namespace of a single naming system. It may be an atomic name or a compound name in that namespace.
fn_composite_name_create creates an FN_composite_name_t object with zero components. Components may be subsequently added to the composite name using the modify operations described below. fn_composite_name_destroy releases any storage associated with the given FN_composite_name_t handle.
fn_composite_name_from_string() creates an FN_composite_name_t from the string str using the XFN composite name syntax. fn_string_from_composite_name() returns the standard string form of the given composite name, by concatenating the components of the composite name in a left to right order, each separated by the XFN component separator.
fn_composite_name_copy() returns a copy of the given composite name object. fn_composite_name_assign() makes a copy of the composite name object pointed to by src and assigns it to dst, releasing any old contents of dst. A pointer to the same object as dst is returned.
fn_composite_name_is_empty() returns 1 if the given composite name is an empty composite name (that is, it consists of a single, empty component name); otherwise, it returns 0. fn_composite_name_count() returns the number of components in the given composite name.
The iteration scheme is based on the exchange of an opaque void * argument, iter_pos, that serves to record the position of the iteration in the sequence. Conceptually, iter_pos records a position between two successive components (or at one of the extreme ends of the sequence).
The function fn_composite_name_first() returns a handle to the FN_string_t that is the first component in the name, and sets iter_pos to indicate the position immediately following the first component. It returns 0 if the name has no components. Thereafter, successive calls of the fn_composite_name_next() function return pointers to the component following the iteration marker, and advance the iteration marker. If the iteration marker is at the end of the sequence, fn_composite_name_next() returns 0. Similarly, fn_composite_name_prev() returns the component preceding the iteration pointer and moves the marker back one component. If the marker is already at the beginning of the sequence, fn_composite_name_prev() returns 0. The function fn_composite_name_last() returns a pointer to the last component of the name and sets the iteration marker immediately preceding this component (so that subsequent calls to fn_composite_name_prev() can be used to step through leading components of the name).
The fn_composite_name_suffix() function returns a composite name consisting of a copy of those components following the supplied iteration marker. The method fn_composite_name_prefix() returns a composite name consisting of those components that precede the iteration marker. Using these functions with an iteration marker that was not initialized using fn_composite_name_first(), fn_composite_name_last(), fn_composite_name_is_prefix(), or fn_composite_name_is_suffix() yields undefined and generally undesirable behavior.
The functions fn_composite_name_is_equal(), fn_composite_name_is_prefix(), and fn_composite_name_is_suffix() test for equality between composite names or between parts of composite names. For these functions, equality is defined as exact string equality, not name equivalence. A name’s syntactic property, such as case-insensitivity, is not taken into account by these functions.
The function fn_composite_name_is_prefix() tests if one composite name is a prefix of another. If so, it returns 1 and sets the iteration marker immediately following the prefix. (For example, a subsequent call to fn_composite_name_suffix() will return the remainder of the name.) Otherwise, it returns 0 and the value of the iteration marker is undefined. The function fn_composite_name_is_suffix() is similar. It tests if one composite name is a suffix of another. If so, it returns 1 and sets the iteration marker immediately preceding the suffix.
The functions fn_composite_name_prepend_comp() and fn_composite_name_append_comp() prepend and append a single component to the given composite name, respectively. These operations invalidate any iteration marker the client holds for that object. fn_composite_name_insert_comp() inserts a single component before iter_pos to the given composite name and sets iter_pos to be immediately after the component just inserted. fn_composite_name_delete_comp() deletes the component located before iter_pos from the given composite name and sets iter_pos back one component.
The functions fn_composite_name_prepend_name(), fn_composite_name_append_name(), and fn_composite_name_insert_name() perform the same update functions as their _comp counterparts, respectively, except that multiple components are being added, rather than single components. For example, fn_composite_name_insert_name() sets iter_pos to be immediately after the name just added.
The update functions fn_composite_name_prepend_comp(), fn_composite_name_append_comp(), fn_composite_name_insert_comp(), fn_composite_name_delete_comp(), and their _name counterparts return 1 if the update was successful; 0 otherwise.
If a function is expected to return a pointer to an object, a NULL pointer (0) is returned if the function fails.