source: project/wiki/man/4/Unit srfi-4 @ 33746

Last change on this file since 33746 was 33746, checked in by sjamaan, 3 years ago

Clarify how srfi-4's release-number-vector can be used

File size: 13.8 KB
Line 
1[[tags: manual]]
2
3== Unit srfi-4
4
5Homogeneous 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
35Each 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}}
38variants 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
57Each of these procedures return a vector where the argument
58{{BLOB}} is taken as a 'packed' representation of the contents
59of the vector. The {{/shared}} variants return a vector that
60shares 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
73Creates a number vector of the same type as the argument vector with the elements at the positions {{FROM}} up to but
74not including {{TO}}.
75
76=== Vector I/O
77
78<procedure>(read-u8vector [LENGTH [PORT]])</procedure>
79
80Reads {{LENGTH}} bytes from the {{PORT}} and returns a fresh
81{{u8vector}} or less if end-of-file is encountered. {{PORT}} defaults to the
82value of {{(current-input-port)}}.
83
84If {{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
88Reads {{LENGTH}} bytes from the {{PORT}} writing the read input into
89{{U8VECTOR}} beginning at {{START}} (or 0 if not given). {{PORT}} defaults
90to the value of {{(current-input-port)}}.
91
92If {{LENGTH}} is {{#f}}, the vector will be filled completely until end-of-file is reached.
93This procedure returns the number of bytes read.
94
95<procedure>(write-u8vector U8VECTOR [PORT [START [END]]])</procedure>
96
97Writes 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
103SRFI-4 describes a set of datatypes for vectors whose elements are
104of the same numeric type (signed or unsigned exact integer or inexact
105real of a given precision). These datatypes support operations analogous
106to the Scheme vector type, but they are distinct datatypes. An external
107representation is specified which must be supported by the {{read}} and
108{{write}} procedures and by the program parser (i.e. programs can contain
109references to literal homogeneous vectors).
110
111=== Datatypes
112
113There are 8 datatypes of exact integer homogeneous vectors (which will be
114called 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
127There are 2 datatypes of inexact real homogeneous vectors (which will be
128called 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
135The only difference between the two float vector types is that
136{{f64vector}}s preserve at least as much precision as {{f32vector}}s.
137
138Each homogeneous vector datatype has an external representation which
139is supported by the {{read}} and {{write}} procedures and by the program
140parser. Each datatype also has a set of associated predefined procedures
141analogous 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
154The external representation of instances of the datatype {{XXXvector}}
155is {{#XXX( ...elements... )}}.
156
157For 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
162This external representation is also available in program source code. For example,
163
164 (set! x '#u8(1 2 3))
165
166will 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
182Return {{#t}} if {{obj}} is an object of the specified type or {{#f}} if not.
183
184<procedure>(number-vector? OBJ)</procedure>
185
186Return {{#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
200Return a newly-allocated SRFI-4 homogeneous number vector of length N.
201
202If the optional fill VALUE is specified, it specifies the initial
203value for each slot in the vector.  If not, the content of the vector
204is unspecified but individual elements of the vector are guaranteed to
205be in the range of values permitted for that type of vector.
206
207The type of the fill value must be compatible with the elements of the
208vector datatype.  It is an error if otherwise -- for example, if an
209inexact integer is passed to {{make-u8vector}}.
210
211On CHICKEN, these procedures have been extended to allow allocating
212the storage in non-garbage collected memory, as follows:
213
214The optional arguments {{NONGC}} and {{FINALIZE}} define whether the
215vector should be allocated in a memory area not subject to garbage
216collection and whether the associated storage should be automatically
217freed (using finalization) when there are no references from Scheme
218variables and data.  {{NONGC}} defaults to {{#f}} (the vector will be
219located in normal garbage collected memory) and {{FINALIZE}} defaults
220to {{#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
232Return a newly-allocated SRFI-4 homogeneous number vector of the specified
233type, 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
246Returns 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
259Return the value of the ''i''th element of the SRFI-4 homogeneous
260number vector, where {{I}} is a nonnegative exact integer less
261than 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
274Set the {{i}}th element of the SRFI-4 homogeneous number VECTOR to
275VALUE.  {{I}} is a nonnegative exact integer less than the length of
276the vector and VALUE must be the same type as the elements of the
277vector datatype.
278
279Additionally, SRFI-17 setters are defined on all {{xxxvector-ref}}
280procedures.  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
296Return a list consisting of the elements of SRFI-4 homogeneous number
297VECTOR.
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
308Return a newly-allocated SRFI-4 homogeneous number VECTOR consisting
309of the elements of LIST.  Each element of LIST must be compatible
310with the datatype of VECTOR.
311
312=== Release number vectors allocated in static memory
313
314<procedure>(release-number-vector NVECTOR)</procedure>
315
316Release the storage of a SRFI-4 vector that was allocated in
317non-garbage collected memory (for example using the {{NONGC}} argument
318for one of the {{make-XXXvector}} constructor procedures). The effect
319of calling this procedure with a number vector allocated in normal
320garbage collected memory is undefined.
321
322
323---
324Previous: [[Unit srfi-1]]
325
326Next: [[Unit srfi-13]]
Note: See TracBrowser for help on using the repository browser.