1 | | This is a proposal for a WG2 bytevector API. The conceit is that everything is a separate procedure with minimal arguments; this makes for a ''lot'' of procedures, but each one can be easily inlined by even a very dumb compiler, providing high efficiency. |
2 | | |
3 | | |
4 | | == Numeric procedures == |
5 | | |
6 | | (`bytevector-<type>-ref` ''bytevector n''`)` |
7 | | |
8 | | Returns a Scheme number corresponding to the binary value encoded according to ''type'' beginning at offset ''n'' in ''bytevector''. This procedure treats ''bytevector'' as potentially containing more than one type. |
9 | | |
10 | | (`<type>vector-ref` ''bytevector n''`)` |
11 | | |
12 | | Returns a Scheme number corresponding to the binary value encoded according to ''type'' beginning at offset ''n * b'' in ''bytevector'', where ''b'' is the size of the binary value in bytes. This procedure treats ''bytevector'' as a uniformly typed vector. |
13 | | |
14 | | (`bytevector-<type>-set!` ''bytevector n v''`)` |
15 | | |
16 | | Converts ''v'' to a binary value encoded according to ''type'' and places it into ''bytevector'' beginning at offset ''n''. This procedure treats ''bytevector'' as potentially containing more than one type. |
17 | | |
18 | | (`<type>vector-set!` ''bytevector n v''`)` |
19 | | |
20 | | Converts ''v'' to a binary value encoded according to ''type'' and places it into ''bytevector'' beginning at offset ''n * b'', where ''b'' is the size of the binary value in bytes. This procedure treats ''bytevector'' as a uniformly typed vector. |
21 | | |
22 | | (`<type>vector-length` ''bytevector''`)` |
23 | | |
24 | | Returns a Scheme number corresponding to the length of ''bytevector''divided by the size of the binary value in bytes. |
25 | | |
26 | | (`vector-><type>vector `''vector''`)` |
27 | | |
28 | | Returns a vector with the same elements as ''<type>vector''. |
29 | | |
30 | | (`<type>vector->vector `''<type>vector''`)` |
31 | | |
32 | | Returns a <type>vector with the same elements as ''vector''. It is an error if an element cannot be accurately converted to `<type>`. |
33 | | |
34 | | == Numeric types == |
35 | | |
36 | | A <type> consists of a <principal type> followed by an <endianism>. |
37 | | |
38 | | The <principal type> values are: |
39 | | |
40 | | `u8`:: |
41 | | unsigned 8-bit integer |
42 | | `s8`:: |
43 | | signed 8-bit integer |
44 | | `u16`:: |
45 | | unsigned 16-bit integer |
46 | | `s16`:: |
47 | | signed 16-bit integer |
48 | | `u32`:: |
49 | | unsigned 32-bit integer |
50 | | `s32`:: |
51 | | signed 32-bit integer |
52 | | `u64`:: |
53 | | unsigned 64-bit integer |
54 | | `s64`:: |
55 | | signed 64-bit integer |
56 | | `u128`:: |
57 | | unsigned 128-bit integer |
58 | | `s128`:: |
59 | | signed 128-bit integer |
60 | | `f32`:: |
61 | | 32-bit float |
62 | | `f64`:: |
63 | | 64-bit float |
64 | | `c64`:: |
65 | | 64-bit complex number (two 32-bit floats, real followed by imaginary) |
66 | | `c128`:: |
67 | | 128-bit complex number (two 64-bit floats, real followed by imaginary) |
68 | | |
69 | | The <endianism> values are: |
70 | | |
71 | | (empty):: |
72 | | Native representations (system-dependent) |
73 | | `le`:: |
74 | | Little-endian (for float and complex, IEEE format) |
75 | | `be`:: |
76 | | Big-endian (for float and complex, IEEE format) |
77 | | |
78 | | Endianism is not applicable to the `u8` and `s8` types. |
79 | | |
80 | | |
81 | | == String procedures == |
82 | | |
83 | | (`bytevector-<encoding>-ref` ''bytevector n l''`)`:: |
84 | | Returns a Scheme string corresponding to the binary value encoded according to ''encoding'' beginning at offset ''n'' in ''bytevector'' and continuing for ''l'' bytes. |
85 | | (`bytevector-<encoding>-set!` ''blob n v''`)`:: |
86 | | Converts ''v'' to a binary string encoded according to ''encoding'' and places it into ''bytevector'' beginning at offset ''n''. Returns the number of bytes encoded. |
87 | | |
88 | | == String encodings == |
89 | | |
90 | | `utf8`:: |
91 | | UTF-8 encoding |
92 | | `utf16`:: |
93 | | UTF-16 encoding (respects BOM if present, defaults to native encoding otherwise) |
94 | | `utf16be`:: |
95 | | UTF-16BE encoding (treats BOM as a normal character) |
96 | | `utf16le`:: |
97 | | UTF-16LE encoding (treats BOM as a normal character) |
98 | | |
99 | | === Equality, map, for-each, fold, unfold === |
100 | | |
101 | | '''TBD''' |
| 1 | See NumericVectorsCowan and StringBytevectorConversionCowan. |