Ubuntu Manpage: VistaIOattribute - representation of a list of name/value pairs

Provided by: libvistaio-dev_1.2.19-1_amd64

NAME

       VistaIOattribute - representation of a list of name/value pairs

SYNOPSIS

       VistaIOAttrList list;

       VistaIOAttrListPosn posn;

DESCRIPTION

Introduction
An attribute associates a value with a name. Generally, various properties of an object
such as an image are described by attributes, each naming one property and specifying that
property's associated value. Attributes are collected into lists, and Vista library
routines are available for accessing and manipulating these lists. A list is referred to
by a pointer of type VistaIOAttrList.

The attribute list representation is closely related to the Vista data file format. Among
other things, attribute lists can represent in memory the contents of Vista data files.

An attribute's name is an alphanumeric string — specifically, a sequence of characters
matching the regular expression [a-zA-Z0-9_.+-]+. (Regular expressions are described in
grep(1).) Attribute names are represented in memory as null-terminated character strings.
They may be 50 character in length.

An attribute's value may be a character string, a (nested) attribute list, or a pointer to
data of a specified type.

• If it's a character string, the string may optionally be interpreted as an number
whenever it is accessed. Library routines exist, for example, that can return a
string's value as a VistaIOShort, or set it with a VistaIOFloat value. The following
representations can be used when accessing character-string attribute values:
VistaIOBit, VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat,
VistaIODouble, VistaIOBoolean, or VistaIOString. An error will be signalled if an
attempt is made to obtain an attribute's value in a representation to which it cannot
be converted.

A character-string attribute value can also be interpreted as a keyword. Again,
conversion between keywords and any desired representation occurs when the attribute
value is accessed. The routines you use to access attribute values allow you to
specify an optional dictionary that describes a mapping between keywords and values.
The form of this dictionary is described by the VistaIOdictionary(3) manual page.
Using a dictionary, for example, you can fetch an attribute's value as a
VistaIOBoolean while converting the keywords false and true to the values 0 and 1.

• An attribute's value may be another attribute list. However, circular references, as
when an attribute list is the value of one of its attributes, are not allowed.

• An attribute's value may be an object with any of the standard object types (e.g., an
image or edge set); or it may be an object of a type that has been registered by the
programmer using the mechanism described in VistaIOtype(3). Because they are
registered, such types are automatically read from data files and written to data
files by library routines such as VistaIOReadFile(3) and VistaIOWriteFile(3).

• An attribute's value may be of type VistaIOBundle, described in VistaIOBundle(3). A
VistaIOBundle can represent an object whose type has not been registered with the
VistaIOtype(3) mechanism, in a way that allows the object to be copied unchanged from
an input data file to an output data file. It's used to represent objects of unknown
type encountered in input data files.

• An attribute's value may be a pointer to an opaque data structure. Such a pointer is
of type VistaIOPointer. Library routines only allow for getting and setting a
VistaIOPointer attribute value; they cannot read VistaIOPointer values from data
files, or write them to data files.

The elements of an attribute list may be accessed by attribute name, in which case each
element should have a unique name and the order of attributes within the list is not
significant. In this form of access the attribute list is treated as a set. Alternatively,
the elements of an attribute list may be accessed by their position within the list, in
which case attribute names needn't be unique and the ordering of list elements is
significant. In this form of access the attribute list is treated as a sequence. The
library provides support for both forms of access.

A position within an attribute list is identified by a structure of type
VistaIOAttrListPosn. Its value can denote a particular attribute within a list, or no
attribute (analogous to NULL

Creating, Copying, and Destroying Attribute Lists
The following routines will create, copy, and destroy attribute lists.

VistaIOAttrList VistaIOCreateAttrList (void)

VistaIOCreateAttrList creates and returns an empty attribute list.

VistaIOAttrList VistaIOCopyAttrList (VistaIOAttrList list)

VistaIOCopyAttrList generates a complete copy of list using newly-allocated storage
for each list element. The new list contains its own copy of each attribute value —
except that for a VistaIOPointer value, the pointer is copied but not the (opaque)
data structure to which it points.

void VistaIODestroyAttrList (VistaIOAttrList list)

VistaIODestroyAttrList releases the storage occupied by list. Also released is
storage occupied by attribute values — except that for a VistaIOPointer value, the
pointer is released but not the (opaque) data structure to which it points.

Traversing an Attribute List
The following macros are used to sequence through an attribute list in either direction.
They are appropriate when accessing an attribute list representing a sequence (as opposed
to a set) of attributes.

void VistaIOFirstAttr (VistaIOAttrList list, VistaIOAttrListPosn *posn)

VistaIOFirstAttr sets posn to point to the first attribute in list. If the list is
empty, posn is set to point to nothing (a condition that can be tested using the
VistaIOAttrExists macro).

void VistaIOLastAttr (VistaIOAttrList list, VistaIOAttrListPosn *posn)

VistaIOLastAttr sets posn to point to the last attribute in list. If the list is
empty, posn is set to point to nothing (a condition that can be tested using the
VistaIOAttrExists macro).

void VistaIONextAttr (VistaIOAttrListPosn *posn)

VistaIONextAttr sets posn to point to the next attribute in its list. If posn
already points to the list's last attribute, posn is set to point to nothing (a
condition that can be detected by the VistaIOAttrExists macro).

