Taglisty

Grzegorz Kraszewski

Taglista to tablica par "klucz-wartość". Kluczem jest zawsze 32-bitowa liczba całkowita i nazywana jest tagiem. Wartość ma również rozmiar 32 bitów. Może to być liczba całkowita, lub wskaźnik na dowolną strukturę, czy obiekt. Taglisty są powszechnie używane w API MorphOS-a do przekazywania zmiennej liczby argumentów, zazwyczaj listy atrybutów wraz z ich wartościami. Kilka specjalnych wartości kluczy jest używanych do zakończenia taglisty, przeskakiwania elementów i łączenia taglist. Biblioteka utility.library zawiera zestaw funkcji do przeglądania, filtrowania, przeszukiwania, kopiowania i innych operacji na taglistach.

Każdy element taglisty (para klucz-wartość) jest strukturą TagItem, zdefiniowaną w pliku nagłówkowym <utility/tagitem.h>:

struct TagItem
{
  ULONG ti_Tag;
  ULONG ti_Data;
};

Taglista jest zwykłą tablicą języka C, żeby była samoopisująca się, musi posiadać jakiś sposób terminacji (oznaczenia końca). Idea jest zbliżona do terminacji łańcuchów tekstowych bajtem 0. Struktura TagItem oznaczająca koniec taglisty ma pole ti_Tag ustawione na stałą TAG_END i tak się składa, że ta stała jest równa 0. Pole ti_Data kończącego elementu jest ignorowane i zwykle również bywa ustawiane na 0. Poniższa ilustracja przedstawia prostą taglistę:

Taglistę tę można zbudować następującym kodem:

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

struct TagItem taglista[] = {
  { Tag1, 2837 },
  { Tag2, (ULONG)&x },
  { Tag3, (ULONG)"Leż, dość próźnych kłamstw, rąb fuzję, giń!" },
  { Tag4, (ULONG)obj },
  { TAG_END, 0 }
};

Taglisty jako argumenty funkcji

Tworzenie taglist jako zmiennych globalnych, czy lokalnych nie jest zbyt wygodne. Dlatego prawie każda funkcja z API MorphOS-a przymująca taglistę jako jeden ze swoich argumentów, ma dwie formy. Pierwsza z form akceptuje jako argument wskaźnik na taglistę. Druga forma jest funkcją o zmiennej liczbie argumentów i tworzy taglistę z argumnentów dynamicznie, umieszczając ją chwilowo na stosie procesu. Takie pary funkcji nazywane są zgodnie z jedną z dwóch poniższych konwencji:

1. JakasFunkcjaA() przyjmuje wskaźnik na taglistę, JakasFunkcja() tworzy taglistę dynamicznie.
2. JakasFunkcjaTagList() przyjmuje wskaźnik na taglistę, JakasFunkcjaTags() tworzy taglistę dynamicznie.

Kontunuując przykład z poprzedniego podrozdziału, przykładową taglistę można przekazać do JakiejsFunkcji() na dwa sposoby:

JakasFunkcjaTagList(taglista);
JakasFunkcjaTags(Tag1, 2837, Tag2, (ULONG)&x, Tag3, (ULONG)"Leż, dość próżnych kłamstw,"
  " rąb fuzję, giń!", Tag4, (ULONG)obj, TAG_END);

Rzecz jasna, w drugim przypadku zmienna taglista nie musi być w ogóle zdefiniowana. Warto zauważyć, że dla każdej funkcji używającej taglisty, taglista jest ostatnim parametrem. Przed nią mogą być inne, zwykłe argumenty. Powszechną praktyką przy dynamicznym tworzeniu taglisty z argumentów funkcji jest pomijanie wartości (ti_Data), dla ostatniego, kończącego taglistę elementu (tak czy inaczej wartość ta jest ignorowana).