aboutsummaryrefslogtreecommitdiffstats
path: root/byte.txi
blob: 20bc8e02f64608640d3cbd9ec38daca7cccb5318 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
@code{(require 'byte)}
@ftindex byte

@noindent
Some algorithms are expressed in terms of arrays of small integers.
Using Scheme strings to implement these arrays is not portable vis-a-vis
the correspondence between integers and characters and non-ascii
character sets.  These functions abstract the notion of a @dfn{byte}.
@cindex byte
@cindex byte


@defun byte-ref bytes k

@var{k} must be a valid index of @var{bytes}.  @code{byte-ref} returns byte @var{k} of @var{bytes} using
zero-origin indexing.
@end defun


@deffn {Procedure} byte-set! bytes k byte

@var{k} must be a valid index of @var{bytes}, and @var{byte} must be a small
nonnegative integer.  @code{byte-set!} stores @var{byte} in element @var{k} of @var{bytes} and
returns an unspecified value.  @c <!>
@end deffn


@defun make-bytes k byte


@defunx make-bytes k
@code{make-bytes} returns a newly allocated byte-array of length @var{k}.  If @var{byte} is
given, then all elements of the byte-array are initialized to @var{byte},
otherwise the contents of the byte-array are unspecified.
@end defun


@defun bytes-length bytes

@code{bytes-length} returns length of byte-array @var{bytes}.
@end defun


@defun bytes byte @dots{}

Returns a newly allocated byte-array composed of the small
nonnegative arguments.
@end defun


@defun list->bytes bytes

@code{list->bytes} returns a newly allocated byte-array formed from the small
nonnegative integers in the list @var{bytes}.
@end defun


@defun bytes->list bytes

@code{bytes->list} returns a newly allocated list of the bytes that make up the
given byte-array.
@end defun

@noindent
@code{Bytes->list} and @code{list->bytes} are inverses so far as
@code{equal?} is concerned.
@findex equal?


@defun bytes->string bytes

Returns a new string formed from applying @code{integer->char} to
each byte in @code{bytes->string}.  Note that this may signal an error for bytes
having values between 128 and 255.
@end defun


@defun string->bytes string

Returns a new byte-array formed from applying @code{char->integer}
to each character in @code{string->bytes}.  Note that this may signal an error if an
integer is larger than 255.
@end defun


@defun bytes-copy bytes

Returns a newly allocated copy of the given @var{bytes}.
@end defun


@defun subbytes bytes start end

@var{bytes} must be a bytes, and @var{start} and @var{end}
must be exact integers satisfying

@center 0 <= @var{start} <= @var{end} <= @w{@t{(bytes-length @var{bytes})@r{.}}}

@code{subbytes} returns a newly allocated bytes formed from the bytes of
@var{bytes} beginning with index @var{start} (inclusive) and ending with index
@var{end} (exclusive).
@end defun


@deffn {Procedure} bytes-reverse! bytes

Reverses the order of byte-array @var{bytes}.
@end deffn


@defun bytes-reverse bytes

Returns a newly allocated bytes-array consisting of the elements of
@var{bytes} in reverse order.
@end defun

@noindent
@cindex binary
Input and output of bytes should be with ports opened in @dfn{binary}
@cindex binary
mode (@pxref{Input/Output}).  Calling @code{open-file} with @r{'rb} or
@findex open-file
@r{'wb} modes argument will return a binary port if the Scheme
implementation supports it.


@defun write-byte byte port


@defunx write-byte byte
Writes the byte @var{byte} (not an external representation of the byte) to
the given @var{port} and returns an unspecified value.  The @var{port} argument may
be omitted, in which case it defaults to the value returned by
@code{current-output-port}.
@findex current-output-port
@end defun


@defun read-byte port


@defunx read-byte
Returns the next byte available from the input @var{port}, updating the @var{port}
to point to the following byte.  If no more bytes are available, an
end-of-file object is returned.  @var{port} may be omitted, in which case it
defaults to the value returned by @code{current-input-port}.
@findex current-input-port
@end defun

@noindent
When reading and writing binary numbers with @code{read-bytes} and
@code{write-bytes}, the sign of the length argument determines the
endianness (order) of bytes.  Positive treats them as big-endian,
the first byte input or output is highest order.  Negative treats
them as little-endian, the first byte input or output is the lowest
order.

@noindent
Once read in, SLIB treats byte sequences as big-endian.  The
multi-byte sequences produced and used by number conversion routines
@pxref{Byte/Number Conversions} are always big-endian.


@defun read-bytes n port


@defunx read-bytes n
@code{read-bytes} returns a newly allocated bytes-array filled with
@code{(abs @var{n})} bytes read from @var{port}.  If @var{n} is positive, then
the first byte read is stored at index 0; otherwise the last byte
read is stored at index 0.  Note that the length of the returned
byte-array will be less than @code{(abs @var{n})} if @var{port} reaches
end-of-file.

@var{port} may be omitted, in which case it defaults to the value returned
by @code{current-input-port}.
@end defun


@defun write-bytes bytes n port


@defunx write-bytes bytes n
@code{write-bytes} writes @code{(abs @var{n})} bytes to output-port @var{port}.  If @var{n} is
positive, then the first byte written is index 0 of @var{bytes}; otherwise
the last byte written is index 0 of @var{bytes}.  @code{write-bytes} returns an unspecified
value.

@var{port} may be omitted, in which case it defaults to the value returned
by @code{current-output-port}.
@end defun

@noindent
@code{subbytes-read!} and @code{subbytes-write} provide
lower-level procedures for reading and writing blocks of bytes.  The
relative size of @var{start} and @var{end} determines the order of
writing.


@deffn {Procedure} subbytes-read! bts start end port


@deffnx {Procedure} subbytes-read! bts start end
Fills @var{bts} with up to @code{(abs (- @var{start} @var{end}))} bytes
read from @var{port}.  The first byte read is stored at index @var{bts}.
@code{subbytes-read!} returns the number of bytes read.

@var{port} may be omitted, in which case it defaults to the value returned
by @code{current-input-port}.
@end deffn


@defun subbytes-write bts start end port


@defunx subbytes-write bts start end
@code{subbytes-write} writes @code{(abs (- @var{start} @var{end}))} bytes to
output-port @var{port}.  The first byte written is index @var{start} of @var{bts}.  @code{subbytes-write}
returns the number of bytes written.

@var{port} may be omitted, in which case it defaults to the value returned
by @code{current-output-port}.
@end defun