Difference between revisions of "Taglisty"

From MorphOS Library

(Created, copied English text over.)
 
m (Crosslink to English version.)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
''Grzegorz Kraszewski''
 
''Grzegorz Kraszewski''
 +
----
 +
<small>Ten artykuł w innych językach: [[Taglists|angielski]]</small>
  
  
−
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 also has a 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 a variable number of arguments, usually sets of attributes with their values. A few special key values are used for array termination, concatenation and item skipping. A set of functions in the ''utility.library'' may be used for taglist traversing, filtering, searching, copying etc.
+
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.
  
−
Every pair in a taglist is a ''TagItem'' structure, defined in ''<utility/tagitem.h>'':
+
Każdy element taglisty (para klucz-wartość) jest strukturą ''TagItem'', zdefiniowaną w pliku nagłówkowym ''<utility/tagitem.h>'':
  
 
  struct TagItem
 
  struct TagItem
Line 12: Line 14:
 
  };
 
  };
  
−
To be self descriptive, every taglist, being just a plain C array, must have some kind of termination. It is very similar to the string null-termination idea. The termination is done with a ''TagItem'' having its ''ti_Tag'' field set to ''TAG_END'' (which happens to be defined as zero). The ''ti_Data'' value of the terminating ''TagItem'' is ignored, it is usually set to zero too. The illustration below shows a simple taglist:
+
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ę:
  
  
−
[[File:taglists1.png|center]]
+
[[File:taglists1pl.png|center]]
  
  
−
This taglist may be created with the following code:
+
Taglistę tę można zbudować następującym kodem:
  
 
  double x = 3.438872763e+17;
 
  double x = 3.438872763e+17;
 
  Object *obj = NewObject( /* ... */ );
 
  Object *obj = NewObject( /* ... */ );
 
   
 
   
−
  struct TagItem mytaglist[] = {
+
  struct TagItem taglista[] = {
 
   { Tag1, 2837 },
 
   { Tag1, 2837 },
 
   { Tag2, (ULONG)&x },
 
   { Tag2, (ULONG)&x },
−
   { Tag3, (ULONG)"The quick brown fox..." },
+
   { Tag3, (ULONG)"Leż, dość próźnych kłamstw, rąb fuzję, giń!" },
 
   { Tag4, (ULONG)obj },
 
   { Tag4, (ULONG)obj },
 
   { TAG_END, 0 }
 
   { TAG_END, 0 }
Line 32: Line 34:
  
  
−
==Passing Taglists to Functions==
+
==Taglisty jako argumenty funkcji==
  
−
Building taglists as global or local variables is not very convenient. That is why almost every MorphOS API function getting a taglist as one of its arguments has two forms. The first one accepts a pointer to the taglist. The second one is a variadic args macro building the taglist on the program stack dynamically. Such function pairs are named according to one of the two conventions:
+
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:
−
# ''SomeFunction'''A'''()'' takes a pointer to a taglist, ''SomeFunction()'' builds the taglist dynamically.
 
−
# ''SomeFunction'''TagList'''()'' takes a pointer to a taglist, ''SomeFunction'''Tags'''()'' builds the taglist dynamically.
 
  
 +
# ''JakasFunkcja'''A'''()'' przyjmuje wskaźnik na taglistę, ''JakasFunkcja()'' tworzy taglistę dynamicznie.
 +
# ''JakasFunkcja'''TagList'''()'' przyjmuje wskaźnik na taglistę, ''JakasFunkcja'''Tags'''()'' tworzy taglistę dynamicznie.
  
−
Continuing the above example, one can pass the example taglist to ''SomeFunction()'' in two ways:
+
Kontunuując przykład z poprzedniego podrozdziału, przykładową taglistę można przekazać do ''JakiejsFunkcji()'' na dwa sposoby:
  
−
  SomeFunctionTagList(mytaglist);
+
  JakasFunkcjaTagList(taglista);
−
  SomeFunctionTags(Tag1, 2837, Tag2, (ULONG)&x, Tag3, (ULONG)"The quick brown fox...", Tag4,
+
  JakasFunkcjaTags(Tag1, 2837, Tag2, (ULONG)&x, Tag3, (ULONG)"Leż, dość próżnych kłamstw,"
−
  (ULONG)obj, TAG_END);
+
  " rąb fuzję, giń!", Tag4, (ULONG)obj, TAG_END);
  
−
Of course in the second case variable ''mytaglist'' need not be defined anywhere. Note that for every taglist-based function the taglist is '''the last''' argument. There may be some plain arguments before it. It is a common practice to omit ''ti_Data'' for the terminator (it is ignored anyway).
+
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).

Latest revision as of 14:35, 7 April 2011

Grzegorz Kraszewski

Ten artykuł w innych językach: angielski


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ę:


Taglists1pl.png


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).

Retrieved from "https://library.morph.zone/index.php?title=Taglisty&oldid=1381"