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