source: project/wiki/eggref/5/srfi-74 @ 39286

Last change on this file since 39286 was 39286, checked in by gnosis, 2 months ago

Initial revision of SRFI-74 documentation

File size: 12.1 KB
Line 
1== SRFI-74: Octet-Addressed Binary Blocks
2=== Abstract
3This SRFI defines a set of procedures for creating, accessing, and manipulating octet-addressed blocks of binary data, in short, blobs. The SRFI provides access primitives for fixed-length integers of arbitrary size, with specified endianness, and a choice of unsigned and two's complement representations.
4
5For more information see: [[https://srfi.schemers.org/srfi-74/|SRFI-74: Octet-Addressed Binary Blocks]]
6=== Rationale
7Many applications must deal with blocks of binary data by accessing them in various ways---extracting signed or unsigned numbers of various sizes. Such an application can use octet vectors as in [[https://srfi.schemers.org/srfi-66/|SRFI 66]] or any of the other types of homogeneous vectors in [[http://srfi.schemers.org/srfi-4/|SRFI 4]], but these both only allow retrieving the binary data of one type.
8
9This is awkward in many situations, because an application might access different kinds of entities from a single binary block. Even for uniform blocks, the disjointness of the various vector data types in SRFI 4 means that, say, an I/O API needs to provide an army of procedures for each of them in order to provide efficient access to binary data.
10
11Therefore, this SRFI provides a single type for blocks of binary data with multiple ways to access that data. It deals only with integers in various sizes with specified [[http://en.wikipedia.org/wiki/Endianness|endianness]], because these are the most frequent applications. Dealing with other kinds of binary data, such as floating-point numbers or variable-size integers would be natural extensions, but are left for a future SRFI.
12=== Specification
13==== General remarks
14Blobs are objects of a new type. Conceptually, a blob represents a sequence of octets.
15
16Scheme systems implementing both SRFI 4 and/or SRFI 66 and this SRFI may or may not use the same type for u8vector and blobs. They are encouraged to do so, however.
17
18As with u8vectors, the length of a blob is the number of octets it contains. This number is fixed. A valid index into a blob is an exact, non-negative integer. The first octet of a blob has index 0, the last octet has an index one less than the length of the blob.
19
20Generally, the access procedures come in different flavors according to the size of the represented integer, and the endianness of the representation. The procedures also distinguish signed and unsigned representations. The signed representations all use [[http://en.wikipedia.org/wiki/Two's_complement|two's complement]].
21
22For procedures that have no "natural" return value, this SRFI often uses the sentence
23
24The return values are unspecified.
25
26This means that number of return values and the return values are unspecified. However, the number of return values is such that it is accepted by a continuation created by begin. Specifically, on Scheme implementations where continuations created by begin accept an arbitrary number of arguments (this includes most implementations), it is suggested that the procedure return zero return values.
27==== Interface
28
29<syntax>(endianness big)</syntax>
30
31
32<syntax>(endianness little)</syntax>
33
34
35<syntax>(endianness native)</syntax>
36
37{{(endianness big)}} and {{(endianness little)}} evaluate to two distinct and unique objects representing an {{endianness}}. The native {{endianness}} evaluates to the endianness of the underlying machine architecture, and must be {{eq?}} to either {{(endianness big)}} or {{(endianness little)}}.
38
39<procedure>(blob? obj)</procedure>
40
41Returns {{#t}} if obj is a blob, otherwise returns {{#f}}.
42
43<procedure>(make-blob k)</procedure>
44
45Returns a newly allocated blob of {{k}} octets, all of them 0.
46
47<procedure>(blob-length blob)</procedure>
48
49Returns the number of octets in blob as an exact integer.
50
51<procedure>(blob-u8-ref blob k)</procedure>
52
53<procedure>(blob-s8-ref blob k)</procedure>
54
55{{K}} must be a valid index of {{blob}}.
56
57{{Blob-u8-ref}} returns the octet at index {{k}} of blob.
58
59{{Blob-s8-ref}} returns the exact integer corresponding to the two's complement representation at index {{k}} of blob.
60
61<procedure>(blob-u8-set! blob k octet)</procedure>
62
63<procedure>(blob-s8-set! blob k byte)</procedure>
64
65{{K}} must be a valid index of blob.
66
67{{Blob-u8-set!}} stores octet in element {{k}} of blob.
68
69Byte, must be an exact integer in the interval {-128, ..., 127}. {{Blob-u8-set!}} stores the two's complement representation of byte in element {{k}} of blob.
70
71The return values are unspecified.
72
73<procedure>(blob-uint-ref size endianness blob k)</procedure>
74
75<procedure>(blob-sint-ref size endianness blob k)</procedure>
76
77<procedure>(blob-uint-set! size endianness blob k n)</procedure>
78
79<procedure>(blob-sint-set! size endianness blob k n)</procedure>
80
81Size must be a positive exact integer. {{K}} must be a valid index of blob; so must the indices {k, ..., k + size - 1}. {{Endianness}} must be an {{endianness}} object.
82
83{{Blob-uint-ref}} retrieves the exact integer corresponding to the unsigned representation of size size and specified by endianness at indices {k, ..., k + size - 1}.
84
85{{Blob-sint-ref}} retrieves the exact integer corresponding to the two's complement representation of size size and specified by {{endianness}} at indices {k, ..., k + size - 1}.
86
87For {{blob-uint-set!}}, {{n}} must be an exact integer in the interval [0, (256^size)-1]. Blob-uint-set! stores the unsigned representation of size size and specified by endianness into the blob at indices {k, ..., k + size - 1}.
88
89For {{blob-uint-set!}}, {{n}} must be an exact integer in the interval [-256^(size-1), (256^(size-1))-1]. Blob-sint-set! stores the two's complement representation of size size and specified by endianness into the blob at indices {k, ..., k + size - 1}.
90
91<procedure>(blob-u16-ref endianness blob k)</procedure>
92
93<procedure>(blob-s16-ref endianness blob k)</procedure>
94
95<procedure>(blob-u16-native-ref blob k)</procedure>
96
97<procedure>(blob-s16-native-ref blob k)</procedure>
98
99<procedure>(blob-u16-set! endianness blob k n)</procedure>
100
101<procedure>(blob-s16-set! endianness blob k n)</procedure>
102
103<procedure>(blob-u16-native-set! blob k n)</procedure>
104
105<procedure>(blob-s16-native-set! blob k n)</procedure>
106
107K must be a valid index of blob; so must the index k+ 1. Endianness must be an endianness object.
108
109These retrieve and set two-octet representations of numbers at indices {{k}} and k+1, according to the endianness specified by {{endianness}}. The procedures with u16 in their names deal with the unsigned representation, those with s16 with the two's complement representation.
110
111The procedures with native in their names employ the native endianness, and only work at aligned indices: {{k}} must be a multiple of 2. It is an error to use them at non-aligned indices.
112
113<procedure>(blob-u32-ref endianness blob k)</procedure>
114
115<procedure>(blob-s32-ref endianness blob k)</procedure>
116
117<procedure>(blob-u32-native-ref blob k)</procedure>
118
119<procedure>(blob-s32-native-ref blob k)</procedure>
120
121<procedure>(blob-u32-set! endianness blob k n)</procedure>
122
123<procedure>(blob-s32-set! endianness blob k n)</procedure>
124
125<procedure>(blob-u32-native-set! blob k n)</procedure>
126
127<procedure>(blob-s32-native-set! blob k n)</procedure>
128
129K must be a valid index of blob; so must the indices {k, ..., k+ 3}. {{Endianness}} must be an {{endianness}} object.
130
131These retrieve and set four-octet representations of numbers at indices {k, ..., k+ 3}, according to the endianness specified by {{endianness}}. The procedures with u32 in their names deal with the unsigned representation, those with s32 with the two's complement representation.
132
133The procedures with native in their names employ the native endianness, and only work at aligned indices: {{k}} must be a multiple of 4. It is an error to use them at non-aligned indices.
134
135<procedure>(blob-u64-ref endianness blob k)</procedure>
136
137<procedure>(blob-s64-ref endianness blob k)</procedure>
138
139<procedure>(blob-u64-native-ref blob k)</procedure>
140
141<procedure>(blob-s64-native-ref blob k)</procedure>
142
143<procedure>(blob-u64-set! endianness blob k n)</procedure>
144
145<procedure>(blob-s64-set! endianness blob k n)</procedure>
146
147<procedure>(blob-u64-native-set! blob k n)</procedure>
148
149<procedure>(blob-s64-native-set! blob k n)</procedure>
150
151K must be a valid index of blob; so must the indices {k, ..., k+ 7}. Endianness must be an endianness object.
152
153These retrieve and set eight-octet representations of numbers at indices {k, ..., k+ 7}, according to the endianness specified by endianness. The procedures with u64 in their names deal with the unsigned representation, those with s64 with the two's complement representation.
154
155The procedures with native in their names employ the native endianness, and only work at aligned indices: {{k}} must be a multiple of 8. It is an error to use them at non-aligned indices.
156
157<procedure>(blob=? blob-1 blob-2)</procedure>
158
159Returns {{#t}} if blob-1 and blob-2 are equal---that is, if they have the same length and equal octets at all valid indices.
160
161<procedure>(blob-copy! source source-start target target-start n)</procedure>
162
163Copies data from blob source to blob target. Source-start, target-start, and {{n}} must be non-negative exact integers that satisfy
164
165{{0 <= source-start <= source-start + n <= (blob-length source)}}
166
167{{0 <= target-start <= target-start + n <= (blob-length target)}}
168
169This copies the octets from source at indices {{[source-start, source-start + n)}} to consecutive indices in target starting at target-index.
170
171This must work even if the memory regions for the source and the target overlap, i.e., the octets at the target location after the copy must be equal to the octets at the source location before the copy.
172
173The return values are unspecified.
174
175<procedure>(blob-copy blob)</procedure>
176
177Returns a newly allocated copy of blob blob.
178
179<procedure>(blob->u8-list blob)</procedure>
180
181<procedure>(u8-list->blob blob)</procedure>
182
183{{blob->u8-listreturns}} a newly allocated list of the octets of blob in the same order.
184
185{{U8-list->blob}} returns a newly allocated blob whose elements are the elements of list octets, which must all be octets, in the same order. Analogous to {{list->vector}}.
186
187<procedure>(blob->uint-list size endianness blob)</procedure>
188
189<procedure>(blob->sint-list size endianness blob)</procedure>
190
191<procedure>(uint-list->blob size endianness list)</procedure>
192
193<procedure>(sint-list->blob size endianness list)</procedure>
194
195Size must be a positive exact integer. Endianness must be an endianness object.
196
197These convert between lists of integers and their consecutive representations according to size and endianness in blobs in the same way as {{blob->u8-list}}, {{blob->s8-list}}, u8-{{list->blob}}, and {{s8-list->blob}} do for one-octet representations.
198=== Examples
199The [[https://srfi.schemers.org/srfi-74/example.scm|test suite]] doubles as a source of examples.
200=== References
201* [[http://srfi.schemers.org/srfi-4/|SRFI 4]] (Homogeneous numeric vector datatypes)
202* [[http://srfi.schemers.org/srfi-56/|SRFI 56]] (Binary I/O)
203* [[http://srfi.schemers.org/srfi-66/|SRFI 66]] (Octet Vectors)
204=== Authors
205* Michael Sperber
206* Ported to Chicken 5 by Sergey Goldgaber
207=== Copyright
208Copyright (C) Michael Sperber (2005). All Rights Reserved.
209
210Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
211
212The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
213
214THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
215=== Version history
216* [[https://github.com/diamond-lizard/srfi-74/releases/tag/0.1|0.1]] - Ported to Chicken Scheme 5
217
Note: See TracBrowser for help on using the repository browser.