Provided by: libvistaio-dev_1.2.19-3_amd64 bug

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>