aboutsummaryrefslogtreecommitdiffstats
path: root/bytenumb.txi
blob: d5fc680e23a510c97603385f4e10d63186b54be1 (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
@code{(require 'byte-number)}
@ftindex byte-number

@noindent
The multi-byte sequences produced and used by numeric conversion
routines are always big-endian.  Endianness can be changed during
reading and writing bytes using @code{read-bytes} and
@code{write-bytes} @xref{Byte, read-bytes}.

@noindent
The sign of the length argument to bytes/integer conversion
procedures determines the signedness of the number.


@defun bytes->integer bytes n

Converts the first @code{(abs @var{n})} bytes of big-endian @var{bytes} array
to an integer.  If @var{n} is negative then the integer coded by the
bytes are treated as two's-complement (can be negative).

@example
(bytes->integer (bytes   0   0   0  15) -4)   @result{}          15
(bytes->integer (bytes   0   0   0  15)  4)   @result{}          15
(bytes->integer (bytes 255 255 255 255) -4)   @result{}          -1
(bytes->integer (bytes 255 255 255 255)  4)   @result{}  4294967295
(bytes->integer (bytes 128   0   0   0) -4)   @result{} -2147483648
(bytes->integer (bytes 128   0   0   0)  4)   @result{}  2147483648
@end example
@end defun


@defun integer->bytes n len

Converts the integer @var{n} to a byte-array of @code{(abs @var{n})}
bytes.  If @var{n} and @var{len} are both negative, then the bytes in the
returned array are coded two's-complement.

@example
(bytes->list (integer->bytes          15 -4))   @result{} (0 0 0 15)
(bytes->list (integer->bytes          15  4))   @result{} (0 0 0 15)
(bytes->list (integer->bytes          -1 -4))   @result{} (255 255 255 255)
(bytes->list (integer->bytes  4294967295  4))   @result{} (255 255 255 255)
(bytes->list (integer->bytes -2147483648 -4))   @result{} (128 0 0 0)
(bytes->list (integer->bytes  2147483648  4))   @result{} (128 0 0 0)
@end example
@end defun


@defun bytes->ieee-float bytes

@var{bytes} must be a 4-element byte-array.  @code{bytes->ieee-float} calculates and returns the
value of @var{bytes} interpreted as a big-endian IEEE 4-byte (32-bit) number.
@end defun

@example
(bytes->ieee-float (bytes    0    0 0 0))  @result{}  0.0
(bytes->ieee-float (bytes #x80    0 0 0))  @result{} -0.0
(bytes->ieee-float (bytes #x40    0 0 0))  @result{}  2.0
(bytes->ieee-float (bytes #x40 #xd0 0 0))  @result{}  6.5
(bytes->ieee-float (bytes #xc0 #xd0 0 0))  @result{} -6.5

(bytes->ieee-float (bytes    0 #x80 0 0))  @result{} 11.754943508222875e-39
(bytes->ieee-float (bytes    0 #x40 0 0))  @result{}  5.877471754111437e-39
(bytes->ieee-float (bytes    0    0 0 1))  @result{}  1.401298464324817e-45

(bytes->ieee-float (bytes #xff #x80 0 0))  @result{} -inf.0
(bytes->ieee-float (bytes #x7f #x80 0 0))  @result{} +inf.0
(bytes->ieee-float (bytes #x7f #x80 0 1))  @result{}  0/0
(bytes->ieee-float (bytes #x7f #xc0 0 0))  @result{}  0/0
@end example


@defun bytes->ieee-double bytes

@var{bytes} must be a 8-element byte-array.  @code{bytes->ieee-double} calculates and returns the
value of @var{bytes} interpreted as a big-endian IEEE 8-byte (64-bit) number.
@end defun

@example
(bytes->ieee-double (bytes    0    0 0 0 0 0 0 0))  @result{}  0.0
(bytes->ieee-double (bytes #x80    0 0 0 0 0 0 0))  @result{} -0.0
(bytes->ieee-double (bytes #x40    0 0 0 0 0 0 0))  @result{}  2.0
(bytes->ieee-double (bytes #x40 #x1A 0 0 0 0 0 0))  @result{}  6.5
(bytes->ieee-double (bytes #xC0 #x1A 0 0 0 0 0 0))  @result{} -6.5

(bytes->ieee-double (bytes 0 8 0 0 0 0 0 0)) @result{} 11.125369292536006e-309
(bytes->ieee-double (bytes 0 4 0 0 0 0 0 0)) @result{}  5.562684646268003e-309
(bytes->ieee-double (bytes 0 0 0 0 0 0 0 1)) @result{}  4.0e-324

(bytes->ieee-double (bytes #xFF #xF0 0 0 0 0 0 0))  @result{} -inf.0
(bytes->ieee-double (bytes #x7F #xF0 0 0 0 0 0 0))  @result{} +inf.0
(bytes->ieee-double (bytes #x7F #xF8 0 0 0 0 0 0))  @result{}  0/0
@end example


@defun ieee-float->bytes x

Returns a 4-element byte-array encoding the IEEE single-precision
floating-point of @var{x}.
@end defun

@example
(bytes->list (ieee-float->bytes  0.0))                    @result{} (0     0 0 0)
(bytes->list (ieee-float->bytes -0.0))                    @result{} (128   0 0 0)
(bytes->list (ieee-float->bytes  2.0))                    @result{} (64    0 0 0)
(bytes->list (ieee-float->bytes  6.5))                    @result{} (64  208 0 0)
(bytes->list (ieee-float->bytes -6.5))                    @result{} (192 208 0 0)

(bytes->list (ieee-float->bytes 11.754943508222875e-39))  @result{} (  0 128 0 0)
(bytes->list (ieee-float->bytes  5.877471754111438e-39))  @result{} (  0  64 0 0)
(bytes->list (ieee-float->bytes  1.401298464324817e-45))  @result{} (  0   0 0 1)

(bytes->list (ieee-float->bytes -inf.0))                  @result{} (255 128 0 0)
(bytes->list (ieee-float->bytes +inf.0))                  @result{} (127 128 0 0)
(bytes->list (ieee-float->bytes  0/0))                    @result{} (127 192 0 0)
@end example


@defun ieee-double->bytes x

Returns a 8-element byte-array encoding the IEEE double-precision
floating-point of @var{x}.
@end defun

@example
(bytes->list (ieee-double->bytes  0.0)) @result{} (0     0 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes -0.0)) @result{} (128   0 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes  2.0)) @result{} (64    0 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes  6.5)) @result{} (64   26 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes -6.5)) @result{} (192  26 0 0 0 0 0 0)

(bytes->list (ieee-double->bytes 11.125369292536006e-309))
                                        @result{} (  0   8 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes  5.562684646268003e-309))
                                        @result{} (  0   4 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes  4.0e-324))
                                        @result{} (  0   0 0 0 0 0 0 1)

(bytes->list (ieee-double->bytes -inf.0)) @result{} (255 240 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes +inf.0)) @result{} (127 240 0 0 0 0 0 0)
(bytes->list (ieee-double->bytes  0/0)) @result{} (127 248 0 0 0 0 0 0)
@end example

@subsubheading Byte Collation Order

@noindent
The @code{string<?} ordering of big-endian byte-array
representations of fixed and IEEE floating-point numbers agrees with
the numerical ordering only when those numbers are non-negative.

@noindent
Straighforward modification of these formats can extend the
byte-collating order to work for their entire ranges.  This
agreement enables the full range of numbers as keys in
@dfn{indexed-sequential-access-method} databases.
@cindex indexed-sequential-access-method


@deffn {Procedure} integer-byte-collate! byte-vector

Modifies sign bit of @var{byte-vector} so that @code{string<?} ordering of
two's-complement byte-vectors matches numerical order.  @code{integer-byte-collate!} returns
@var{byte-vector} and is its own functional inverse.
@end deffn


@defun integer-byte-collate byte-vector

Returns copy of @var{byte-vector} with sign bit modified so that @code{string<?}
ordering of two's-complement byte-vectors matches numerical order.
@code{integer-byte-collate} is its own functional inverse.
@end defun


@deffn {Procedure} ieee-byte-collate! byte-vector

Modifies @var{byte-vector} so that @code{string<?} ordering of IEEE floating-point
byte-vectors matches numerical order.  @code{ieee-byte-collate!} returns @var{byte-vector}.
@end deffn


@deffn {Procedure} ieee-byte-decollate! byte-vector

Given @var{byte-vector} modified by @code{ieee-byte-collate!}, reverses the @var{byte-vector}
modifications.
@end deffn


@defun ieee-byte-collate byte-vector

Returns copy of @var{byte-vector} encoded so that @code{string<?} ordering of IEEE
floating-point byte-vectors matches numerical order.
@end defun


@defun ieee-byte-decollate byte-vector

Given @var{byte-vector} returned by @code{ieee-byte-collate}, reverses the @var{byte-vector}
modifications.
@end defun