void VistaIOPrevAttr (VistaIOAttrList list, VistaIOAttrListPosn *posn)

VistaIOPrevAttr sets posn to point to the previous attribute in its list. If posn
already points to the list's first attribute, posn is set to point to nothing (a
condition that can be detected by the VistaIOAttrExists macro).

VistaIOBoolean VistaIOAttrExists (VistaIOAttrListPosn *posn)

VistaIOAttrExists returns TRUE if posn points to an attribute, and FALSE if it
points to nothing. This macro is used, for example, to test for the end of an
attribute list while sequencing through it.

VistaIOBoolean VistaIOAttrListEmpty (VistaIOAttrList *list)

VistaIOAttrListEmpty returns TRUE if list is empty.

Accessing Attributes by Position
The following macros and routines access the attribute at a specified position within an
attribute list.

VistaIOStringConst VistaIOGetAttrName (VistaIOAttrListPosn *posn)

The VistaIOGetAttrName macro returns the name of the attribute at posn.

VistaIORepnKind VistaIOGetAttrRepn (VistaIOAttrListPosn *posn)

The VistaIOGetAttrRepn macro returns the type of representation of the attribute
value at posn.

VistaIOBoolean VistaIOGetAttrValue (VistaIOAttrListPosn *posn, VistaIODictEntry *dict,
VistaIORepnKind repn, VistaIOPointer value)

This routine gets the value of the attribute at posn. (See VistaIOGetAttrValue(3) for
details.)

void VistaIOSetAttrValue (VistaIOAttrListPosn *posn, VistaIODictEntry *dict,
VistaIORepnKind repn, type value)

This routine sets the value of the attribute at posn. (See VistaIOSetAttrValue(3) for
details.)

Accessing Attributes by Name
The following routines access attributes by name. They are appropriate when accessing an
attribute list representing a set of attributes, in which each attribute name is present
at most once.

VistaIOBoolean VistaIOLookupAttr (VistaIOAttrList list, VistaIOStringConst name,
VistaIOAttrListPosn *posn)

VistaIOLookupAttr locates the first attribute named name in the list list. If the
attribute is found, TRUE is returned along with the attribute's position in posn.
Otherwise FALSE is returned.

VistaIOGetAttrResult VistaIOGetAttr (VistaIOAttrList *list, VistaIOStringConst name,
VistaIODictEntry *dict, VistaIORepnKind repn, VistaIOPointer value)

VistaIOGetAttr gets the value of the named attribute. (See VistaIOGetAttr(3) for
details.)

void VistaIOSetAttr (VistaIOAttrList *list, VistaIOStringConst name,
VistaIODictEntry *dict, VistaIORepnKind repn, type value)

VistaIOSetAttr sets the value of the named attribute, creating an attribute if the
list doesn't already contain one with that name. (See VistaIOSetAttr(3) for details.)

Inserting and Deleting Attributes
The following routines add attributes to lists and remove them.

void VistaIOInsertAttr (VistaIOAttrListPosn *posn, VistaIOBoolean after,
VistaIOStringConst name, VistaIODictEntry *dict, VistaIORepnKind repn,
type value)

VistaIOInsertAttr inserts an attribute before or after a specified position within an
attribute list. (See VistaIOInsertAttr(3) for details.)

void VistaIODeleteAttr (VistaIOAttrListPosn *posn)

VistaIODeleteAttr deletes the attribute at posn. It leaves posn pointing to the
following attribute if their is one, or nothing if the attribute deleted was the
last on its list.

void VistaIOAppendAttr (VistaIOAttrList *list, VistaIOStringConst name,
VistaIODictEntry *dict, VistaIORepnKind repn, type value)

VistaIOAppendAttr appends an attribute to the back of list. (See VistaIOAppendAttr(3)
for details.)

void VistaIOPrependAttr (VistaIOAttrList *list, VistaIOStringConst name,
VistaIODictEntry *dict, VistaIORepnKind repn, type value)

VistaIOPrependAttr prepends an attribute to the front of list. (See
VistaIOPrependAttr(3) for details.)

VistaIOBoolean VistaIOExtractAttr (VistaIOAttrList *list, VistaIOStringConst name,
VistaIODictEntry *dict, VistaIORepnKind repn, VistaIOPointer value,
VistaIOBoolean required)

