Taglists

Grzegorz Kraszewski

A taglist is an array of "key-value" pairs. The key is always a 32-bit integer number and is called a tag. The value has also size of 32 bits. It may be an integer, or a pointer to any structure or object. Taglists are commonly used in the MorphOS API for passing variable number of arguments, usually sets of attributes with their values. A few special key values are used for array termination, concatenation and skipping. A set of functions in the utility.library may be used for taglist traversing, filtering, searching, copying etc.

Every pair in a taglist is a TagItem structure, defined in <utility/tagitem.h>:

struct TagItem
{
  ULONG ti_Tag;
  ULONG ti_Data;
};

To be selfdescriptive, every taglist, being just a plain C array, must have some kind of termination. It is very similar to string null-termination idea. The termination is done with a TagItem having its ti_Tag set to TAG_END (which happens to be defined as zero). ti_Data value of the terminating TagItem is ignored, it is usually set to zero too. The drawing below shows some simple taglist:

This taglist may be created with the following code:

double x = 3.438872763e+17;
Object *obj = NewObject( /* ... */ );

struct TagItem taglist[] = {
  { Tag1, 2837 },
  { Tag2, (ULONG)&x },
  { Tag3, (ULONG)"The quick brown fox..." },
  { Tag4, (ULONG)obj },
  { TAG_END, 0 }
};