bionic (3) VistaIOattribute.3.gz
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);
}
SEE ALSO
VistaIOBundle(3), VistaIOdictionary(3), VistaIOtype(3), , VistaIOGetAttrValue(3), VistaIOSetAttrValue(3), VistaIOGetAttr(3), VistaIOSetAttr(3), VistaIOInsertAttr(3), VistaIOAppendAttr(3), VistaIOPrependAttr(3), VistaIOExtractAttr(3), VistaIOEncodeAttrValue(3), VistaIODecodeAttrValue(3), VistaIOReadFile(3), VistaIOWriteFile(3)
AUTHOR
Art Pope <pope@cs.ubc.ca> Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>