VistaIOExtractAttr locates an attribute named name in list, removing it if found and
returning its value. (See VistaIOExtractAttr(3) for details.)

Encoding and Decoding Attribute VistaIOalues
The following routines translate character-string attribute values to and from other
representations.

VistaIOStringConst VistaIOEncodeAttrValue (VistaIODictEntry *dict, VistaIORepnKind repn,
type value)

VistaIOEncodeAttrValue takes a value and an optional dictionary, and encodes the
value as a character string suitable for storage in an attribute list or output to a
data file. (See VistaIOEncodeAttrValue(3) for details.)

VistaIOBoolean VistaIODecodeAttrValue (VistaIOStringConst str, VistaIODictEntry *dict,
VistaIORepnKind repn, VistaIOPointer value)

VistaIODecodeAttrValue performs the inverse operation, taking a string and returning
a value in the requested representation. (See VistaIODecodeAttrValue(3) for details.)

Inputting and Outputting Attribute Lists
The following routines read and write attribute lists.

VistaIOAttrList VistaIOReadFile (FILE *file, VistaIOBoolean (*filter) ())

VistaIOReadFile reads an entire data file, returning it as an attribute list. (See
VistaIOReadFile(3) for details.)

VistaIOBoolean VistaIOWriteFile (FILE *file, VistaIOAttrList list)

VistaIOWriteFile writes an entire data file with the contents of an attribute list.
(See VistaIOWriteFile(3) for details.)

Storage Management
To program with attribute lists it is necessary to know something about how storage is
managed for attribute values. The general rule is that when individual attributes are
accessed, values aren't created, copied, or destroyed — only references to them are
manipulated. On the other hand when an entire attribute list is create, copied, or
destroyed, then all the values will be created, copied, or destroyed along with it.
Unfortunately, the exact behavior must depend on both the type of value an attribute has,
and the type of operation being performed with the attribute. The following table
summarizes the various cases.

For an attribute whose value is a character string:

• The value is stored in an attribute list as a string.

• VistaIOCopyAttrList creates a new copy of the string for the list it creates.

• VistaIODestroyAttrList releases storage occupied by the string when it destroys the
list containing the attribute.

• VistaIOGetAttr and VistaIOGetAttrValue return a pointer to a shared copy of the
string. This pointer is valid until the attribute is modified.

• When VistaIOSetAttr, VistaIOSetAttrValue, VistaIODeleteAttr, or VistaIOExtractAttr
modifies or deletes an attribute with a string value, it releases the storage
occupied by that value.

• When VistaIOSetAttr or VistaIOSetAttrValue sets an attribute to a new string value,
it stores its own copy of the string in the attribute list.

For an attribute whose value is an attribute list, object, or VistaIOBundle:

• The value is stored in an attribute list as a pointer.

• VistaIOCopyAttrList creates a new copy of the value for the list it creates. (If
the value is an attribute list, for example, it calls itself recursively to clone
the value.)

• VistaIODestroyAttrList releases storage occupied by the value when it destroys the
list containing the attribute.

