VistaIOattribute(3) 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 <[email protected]>

Adaption to vistaio: Gert Wollny <[email protected]>

SEE ALSO

LAST SEARCHED