1\datatype{Assoc_Type}
2\synopsis{An associative array or hash type}
3\description
4  An \dtype{Assoc_Type} object is like an array except that it is
5  indexed using strings and not integers.  Unlike an \dtype{Array_Type}
6  object, the size of an associative array is not fixed, but grows as
7  objects are added to the array.  Another difference is that ordinary
8  arrays represent ordered object; however, the ordering of the
9  elements of an \var{Assoc_Type} object is unspecified.
10
11  An \dtype{Assoc_Type} object whose elements are of some data-type
12  \exmp{d} may be created using using
13#v+
14    A = Assoc_Type[d];
15#v-
16  For example,
17#v+
18    A = Assoc_Type[Int_Type];
19#v-
20  will create an associative array of integers.  To create an
21  associative array capable of storing an arbitrary type, use the form
22#v+
23    A = Assoc_Type[];
24#v-
25
26  An optional parameter may be used to specify a default value for
27  array elements.  For example,
28#v+
29   A = Assoc_Type[Int_Type, -1];
30#v-
31  creates an integer-valued associative array with a default element
32  value of -1.  Then \exmp{A["foo"]} will return -1 if the key
33  \exmp{"foo"} does not exist in the array.  Default values are
34  available only if the type was specified when the associative array
35  was created.
36
37  The following functions may be used with associative arrays:
38#v+
39    assoc_get_keys
40    assoc_get_values
41    assoc_key_exists
42    assoc_delete_key
43#v-
44  The \ifun{length} function may be used to obtain the number of
45  elements in the array.
46
47  The \var{foreach} construct may be used with associative arrays via
48  one of the following forms:
49#v+
50      foreach k,v (A) {...}
51      foreach k (A) using ("keys") { ... }
52      foreach v (A) using ("values") { ... }
53      foreach k,v (A) using ("keys", "values") { ... }
54#v-
55  In all the above forms, the loop is over all elements of the array
56  such that \exmp{v=A[k]}.
57\seealso{List_Type, Array_Type, Struct_Type}
58\done
59
60\datatype{File_Type}
61\synopsis{A type representing a C stdio object}
62\description
63  An \dtype{File_Type} is the interpreter's representation of a C
64  stdio FILE object and is usually created using the \ifun{fopen}
65  function, i.e.,
66#v+
67    fp = fopen ("file.dat", "r");
68#v-
69  Functions that utilize the \dtype{File_Type} include:
70#v+
71    fopen
72    fclose
73    fgets
74    fputs
75    ferror
76    feof
77    fflush
78    fprintf
79    fseek
80    ftell
81    fread
82    fwrite
83    fread_bytes
84#v-
85  The \var{foreach} construct may be used with \dtype{File_Type}
86  objects via one of the following forms:
87#v+
88   foreach line (fp) {...}
89   foreach byte (A) using ("char") { ... }   % read bytes
90   foreach line (A) using ("line") { ... }   % read lines (default)
91   foreach line (A) using ("wsline") { ... } % whitespace stripped from lines
92#v-
93\seealso{List_Type, Array_Type, Struct_Type}
94\done
95
96\datatype{List_Type}
97\synopsis{A list object}
98\description
99  An object of type \var{List_Type} represents a list, which is
100  defined as an ordered heterogeneous collection of objects.
101  A list may be created using, e.g.,
102#v+
103    empty_list = {};
104    list_with_4_items = {[1:10], "three", 9, {1,2,3}};
105#v-
106  Note that the last item of the list in the last example is also a
107  list.  A List_Type object may be manipulated by the following
108  functions:
109#v+
110    list_new
111    list_insert
112    list_append
113    list_delete
114    list_reverse
115    list_pop
116#v-
117  A \var{List_Type} object may be indexed using an array syntax with
118  the first item on the list given by an index of 0.  The
119  \ifun{length} function may be used to obtain the number of elements
120  in the list.
121
122  A copy of the list may be created using the @ operator, e.g.,
123  \exmp{copy = @list}.
124
125  The \kw{foreach} statement may be used with a \dtype{List_Type}
126  object to loop over its elements:
127#v+
128    foreach elem (list) {....}
129#v-
130\seealso{Array_Type, Assoc_Type, Struct_Type}
131\done
132
133\datatype{String_Type}
134\synopsis{A string object}
135\description
136  An object of type \var{String_Type} represents a string of bytes or
137  characters, which in general have different semantics depending upon
138  the UTF-8 mode.
139
140  The string obeys byte-semantics when indexed as an
141  array.  That is, \exmp{S[0]} will return the first byte of the
142  string \exmp{S}.  For character semantics, the nth character in the
143  string may be obtained using \ivar{substr} function.
144
145  The \kw{foreach} statement may be used with a \dtype{String_Type}
146  object \exmp{S} to loop over its bytes:
147#v+
148    foreach b (S) {....}
149    foreach b (S) using ("bytes") {....}
150#v-
151  To loop over its characters, the following form may be used:
152#v+
153    foreach c (S) using ("chars") {...}
154#v-
155  When UTF-8 mode is not in effect, the byte and character forms will
156  produce the same sequence.  Otherwise, the string will be decoded
157  to generate the (wide) character sequence.  If the string contains
158  an invalid UTF-8 encoded character, successive bytes of the invalid
159  sequence will be returned as negative integers.  For example,
160  \exmp{"a\\xAB\\x{AB}"} specifies a string composed of the character
161  \exmp{a}, a byte \exmp{0xAB}, and the character \exmp{0xAB}.  In
162  this case,
163#v+
164     foreach c ("a\xAB\x{AB}") {...}
165#v-
166  will produce the integer-valued sequence \exmp{'a', -0xAB, 0xAB}.
167
168\seealso{Array_Type, _slang_utf8_ok}
169\done
170
171\datatype{Struct_Type}
172\synopsis{A structure datatype}
173\description
174  A \dtype{Struct_Type} object with fields \exmp{f1}, \exmp{f2},...,
175  \exmp{fN} may be created using
176#v+
177    s = struct { f1, f2, ..., fN };
178#v-
179  The fields may be accessed via the "dot" operator, e.g.,
180#v+
181     s.f1 = 3;
182     if (s12.f1 == 4) s.f1++;
183#v-
184  By default, all fields will be initialized to \NULL.
185
186  A structure may also be created using the dereference operator (@):
187#v+
188    s = @Struct_Type ("f1", "f2", ..., "fN");
189    s = @Struct_Type ( ["f1", "f2", ..., "fN"] );
190#v-
191  Functions for manipulating structure fields include:
192#v+
193     _push_struct_field_values
194     get_struct_field
195     get_struct_field_names
196     set_struct_field
197     set_struct_fields
198#v-
199
200  The \kw{foreach} loop may be used to loop over elements of a linked
201  list.  Suppose that first structure in the list is called
202  \exmp{root}, and that the \exmp{child} field is used to form the
203  chain.  Then one may walk the list using:
204#v+
205     foreach s (root) using ("child")
206      {
207         % s will take on successive values in the list
208          .
209          .
210      }
211#v-
212  The loop will terminate when the last elements \exmp{child} field is
213  \NULL.  If no ``linking'' field is specified, the field name will
214  default to \exmp{next}.
215
216  User-defined data types are similar to the \var{Struct_Type}.  A
217  type, e.g., \exmp{Vector_Type} may be created using:
218#v+
219    typedef struct { x, y, z } Vector_Type;
220#v-
221  Objects of this type may be created via the @ operator, e.g.,
222#v+
223    v = @Vector_Type;
224#v-
225  It is recommended that this be used in a function for creating such
226  types, e.g.,
227#v+
228    define vector (x, y, z)
229    {
230       variable v = @Vector_Type;
231       v.x = x;
232       v.y = y;
233       v.z = z;
234       return v;
235    }
236#v-
237  The action of the binary and unary operators may be defined for such
238  types.  Consider the "+" operator.  First define a function for
239  adding two \exmp{Vector_Type} objects:
240#v+
241    static define vector_add (v1, v2)
242    {
243       return vector (v1.x+v2.x, v1.y+v2.y, v1.z, v2.z);
244    }
245#v-
246  Then use
247#v+
248    __add_binary ("+", Vector_Type, &vector_add, Vector_Type, Vector_Type);
249#v-
250  to indicate that the function is to be called whenever the "+"
251  binary operation between two \exmp{Vector_Type} objects takes place,
252  e.g.,
253#v+
254    V1 = vector (1, 2, 3);
255    V2 = vector (8, 9, 1);
256    V3 = V1 + V2;
257#v-
258  will assigned the vector (9, 11, 4) to \exmp{V3}.  Similarly, the
259  \exmp{"*"} operator between scalars and vectors may be defined using:
260#v+
261    static define vector_scalar_mul (v, a)
262    {
263       return vector (a*v.x, a*v.y, a*v.z);
264    }
265    static define scalar_vector_mul (a, v)
266    {
267       return vector_scalar_mul (v, a);
268    }
269    __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type);
270    __add_binary ("*", Vector_Type, &vector_scalar_mul, Vector_Type, Any_Type);
271#v-
272  Related functions include:
273#v+
274    __add_unary
275    __add_string
276    __add_destroy
277#v-
278\seealso{List_Type, Assoc_Type}
279\done
280
281