1 | [[tags: manual]] |
---|
2 | |
---|
3 | == Unit srfi-4 |
---|
4 | |
---|
5 | Homogeneous numeric vector datatypes. Also see the [[http://srfi.schemers.org/srfi-4/srfi-4.html|original SRFI-4 document]]. |
---|
6 | |
---|
7 | [[toc:]] |
---|
8 | |
---|
9 | == CHICKEN implementation |
---|
10 | |
---|
11 | * Procedures for blob conversion, subvectors and vector I/O are provided. |
---|
12 | * SRFI-17 setters for {{XXXvector-ref}} are defined. |
---|
13 | * Constructors allow allocating the storage in non garbage collected memory. |
---|
14 | * 64-bit integer vectors ({{u64vector}} and {{s64vector}}) are not supported. |
---|
15 | |
---|
16 | === Blob conversions |
---|
17 | |
---|
18 | <procedure>(u8vector->blob U8VECTOR)</procedure><br> |
---|
19 | <procedure>(s8vector->blob S8VECTOR)</procedure><br> |
---|
20 | <procedure>(u16vector->blob U16VECTOR)</procedure><br> |
---|
21 | <procedure>(s16vector->blob S16VECTOR)</procedure><br> |
---|
22 | <procedure>(u32vector->blob U32VECTOR)</procedure><br> |
---|
23 | <procedure>(s32vector->blob S32VECTOR)</procedure><br> |
---|
24 | <procedure>(f32vector->blob F32VECTOR)</procedure><br> |
---|
25 | <procedure>(f64vector->blob F64VECTOR)</procedure><br> |
---|
26 | <procedure>(u8vector->blob/shared U8VECTOR)</procedure><br> |
---|
27 | <procedure>(s8vector->blob/shared S8VECTOR)</procedure><br> |
---|
28 | <procedure>(u16vector->blob/shared U16VECTOR)</procedure><br> |
---|
29 | <procedure>(s16vector->blob/shared S16VECTOR)</procedure><br> |
---|
30 | <procedure>(u32vector->blob/shared U32VECTOR)</procedure><br> |
---|
31 | <procedure>(s32vector->blob/shared S32VECTOR)</procedure><br> |
---|
32 | <procedure>(f32vector->blob/shared F32VECTOR)</procedure><br> |
---|
33 | <procedure>(f64vector->blob/shared F64VECTOR)</procedure><br> |
---|
34 | |
---|
35 | Each of these procedures return the contents of the given vector as a |
---|
36 | 'packed' blob. The byte order in that vector is platform-dependent |
---|
37 | (for example little-endian on an '''Intel''' processor). The {{/shared}} |
---|
38 | variants return a blob that shares memory with the contents of the vector. |
---|
39 | |
---|
40 | <procedure>(blob->u8vector BLOB)</procedure><br> |
---|
41 | <procedure>(blob->s8vector BLOB)</procedure><br> |
---|
42 | <procedure>(blob->u16vector BLOB)</procedure><br> |
---|
43 | <procedure>(blob->s16vector BLOB)</procedure><br> |
---|
44 | <procedure>(blob->u32vector BLOB)</procedure><br> |
---|
45 | <procedure>(blob->s32vector BLOB)</procedure><br> |
---|
46 | <procedure>(blob->f32vector BLOB)</procedure><br> |
---|
47 | <procedure>(blob->f64vector BLOB)</procedure><br> |
---|
48 | <procedure>(blob->u8vector/shared BLOB)</procedure><br> |
---|
49 | <procedure>(blob->s8vector/shared BLOB)</procedure><br> |
---|
50 | <procedure>(blob->u16vector/shared BLOB)</procedure><br> |
---|
51 | <procedure>(blob->s16vector/shared BLOB)</procedure><br> |
---|
52 | <procedure>(blob->u32vector/shared BLOB)</procedure><br> |
---|
53 | <procedure>(blob->s32vector/shared BLOB)</procedure><br> |
---|
54 | <procedure>(blob->f32vector/shared BLOB)</procedure><br> |
---|
55 | <procedure>(blob->f64vector/shared BLOB)</procedure><br> |
---|
56 | |
---|
57 | Each of these procedures return a vector where the argument |
---|
58 | {{BLOB}} is taken as a 'packed' representation of the contents |
---|
59 | of the vector. The {{/shared}} variants return a vector that |
---|
60 | shares memory with the contents of the blob. |
---|
61 | |
---|
62 | === Subvectors |
---|
63 | |
---|
64 | <procedure>(subu8vector U8VECTOR FROM TO)</procedure><br> |
---|
65 | <procedure>(subu16vector U16VECTOR FROM TO)</procedure><br> |
---|
66 | <procedure>(subu32vector U32VECTOR FROM TO)</procedure><br> |
---|
67 | <procedure>(subs8vector S8VECTOR FROM TO)</procedure><br> |
---|
68 | <procedure>(subs16vector S16VECTOR FROM TO)</procedure><br> |
---|
69 | <procedure>(subs32vector S32VECTOR FROM TO)</procedure><br> |
---|
70 | <procedure>(subf32vector F32VECTOR FROM TO)</procedure><br> |
---|
71 | <procedure>(subf64vector F64VECTOR FROM TO)</procedure><br> |
---|
72 | |
---|
73 | Creates a number vector of the same type as the argument vector with the elements at the positions {{FROM}} up to but |
---|
74 | not including {{TO}}. |
---|
75 | |
---|
76 | === Vector I/O |
---|
77 | |
---|
78 | <procedure>(read-u8vector [LENGTH [PORT]])</procedure> |
---|
79 | |
---|
80 | Reads {{LENGTH}} bytes from the {{PORT}} and returns a fresh |
---|
81 | {{u8vector}} or less if end-of-file is encountered. {{PORT}} defaults to the |
---|
82 | value of {{(current-input-port)}}. |
---|
83 | |
---|
84 | If {{LENGTH}} is {{#f}}, the vector will be filled completely until end-of-file is reached. |
---|
85 | |
---|
86 | <procedure>(read-u8vector! LENGTH U8VECTOR [PORT [START]])</procedure> |
---|
87 | |
---|
88 | Reads {{LENGTH}} bytes from the {{PORT}} writing the read input into |
---|
89 | {{U8VECTOR}} beginning at {{START}} (or 0 if not given). {{PORT}} defaults |
---|
90 | to the value of {{(current-input-port)}}. |
---|
91 | |
---|
92 | If {{LENGTH}} is {{#f}}, the vector will be filled completely until end-of-file is reached. |
---|
93 | This procedure returns the number of bytes read. |
---|
94 | |
---|
95 | <procedure>(write-u8vector U8VECTOR [PORT [START [END]]])</procedure> |
---|
96 | |
---|
97 | Writes the bytes {{U8VECTOR}} between the indices {{START}} (inclusive) and {{END}} (exclusive) to {{PORT}}. |
---|
98 | |
---|
99 | {{PORT}} defaults to the value of {{(current-output-port)}}. |
---|
100 | |
---|
101 | == SRFI-4 specification |
---|
102 | |
---|
103 | SRFI-4 describes a set of datatypes for vectors whose elements are |
---|
104 | of the same numeric type (signed or unsigned exact integer or inexact |
---|
105 | real of a given precision). These datatypes support operations analogous |
---|
106 | to the Scheme vector type, but they are distinct datatypes. An external |
---|
107 | representation is specified which must be supported by the {{read}} and |
---|
108 | {{write}} procedures and by the program parser (i.e. programs can contain |
---|
109 | references to literal homogeneous vectors). |
---|
110 | |
---|
111 | === Datatypes |
---|
112 | |
---|
113 | There are 8 datatypes of exact integer homogeneous vectors (which will be |
---|
114 | called integer vectors): |
---|
115 | |
---|
116 | <table> |
---|
117 | <tr><th>Datatype</th><th>Type of elements</th></tr> |
---|
118 | <tr><td>{{s8vector}}</td><td>signed exact integer in the range -(2^7) to (2^7)-1</td></tr> |
---|
119 | <tr><td>{{u8vector}}</td><td>unsigned exact integer in the range 0 to (2^8)-1</td></tr> |
---|
120 | <tr><td>{{s16vector}}</td><td>signed exact integer in the range -(2^15) to (2^15)-1</td></tr> |
---|
121 | <tr><td>{{u16vector}}</td><td>unsigned exact integer in the range 0 to (2^16)-1</td></tr> |
---|
122 | <tr><td>{{s32vector}}</td><td>signed exact integer in the range -(2^31) to (2^31)-1</td></tr> |
---|
123 | <tr><td>{{u32vector}}</td><td>unsigned exact integer in the range 0 to (2^32)-1</td></tr> |
---|
124 | <tr><td>{{s64vector}}</td><td>signed exact integer in the range -(2^63) to (2^63)-1</td></tr> |
---|
125 | <tr><td>{{u64vector}}</td><td>unsigned exact integer in the range 0 to (2^64)-1</td></tr></table> |
---|
126 | |
---|
127 | There are 2 datatypes of inexact real homogeneous vectors (which will be |
---|
128 | called float vectors): |
---|
129 | |
---|
130 | <table> |
---|
131 | <tr><th>Datatype</th><th>Type of elements</th></tr> |
---|
132 | <tr><td>{{f32vector}}</td><td>inexact real</td></tr> |
---|
133 | <tr><td>{{f64vector}}</td><td>inexact real</td></tr></table> |
---|
134 | |
---|
135 | The only difference between the two float vector types is that |
---|
136 | {{f64vector}}s preserve at least as much precision as {{f32vector}}s. |
---|
137 | |
---|
138 | Each homogeneous vector datatype has an external representation which |
---|
139 | is supported by the {{read}} and {{write}} procedures and by the program |
---|
140 | parser. Each datatype also has a set of associated predefined procedures |
---|
141 | analogous to those available for Scheme's heterogeneous vectors. |
---|
142 | |
---|
143 | === External representation |
---|
144 | |
---|
145 | <read>#u8</read><br> |
---|
146 | <read>#u16</read><br> |
---|
147 | <read>#u32</read><br> |
---|
148 | <read>#s8</read><br> |
---|
149 | <read>#s16</read><br> |
---|
150 | <read>#s32</read><br> |
---|
151 | <read>#f32</read><br> |
---|
152 | <read>#f64</read><br> |
---|
153 | |
---|
154 | The external representation of instances of the datatype {{XXXvector}} |
---|
155 | is {{#XXX( ...elements... )}}. |
---|
156 | |
---|
157 | For example, |
---|
158 | |
---|
159 | #u8(0 #e1e2 #xff)}} ; a {{u8vector}} of length 3 containing 0, 100, 255 |
---|
160 | #f64(-1.5) ; a {{f64vector}} of length 1 containing -1.5. |
---|
161 | |
---|
162 | This external representation is also available in program source code. For example, |
---|
163 | |
---|
164 | (set! x '#u8(1 2 3)) |
---|
165 | |
---|
166 | will set {{x}} to the object {{#u8(1 2 3)}}. Since CHICKEN 4.9.0, literal homogeneous vectors do not have to be quoted. Homogeneous vectors can appear in quasiquotations but must not contain {{unquote}} or {{unquote-splicing}} forms. ''I.e.'', |
---|
167 | |
---|
168 | `(,x #u8(1 2)) ; legal |
---|
169 | `#u8(1 ,x 2) ; illegal |
---|
170 | |
---|
171 | === Predicates |
---|
172 | |
---|
173 | <procedure>(u8vector? OBJ)</procedure><br> |
---|
174 | <procedure>(s8vector? OBJ)</procedure><br> |
---|
175 | <procedure>(u16vector? OBJ)</procedure><br> |
---|
176 | <procedure>(s16vector? OBJ)</procedure><br> |
---|
177 | <procedure>(u32vector? OBJ)</procedure><br> |
---|
178 | <procedure>(s32vector? OBJ)</procedure><br> |
---|
179 | <procedure>(f32vector? OBJ)</procedure><br> |
---|
180 | <procedure>(f64vector? OBJ)</procedure><br> |
---|
181 | |
---|
182 | Return {{#t}} if {{obj}} is an object of the specified type or {{#f}} if not. |
---|
183 | |
---|
184 | <procedure>(number-vector? OBJ)</procedure> |
---|
185 | |
---|
186 | Return {{#t}} if {{obj}} is a number vector, {{#f}} if not. A "number vector" is any of the homogeneous number vector types defined by SRFI-4, ie it's one of {{u8vector}}, {{s8vector}}, {{u16vector}}, {{s16vector}}, {{u32vector}}, {{s32vector}}, {{f32vector}} or {{f64vector}}). |
---|
187 | |
---|
188 | |
---|
189 | === Constructors |
---|
190 | |
---|
191 | <procedure>(make-u8vector N [U8VALUE NONGC FINALIZE])</procedure><br> |
---|
192 | <procedure>(make-s8vector N [S8VALUE NONGC FINALIZE])</procedure><br> |
---|
193 | <procedure>(make-u16vector N [U16VALUE NONGC FINALIZE])</procedure><br> |
---|
194 | <procedure>(make-s16vector N [S16VALUE NONGC FINALIZE])</procedure><br> |
---|
195 | <procedure>(make-u32vector N [U32VALUE NONGC FINALIZE])</procedure><br> |
---|
196 | <procedure>(make-s32vector N [S32VALUE NONGC FINALIZE])</procedure><br> |
---|
197 | <procedure>(make-f32vector N [F32VALUE NONGC FINALIZE])</procedure><br> |
---|
198 | <procedure>(make-f64vector N [F64VALUE NONGC FINALIZE])</procedure><br> |
---|
199 | |
---|
200 | Return a newly-allocated SRFI-4 homogeneous number vector of length N. |
---|
201 | |
---|
202 | If the optional fill VALUE is specified, it specifies the initial |
---|
203 | value for each slot in the vector. If not, the content of the vector |
---|
204 | is unspecified but individual elements of the vector are guaranteed to |
---|
205 | be in the range of values permitted for that type of vector. |
---|
206 | |
---|
207 | The type of the fill value must be compatible with the elements of the |
---|
208 | vector datatype. It is an error if otherwise -- for example, if an |
---|
209 | inexact integer is passed to {{make-u8vector}}. |
---|
210 | |
---|
211 | On CHICKEN, these procedures have been extended to allow allocating |
---|
212 | the storage in non-garbage collected memory, as follows: |
---|
213 | |
---|
214 | The optional arguments {{NONGC}} and {{FINALIZE}} define whether the |
---|
215 | vector should be allocated in a memory area not subject to garbage |
---|
216 | collection and whether the associated storage should be automatically |
---|
217 | freed (using finalization) when there are no references from Scheme |
---|
218 | variables and data. {{NONGC}} defaults to {{#f}} (the vector will be |
---|
219 | located in normal garbage collected memory) and {{FINALIZE}} defaults |
---|
220 | to {{#t}}. Note that the {{FINALIZE}} argument is only used when |
---|
221 | {{NONGC}} is true. |
---|
222 | |
---|
223 | <procedure>(u8vector U8VALUE ...)</procedure><br> |
---|
224 | <procedure>(s8vector S8VALUE ...)</procedure><br> |
---|
225 | <procedure>(u16vector U16VALUE ...)</procedure><br> |
---|
226 | <procedure>(s16vector S16VALUE ...)</procedure><br> |
---|
227 | <procedure>(u32vector U32VALUE ...)</procedure><br> |
---|
228 | <procedure>(s32vector S32VALUE ...)</procedure><br> |
---|
229 | <procedure>(f32vector F32VALUE ...)</procedure><br> |
---|
230 | <procedure>(f64vector F64VALUE ...)</procedure><br> |
---|
231 | |
---|
232 | Return a newly-allocated SRFI-4 homogeneous number vector of the specified |
---|
233 | type, composed of the arguments. |
---|
234 | |
---|
235 | === Length |
---|
236 | |
---|
237 | <procedure>(u8vector-length U8VECTOR)</procedure><br> |
---|
238 | <procedure>(s8vector-length S8VECTOR)</procedure><br> |
---|
239 | <procedure>(u16vector-length U16VECTOR)</procedure><br> |
---|
240 | <procedure>(s16vector-length S16VECTOR)</procedure><br> |
---|
241 | <procedure>(u32vector-length U32VECTOR)</procedure><br> |
---|
242 | <procedure>(s32vector-length S32VECTOR)</procedure><br> |
---|
243 | <procedure>(f32vector-length F32VECTOR)</procedure><br> |
---|
244 | <procedure>(f64vector-length F64VECTOR)</procedure><br> |
---|
245 | |
---|
246 | Returns the length of the SRFI-4 homogeneous number VECTOR. |
---|
247 | |
---|
248 | === Getters |
---|
249 | |
---|
250 | <procedure>(u8vector-ref U8VECTOR I)</procedure><br> |
---|
251 | <procedure>(s8vector-ref S8VECTOR i)</procedure><br> |
---|
252 | <procedure>(u16vector-ref U16VECTOR I)</procedure><br> |
---|
253 | <procedure>(s16vector-ref S16VECTOR I)</procedure><br> |
---|
254 | <procedure>(u32vector-ref U32VECTOR I)</procedure><br> |
---|
255 | <procedure>(s32vector-ref S32VECTOR I)</procedure><br> |
---|
256 | <procedure>(f32vector-ref F32VECTOR I)</procedure><br> |
---|
257 | <procedure>(f64vector-ref F64VECTOR I)</procedure><br> |
---|
258 | |
---|
259 | Return the value of the ''i''th element of the SRFI-4 homogeneous |
---|
260 | number vector, where {{I}} is a nonnegative exact integer less |
---|
261 | than the length of the vector. |
---|
262 | |
---|
263 | === Setters |
---|
264 | |
---|
265 | <procedure>(u8vector-set! U8VECTOR I U8VALUE)</procedure><br> |
---|
266 | <procedure>(s8vector-set! S8VECTOR I S8VALUE)</procedure><br> |
---|
267 | <procedure>(u16vector-set! U16VECTOR I U16VALUE)</procedure><br> |
---|
268 | <procedure>(s16vector-set! S16VECTOR I S16VALUE)</procedure><br> |
---|
269 | <procedure>(u32vector-set! U32VECTOR I U32VALUE)</procedure><br> |
---|
270 | <procedure>(s32vector-set! S32VECTOR I S32VALUE)</procedure><br> |
---|
271 | <procedure>(f32vector-set! F32VECTOR I F32VALUE)</procedure><br> |
---|
272 | <procedure>(f64vector-set! F64VECTOR I F64VALUE)</procedure><br> |
---|
273 | |
---|
274 | Set the {{i}}th element of the SRFI-4 homogeneous number VECTOR to |
---|
275 | VALUE. {{I}} is a nonnegative exact integer less than the length of |
---|
276 | the vector and VALUE must be the same type as the elements of the |
---|
277 | vector datatype. |
---|
278 | |
---|
279 | Additionally, SRFI-17 setters are defined on all {{xxxvector-ref}} |
---|
280 | procedures. For example, to set the {{i}}th element of SRFI-4 |
---|
281 | {{u8vector}} to {{u8value}}: |
---|
282 | |
---|
283 | (set! (u8vector-ref u8vector i) u8value) |
---|
284 | |
---|
285 | === Conversions |
---|
286 | |
---|
287 | <procedure>(u8vector->list U8VECTOR)</procedure><br> |
---|
288 | <procedure>(s8vector->list S8VECTOR)</procedure><br> |
---|
289 | <procedure>(u16vector->list U16VECTOR)</procedure><br> |
---|
290 | <procedure>(s16vector->list S16VECTOR)</procedure><br> |
---|
291 | <procedure>(u32vector->list U32VECTOR)</procedure><br> |
---|
292 | <procedure>(s32vector->list S32VECTOR)</procedure><br> |
---|
293 | <procedure>(f32vector->list F32VECTOR)</procedure><br> |
---|
294 | <procedure>(f64vector->list F64VECTOR)</procedure><br> |
---|
295 | |
---|
296 | Return a list consisting of the elements of SRFI-4 homogeneous number |
---|
297 | VECTOR. |
---|
298 | |
---|
299 | <procedure>(list->u8vector U8LIST)</procedure><br> |
---|
300 | <procedure>(list->s8vector S8LIST)</procedure><br> |
---|
301 | <procedure>(list->u16vector U16LIST)</procedure><br> |
---|
302 | <procedure>(list->s16vector S16LIST)</procedure><br> |
---|
303 | <procedure>(list->u32vector U32LIST)</procedure><br> |
---|
304 | <procedure>(list->s32vector S32LIST)</procedure><br> |
---|
305 | <procedure>(list->f32vector F32LIST)</procedure><br> |
---|
306 | <procedure>(list->f64vector F64LIST)</procedure><br> |
---|
307 | |
---|
308 | Return a newly-allocated SRFI-4 homogeneous number VECTOR consisting |
---|
309 | of the elements of LIST. Each element of LIST must be compatible |
---|
310 | with the datatype of VECTOR. |
---|
311 | |
---|
312 | === Release number vectors allocated in static memory |
---|
313 | |
---|
314 | <procedure>(release-number-vector NVECTOR)</procedure> |
---|
315 | |
---|
316 | Release the storage of a SRFI-4 vector that was allocated in |
---|
317 | non-garbage collected memory (for example using the {{NONGC}} argument |
---|
318 | for one of the {{make-XXXvector}} constructor procedures). The effect |
---|
319 | of calling this procedure with a number vector allocated in normal |
---|
320 | garbage collected memory is undefined. |
---|
321 | |
---|
322 | |
---|
323 | --- |
---|
324 | Previous: [[Unit srfi-1]] |
---|
325 | |
---|
326 | Next: [[Unit srfi-13]] |
---|