doc/api-r6rs.texi

   1 @cindex R6RS
   2 @cindex R6RS libraries
   3
   4 This section describes Guile's implementation of some of the standard
   5 libraries defined in the ``Revised^6 Report on the Algorithmic
   6 Language'' aka. @url{http://www.r6rs.org/, R6RS}.
   7
   8 @menu
   9 * Bytevectors::                 Interpreting raw bit strings.
  10 @end menu
  11
  12 @c *********************************************************************
  13 @node Bytevectors
  14 @section Bytevectors
  15
  16 @cindex bytevector
  17
  18 A @dfn{bytevector} is a raw bit string.  The @code{(rnrs bytevector)}
  19 module provides procedures to manipulate bytevectors and interpret their
  20 contents in a number of ways: bytevector contents can be accessed as
  21 signed or unsigned integer of various sizes and endianness, as IEEE-754
  22 floating point numbers, or as strings.  It is a useful tool to decode
  23 binary data.
  24
  25 @menu
  26 * Bytevector Endianness::       Dealing with byte order.
  27 * Bytevector Manipulation::     Creating, copying, manipulating bytevectors.
  28 * Bytevectors as Integers::     Interpreting bytes as integers.
  29 * Bytevectors and Integer Lists::  Converting to/from an integer list.
  30 * Bytevectors as Floats::       Interpreting bytes as real numbers.
  31 @end menu
  32
  33 @node Bytevector Endianness
  34 @subsection Endianness
  35
  36 @cindex endianness
  37 @cindex byte order
  38 @cindex word order
  39
  40 Some of the following procedures take an @var{endianness} parameter.
  41 The @dfn{endianness} is defined is defined as the order of bytes in
  42 multi-byte numbers: numbers encoded in @dfn{big endian} have their most
  43 significant bytes written first, whereas numbers encoded in @dfn{little
  44 endian} have their least significant bytes first@footnote{Big and little
  45 endian are the most common ``endiannesses'' but others exist.  For
  46 instance, the GNU MP library allows @dfn{word order} to be specified
  47 independently of @dfn{byte order} (@pxref{Integer Import and Export,,,
  48 gmp, The GNU Multiple Precision Arithmetic Library Manual}).}  Little
  49 endian is the native endianness of the IA32 architecture and its
  50 derivatives, while big endian is native to SPARC and PowerPC, among
  51 others.  The @code{native-endianness} procedure returns the native
  52 endianness of the machine it runs on.
  53
  54 @deffn {Scheme Procedure} native-endianness
  55 @deffnx {C Function} scm_r6rs_native_endianness ()
  56 Return a value denoting the native endianness of the host machine.
  57 @end deffn
  58
  59 @deffn {Scheme Macro} endianness symbol
  60 Return an object denoting the endianness specified by @var{symbol}.  If
  61 @var{symbol} is neither @code{big} nor @code{little} then a compile-time
  62 error is raised.
  63 @end deffn
  64
  65 @defvr {C Variable} scm_r6rs_endianness_big
  66 @defvrx {C Variable} scm_r6rs_endianness_little
  67 The objects denoting big (resp. little) endianness.
  68 @end defvr
  69
  70
  71 @node Bytevector Manipulation
  72 @subsection Manipulating Bytevectors
  73
  74 Bytevectors can be created, copied, and analyzed with the following
  75 procedures.
  76
  77 @deffn {Scheme Procedure} make-bytevector len [fill]
  78 @deffnx {C Function} scm_r6rs_make_bytevector (len, fill)
  79 @deffnx {C Function} scm_r6rs_c_make_bytevector (unsigned len)
  80 Return a new bytevector of @var{len} bytes.  Optionally, if @var{fill}
  81 is given, fill it with @var{fill}; @var{fill} must be an 8-bit signed
  82 integer, i.e., in the range [-128,127].
  83 @end deffn
  84
  85 @deffn {Scheme Procedure} bytevector? obj
  86 @deffnx {C Function} scm_r6rs_bytevector_p (obj)
  87 Return true if @var{obj} is a bytevector.
  88 @end deffn
  89
  90 @deffn {Scheme Procedure} bytevector-length bv
  91 @deffnx {C Function} scm_r6rs_bytevector_length (bv)
  92 Return the length in bytes of bytevector @var{bv}.
  93 @end deffn
  94
  95 @deffn {Scheme Procedure} bytevector=? bv1 bv2
  96 @deffnx {C Function} scm_r6rs_bytevector_eq_p (bv1, bv2)
  97 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
  98 length and contents.
  99 @end deffn
 100
 101 @deffn {Scheme Procedure} bytevector-fill! bv fill
 102 @deffnx {C Function} scm_r6rs_bytevector_fill_x (bv, fill)
 103 Fill bytevector @var{bv} with @var{fill}, a byte.
 104 @end deffn
 105
 106 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
 107 @deffnx {C Function} scm_r6rs_bytevector_copy_x (source, source_start, target, target_start, len)
 108 Copy @var{len} bytes from @var{source} into @var{target}, starting
 109 reading from @var{source-start} (a positive index within @var{source})
 110 and start writing at @var{target-start}.
 111 @end deffn
 112
 113 @deffn {Scheme Procedure} bytevector-copy bv
 114 @deffnx {C Function} scm_r6rs_bytevector_copy (bv)
 115 Return a newly allocated copy of @var{bv}.
 116 @end deffn
 117
 118
 119 @node Bytevectors as Integers
 120 @subsection Interpreting Bytevector Contents as Integers
 121
 122 The contents of a bytevector can be interpreted as a sequence of
 123 integers of any given size, sign, and endianness.
 124
 125 @lisp
 126 (let ((bv (make-bytevector 4)))
 127   (bytevector-u8-set! bv 0 #x12)
 128   (bytevector-u8-set! bv 1 #x34)
 129   (bytevector-u8-set! bv 2 #x56)
 130   (bytevector-u8-set! bv 3 #x78)
 131
 132   (map (lambda (number)
 133          (number->string number 16))
 134        (list (bytevector-u8-ref bv 0)
 135              (bytevector-u16-ref bv 0 (endianness big))
 136              (bytevector-u32-ref bv 0 (endianness little)))))
 137
 138 @result{} ("12" "1234" "78563412")
 139 @end lisp
 140
 141 The most generic procedures to interpret bytevector contents as integers
 142 are described below.
 143
 144 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
 145 @deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
 146 @deffnx {C Function} scm_r6rs_bytevector_uint_ref (bv, index, endianness, size)
 147 @deffnx {C Function} scm_r6rs_bytevector_sint_ref (bv, index, endianness, size)
 148 Return the @var{size}-byte long unsigned (resp. signed) integer at
 149 index @var{index} in @var{bv}, decoded according to @var{endianness}.
 150 @end deffn
 151
 152 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
 153 @deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
 154 @deffnx {C Function} scm_r6rs_bytevector_uint_set_x (bv, index, value, endianness, size)
 155 @deffnx {C Function} scm_r6rs_bytevector_sint_set_x (bv, index, value, endianness, size)
 156 Set the @var{size}-byte long unsigned (resp. signed) integer at
 157 @var{index} to @var{value}, encoded according to @var{endianness}.
 158 @end deffn
 159
 160 The following procedures are similar to the ones above, but specialized
 161 to a given integer size:
 162
 163 @deffn {Scheme Procedure} bytevector-u8-ref bv index
 164 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
 165 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
 166 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
 167 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
 168 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
 169 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
 170 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
 171 @deffnx {C Function} scm_r6rs_bytevector_u8_ref (bv, index)
 172 @deffnx {C Function} scm_r6rs_bytevector_s8_ref (bv, index)
 173 @deffnx {C Function} scm_r6rs_bytevector_u16_ref (bv, index, endianness)
 174 @deffnx {C Function} scm_r6rs_bytevector_s16_ref (bv, index, endianness)
 175 @deffnx {C Function} scm_r6rs_bytevector_u32_ref (bv, index, endianness)
 176 @deffnx {C Function} scm_r6rs_bytevector_s32_ref (bv, index, endianness)
 177 @deffnx {C Function} scm_r6rs_bytevector_u64_ref (bv, index, endianness)
 178 @deffnx {C Function} scm_r6rs_bytevector_s64_ref (bv, index, endianness)
 179 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
 180 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
 181 @var{endianness}.
 182 @end deffn
 183
 184 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
 185 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
 186 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
 187 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
 188 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
 189 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
 190 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
 191 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
 192 @deffnx {C Function} scm_r6rs_bytevector_u8_set_x (bv, index, value)
 193 @deffnx {C Function} scm_r6rs_bytevector_s8_set_x (bv, index, value)
 194 @deffnx {C Function} scm_r6rs_bytevector_u16_set_x (bv, index, value, endianness)
 195 @deffnx {C Function} scm_r6rs_bytevector_s16_set_x (bv, index, value, endianness)
 196 @deffnx {C Function} scm_r6rs_bytevector_u32_set_x (bv, index, value, endianness)
 197 @deffnx {C Function} scm_r6rs_bytevector_s32_set_x (bv, index, value, endianness)
 198 @deffnx {C Function} scm_r6rs_bytevector_u64_set_x (bv, index, value, endianness)
 199 @deffnx {C Function} scm_r6rs_bytevector_s64_set_x (bv, index, value, endianness)
 200 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
 201 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
 202 @var{endianness}.
 203 @end deffn
 204
 205 Finally, a variant specialized for the host's endianness is available
 206 for each of these functions (with the exception of the @code{u8}
 207 accessors, for obvious reasons):
 208
 209 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
 210 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
 211 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
 212 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
 213 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
 214 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
 215 @deffnx {C Function} scm_r6rs_bytevector_u16_native_ref (bv, index)
 216 @deffnx {C Function} scm_r6rs_bytevector_s16_native_ref (bv, index)
 217 @deffnx {C Function} scm_r6rs_bytevector_u32_native_ref (bv, index)
 218 @deffnx {C Function} scm_r6rs_bytevector_s32_native_ref (bv, index)
 219 @deffnx {C Function} scm_r6rs_bytevector_u64_native_ref (bv, index)
 220 @deffnx {C Function} scm_r6rs_bytevector_s64_native_ref (bv, index)
 221 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
 222 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
 223 host's native endianness.
 224 @end deffn
 225
 226 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
 227 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
 228 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
 229 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
 230 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
 231 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
 232 @deffnx {C Function} scm_r6rs_bytevector_u16_native_set_x (bv, index, value)
 233 @deffnx {C Function} scm_r6rs_bytevector_s16_native_set_x (bv, index, value)
 234 @deffnx {C Function} scm_r6rs_bytevector_u32_native_set_x (bv, index, value)
 235 @deffnx {C Function} scm_r6rs_bytevector_s32_native_set_x (bv, index, value)
 236 @deffnx {C Function} scm_r6rs_bytevector_u64_native_set_x (bv, index, value)
 237 @deffnx {C Function} scm_r6rs_bytevector_s64_native_set_x (bv, index, value)
 238 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
 239 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
 240 host's native endianness.
 241 @end deffn
 242
 243
 244 @node Bytevectors and Integer Lists
 245 @subsection Converting Bytevectors to/from Integer Lists
 246
 247 Bytevector contents can readily be converted to/from lists of signed or
 248 unsigned integers:
 249
 250 @lisp
 251 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
 252                        (endianness little) 2)
 253 @result{} (-1 -1)
 254 @end lisp
 255
 256 @deffn {Scheme Procedure} bytevector->u8-list bv
 257 @deffnx {C Function} scm_r6rs_bytevector_to_u8_list (bv)
 258 Return a newly allocated list of unsigned 8-bit integers from the
 259 contents of @var{bv}.
 260 @end deffn
 261
 262 @deffn {Scheme Procedure} u8-list->bytevector lst
 263 @deffnx {C Function} scm_r6rs_u8_list_to_bytevector (lst)
 264 Return a newly allocated bytevector consisting of the unsigned 8-bit
 265 integers listed in @var{lst}.
 266 @end deffn
 267
 268 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
 269 @deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
 270 @deffnx {C Function} scm_r6rs_bytevector_to_uint_list (bv, endianness, size)
 271 @deffnx {C Function} scm_r6rs_bytevector_to_sint_list (bv, endianness, size)
 272 Return a list of unsigned (resp. signed) integers of @var{size} bytes
 273 representing the contents of @var{bv}, decoded according to
 274 @var{endianness}.
 275 @end deffn
 276
 277
 278 @node Bytevectors as Floats
 279 @subsection Interpreting Bytevector Contents as Floating Point Numbers
 280
 281 @cindex IEEE-754 floating point numbers
 282
 283 Bytevector contents can also be accessed as IEEE-754 single- or
 284 double-precision floating point numbers (respectively 32 and 64-bit
 285 long) using the procedures described here.
 286
 287 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
 288 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
 289 @deffnx {C Function} scm_r6rs_bytevector_ieee_single_ref (bv, index, endianness)
 290 @deffnx {C Function} scm_r6rs_bytevector_ieee_double_ref (bv, index, endianness)
 291 Return the IEEE-754 single-precision floating point number from @var{bv}
 292 at @var{index} according to @var{endianness}.
 293 @end deffn
 294
 295 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
 296 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
 297 @deffnx scm_r6rs_bytevector_ieee_single_set_x (bv, index, value, endianness)
 298 @deffnx scm_r6rs_bytevector_ieee_double_set_x (bv, index, value, endianness)
 299 Store real number @var{value} in @var{bv} at @var{index} according to
 300 @var{endianness}.
 301 @end deffn
 302
 303 Specialized procedures are also available:
 304
 305 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
 306 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
 307 @deffnx {C Function} scm_r6rs_bytevector_ieee_single_native_ref (bv, index)
 308 @deffnx {C Function} scm_r6rs_bytevector_ieee_double_native_ref (bv, index)
 309 Return the IEEE-754 single-precision floating point number from @var{bv}
 310 at @var{index} according to the host's native endianness.
 311 @end deffn
 312
 313 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
 314 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
 315 @deffnx scm_r6rs_bytevector_ieee_single_native_set_x (bv, index, value)
 316 @deffnx scm_r6rs_bytevector_ieee_double_native_set_x (bv, index, value)
 317 Store real number @var{value} in @var{bv} at @var{index} according to
 318 the host's native endianness.
 319 @end deffn
 320
 321
 322
 323 FIXME: Finish.
 324
 325 @c LocalWords:  Bytevectors bytevector bytevectors endianness  endian accessors
 326 @c LocalWords:  endiannesses
 327
 328 @c Local Variables:
 329 @c ispell-local-dictionary: "american"
 330 @c End:
 331