• VistaIOGetAttr and VistaIOGetAttrValue return a pointer to a shared copy of the
value (they don't make a new copy to return). This pointer is valid until the value
is explicitly destroyed, or indirectly destroyed by destroying the list containing
the attribute.

• When VistaIOSetAttr, VistaIOSetAttrValue, VistaIODeleteAttr, or VistaIOExtractAttr
modifies or deletes an attribute with one of these values, it discards the pointer
to the value but not the value itself.

• When VistaIOSetAttr or VistaIOSetAttrValue sets an attribute to one of these values,
it stores a copy of a pointer to the value, but it doesn't copy the value itself.

For an attribute whose value is a VistaIOPointer:

• The value is stored in an attribute list as a pointer.

• VistaIOCopyAttrList creates a new copy of the pointer for the list it creates, but
it doesn't copy the (opaque) data structure pointed to.

• VistaIODestroyAttrList doesn't release the (opaque) data structure pointed to when
it destroys the list containing the attribute.

• VistaIOGetAttr and VistaIOGetAttrValue simply return the pointer.

• When VistaIOSetAttr, VistaIOSetAttrValue, VistaIODeleteAttr, or VistaIOExtractAttr
modifies or deletes an attribute with one of these values, it discards the old
pointer value but doesn't release the (opaque) data structure it points to.

• When VistaIOSetAttr or VistaIOSetAttrValue sets an attribute to one of these values,
it records the new pointer value, but it doesn't copy the (opaque) data structure it
points to.

Data Structures
typedef struct _VAttrRec {
VistaIOAttrRec *next;/* next in list */
VistaIOAttrRec *prev;/* previous in list */
VistaIORepnKind repn;/* rep'n of attribute value */
VistaIOPointer value;/* pointer to attribute value */
char name[1]; /* beginning of name string */
} VistaIOAttrRec, *VistaIOAttrList;

typedef struct {
VistaIOAttrList list;/* the list */
VistaIOAttrRec *ptr;/* position within the list */
} VistaIOAttrListPosn;

Programmers using attribute lists will usually not need to access components of the
attribute list data structure directly from their code since there are library routines
and macros available for most purposes. However, when debugging, one may occasionally
need to examine an attribute list directly.

In a list of attributes, each attribute is represented by a VistaIOAttrRec record. Records
are allocated with a variable size sufficient to contain the attribute name and, if the
attribute value is stored as a character string, the attribute value also.

The record's name field is a variable-length character array containing the attribute's
name terminated by a NULL character. The repn field specifies whether the attribute's
value is stored as a character string (VistaIOStringRepn), an attribute list
(VistaIOAttrListRepn), a pointer to an opaque data structure (VistaIOPointerRepn), or some
other object type (VistaIOBundle, VistaIOImage, VistaIOEdges, etc.). Accordingly, the
value field will point to a null-terminated character string, an attribute list, an opaque
data structure, a VistaIOBundleRec structure, etc. If the value is a string, that string
immediately follows the name string in the variable length record. The next and prev
fields form a doubly-linked list, with NULL pointers marking the list's ends.

An attribute list contains, in addition to a VistaIOAttrRec record for each of its
attributes, one VistaIOAttrRec record serving as a list header. The only significant
fields of this header record are the next and prev fields, which point to the first and
last attributes of the list. An attribute list is of type VistaIOAttrList, which is a
pointer to the list's header record.

The library includes routines and macros that allow one to step through an attribute list,
and to access an attribute by its position in a list. These employ the VistaIOAttrListPosn
type, which acts as a pointer to a particular attribute within a list. The
VistaIOAttrListPosn's list field identifies an entire list, and its ptr field refers to a
specific attribute within that list.

EXAMPLES

       The examples in this section assume the following variables:

              VistaIOAttrList list;
              VistaIOAttrListPosn posn;
              VistaIOImage image, result;

       This  code fragment creates an attribute list, sets some attributes in it, writes the list
       to the standard output stream, and finally destroys the list.

              list = VistaIOCreateAttrList ();
              VistaIOSetAttr (list, "name", NULL, VistaIOStringRepn, "Socrates");
              VistaIOSetAttr (list, "comment", NULL, VistaIOStringRepn, "Greek philosopher");
              VistaIOSetAttr (list, "age", NULL, VistaIOShortRepn, (VistaIOShort) 37);
              VistaIOWriteFile (stdout, list);
              VistaIODestroyAttrList (list);

       This reads an attribute list from the standard input stream and prints the name of each of
       its attributes in sequence:

              list = VistaIOReadFile (stdin, NULL);
              for (VistaIOFirstAttr (list, & posn); VistaIOAttrExists (& posn); VistaIONextAttr (& posn))
                  printf ("%s\n", VistaIOGetAttrName (& posn));

       To add a series of images to an attribute list:

              while (...) {
                  image = VistaIOCreateImage (...);
                  VistaIOAppendAttr (list, ..., VistaIOImageRepn, image);
                  /* Note: don't discard image. */
              }

       To modify each image in an attribute list without replacing it:

              for (VistaIOFirstAttr (list, & posn); VistaIOAttrExists (& posn); VistaIONextAttr (& posn)) {
                  if (VistaIOGetAttrRepn (& posn) != VistaIOImageRepn)
                      continue;
                  VistaIOGetAttrValue (& posn, NULL, VistaIOImageRepn, & image);
                  ProcessImage (image, image, ...);
                  /* Note: modifications to image are inherited by the attribute. */
              }

       To replace each image in an attribute list:

              for (VistaIOFirstAttr (list, & posn); VistaIOAttrExists (& posn); VistaIONextAttr (& posn)) {
                  if (VistaIOGetAttrRepn (& posn) != VistaIOImageRepn)
                      continue;
                  VistaIOGetAttrValue (& posn, NULL, VistaIOImageRepn, & image);
                  result = ProcessImage (image, NULL, ...);
                  VistaIOSetAttrValue (& posn, NULL, VistaIOImageRepn, result);
                  /* Note: the attribute now refers to result, not image. */
                  VistaIODestroyImage (image);
              }

       To delete a named image from an attribute list:

              if (VistaIOLookupAttr (list, "...", & posn)) {
                  VistaIOGetAttrValue (& posn, NULL, VistaIOImageRepn, & image);
                  VistaIODeleteAttr (& posn);
                  VistaIODestroyImage (image);
              }

AUTHOR

       Art Pope <pope@cs.ubc.ca>

       Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

SEE ALSO

AUTHOR