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 @cindex IEEE-754 floating point numbers
  18
  19 A @dfn{bytevector} is a raw bit string.  The @code{(rnrs bytevector)}
  20 module provides procedures to manipulate bytevectors and interpret their
  21 contents in a number of ways: bytevector contents can be accessed as
  22 signed or unsigned integer of various sizes and endianness, as IEEE-754
  23 floating point numbers, or as strings.  It is a useful tool to decode
  24 binary data.
  25
  26 @menu
  27 * Bytevector Endianness::       Dealing with byte order.
  28 * Bytevector Manipulation::     Creating, copying, manipulating bytevectors.
  29 * Bytevectors as Integers::     Interpreting bytes as integers.
  30 * Bytevectors and Integer Lists::  Converting to/from an integer list.
  31 @end menu
  32
  33 @node Bytevector Endianness
  34 @subsection Endianness
  35
  36 @cindex endianness
  37 Some of the following procedures take an @var{endianness} parameter.
  38 The @dfn{endianness} is defined is defined as the order of bytes in
  39 multi-byte numbers: numbers encoded in @dfn{big endian} have their most
  40 significant bytes written first, whereas numbers encoded in @dfn{little
  41 endian} have their least significant bytes first@footnote{Other
  42 ``endiannesses'' exist but big and little endian are the most common.}.
  43 Little endian is the native endianness of the IA32 architecture and its
  44 derivatives, while big endian is native to SPARC and PowerPC, among
  45 others.  The @code{native-endianness} procedure returns the native
  46 endianness of the machine it runs on.
  47
  48 @deffn {Scheme Procedure} native-endianness
  49 @deffnx {C Function} scm_r6rs_native_endianness ()
  50 Return a value denoting the native endianness of the host machine.
  51 @end deffn
  52
  53
  54 @node Bytevector Manipulation
  55 @subsection Manipulating Bytevectors
  56
  57 Bytevectors can be created, copied, and analyzed with the following
  58 procedures.
  59
  60 @deffn {Scheme Procedure} make-bytevector len [fill]
  61 @deffnx {C Function} scm_r6rs_make_bytevector (len, fill)
  62 @deffnx {C Function} scm_r6rs_c_make_bytevector (unsigned len)
  63 Return a new bytevector of @var{len} bytes.  Optionally, if @var{fill}
  64 is given, fill it with @var{fill}; @var{fill} must be an 8-bit signed
  65 integer, i.e., in the range [-128,127].
  66 @end deffn
  67
  68 @deffn {Scheme Procedure} bytevector? obj
  69 @deffnx {C Function} scm_r6rs_bytevector_p (obj)
  70 Return true if @var{obj} is a bytevector.
  71 @end deffn
  72
  73 @deffn {Scheme Procedure} bytevector-length bv
  74 @deffnx {C Function} scm_r6rs_bytevector_length (bv)
  75 Return the length in bytes of bytevector @var{bv}.
  76 @end deffn
  77
  78 @deffn {Scheme Procedure} bytevector=? bv1 bv2
  79 @deffnx {C Function} scm_r6rs_bytevector_eq_p (bv1, bv2)
  80 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
  81 length and contents.
  82 @end deffn
  83
  84 @deffn {Scheme Procedure} bytevector-fill! bv fill
  85 @deffnx {C Function} scm_r6rs_bytevector_fill_x (bv, fill)
  86 Fill bytevector @var{bv} with @var{fill}, a byte.
  87 @end deffn
  88
  89 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
  90 @deffnx {C Function} scm_r6rs_bytevector_copy_x (source, source_start, target, target_start, len)
  91 Copy @var{len} bytes from @var{source} into @var{target}, starting
  92 reading from @var{source-start} (a positive index within @var{source})
  93 and start writing at @var{target-start}.
  94 @end deffn
  95
  96 @deffn {Scheme Procedure} bytevector-copy bv
  97 @deffnx {C Function} scm_r6rs_bytevector_copy (bv)
  98 Return a newly allocated copy of @var{bv}.
  99 @end deffn
 100
 101
 102 @node Bytevectors as Integers
 103 @subsection Interpreting Bytevector Contents as Integers
 104
 105 The contents of a bytevector can be interpreted as a sequence of
 106 integers of any given size, sign, and endianness.
 107
 108 @lisp
 109 (let ((bv (make-bytevector 4)))
 110   (bytevector-u8-set! bv 0 #x12)
 111   (bytevector-u8-set! bv 1 #x34)
 112   (bytevector-u8-set! bv 2 #x56)
 113   (bytevector-u8-set! bv 3 #x78)
 114
 115   (map (lambda (number)
 116          (number->string number 16))
 117        (list (bytevector-u8-ref bv 0)
 118              (bytevector-u16-ref bv 0 (endianness big))
 119              (bytevector-u32-ref bv 0 (endianness little)))))
 120
 121 @result{} ("12" "1234" "78563412")
 122 @end lisp
 123
 124 The most generic procedures to interpret bytevector contents as integers
 125 are described below.
 126
 127 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
 128 @deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
 129 @deffnx {C Function} scm_r6rs_bytevector_uint_ref (bv, index, endianness, size)
 130 @deffnx {C Function} scm_r6rs_bytevector_sint_ref (bv, index, endianness, size)
 131 Return the @var{size}-byte long unsigned (resp. signed) integer at
 132 index @var{index} in @var{bv}, decoded according to @var{endianness}.
 133 @end deffn
 134
 135 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
 136 @deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
 137 @deffnx {C Function} scm_r6rs_bytevector_uint_set_x (bv, index, value, endianness, size)
 138 @deffnx {C Function} scm_r6rs_bytevector_sint_set_x (bv, index, value, endianness, size)
 139 Set the @var{size}-byte long unsigned (resp. signed) integer at
 140 @var{index} to @var{value}, encoded according to @var{endianness}.
 141 @end deffn
 142
 143 The following procedures are similar to the ones above, but specialized
 144 to a given integer size:
 145
 146 @deffn {Scheme Procedure} bytevector-u8-ref bv index
 147 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
 148 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
 149 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
 150 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
 151 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
 152 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
 153 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
 154 @deffnx {C Function} scm_r6rs_bytevector_u8_ref (bv, index)
 155 @deffnx {C Function} scm_r6rs_bytevector_s8_ref (bv, index)
 156 @deffnx {C Function} scm_r6rs_bytevector_u16_ref (bv, index, endianness)
 157 @deffnx {C Function} scm_r6rs_bytevector_s16_ref (bv, index, endianness)
 158 @deffnx {C Function} scm_r6rs_bytevector_u32_ref (bv, index, endianness)
 159 @deffnx {C Function} scm_r6rs_bytevector_s32_ref (bv, index, endianness)
 160 @deffnx {C Function} scm_r6rs_bytevector_u64_ref (bv, index, endianness)
 161 @deffnx {C Function} scm_r6rs_bytevector_s64_ref (bv, index, endianness)
 162 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
 163 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
 164 @var{endianness}.
 165 @end deffn
 166
 167 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
 168 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
 169 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
 170 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
 171 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
 172 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
 173 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
 174 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
 175 @deffnx {C Function} scm_r6rs_bytevector_u8_set_x (bv, index, value)
 176 @deffnx {C Function} scm_r6rs_bytevector_s8_set_x (bv, index, value)
 177 @deffnx {C Function} scm_r6rs_bytevector_u16_set_x (bv, index, value, endianness)
 178 @deffnx {C Function} scm_r6rs_bytevector_s16_set_x (bv, index, value, endianness)
 179 @deffnx {C Function} scm_r6rs_bytevector_u32_set_x (bv, index, value, endianness)
 180 @deffnx {C Function} scm_r6rs_bytevector_s32_set_x (bv, index, value, endianness)
 181 @deffnx {C Function} scm_r6rs_bytevector_u64_set_x (bv, index, value, endianness)
 182 @deffnx {C Function} scm_r6rs_bytevector_s64_set_x (bv, index, value, endianness)
 183 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
 184 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
 185 @var{endianness}.
 186 @end deffn
 187
 188 Finally, a variant specialized for the host's endianness is available
 189 for each of these functions (with the exception of the @code{u8}
 190 accessors, for obvious reasons):
 191
 192 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
 193 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
 194 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
 195 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
 196 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
 197 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
 198 @deffnx {C Function} scm_r6rs_bytevector_u16_native_ref (bv, index)
 199 @deffnx {C Function} scm_r6rs_bytevector_s16_native_ref (bv, index)
 200 @deffnx {C Function} scm_r6rs_bytevector_u32_native_ref (bv, index)
 201 @deffnx {C Function} scm_r6rs_bytevector_s32_native_ref (bv, index)
 202 @deffnx {C Function} scm_r6rs_bytevector_u64_native_ref (bv, index)
 203 @deffnx {C Function} scm_r6rs_bytevector_s64_native_ref (bv, index)
 204 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
 205 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
 206 host's native endianness.
 207 @end deffn
 208
 209 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
 210 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
 211 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
 212 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
 213 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
 214 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
 215 @deffnx {C Function} scm_r6rs_bytevector_u16_native_set_x (bv, index, value)
 216 @deffnx {C Function} scm_r6rs_bytevector_s16_native_set_x (bv, index, value)
 217 @deffnx {C Function} scm_r6rs_bytevector_u32_native_set_x (bv, index, value)
 218 @deffnx {C Function} scm_r6rs_bytevector_s32_native_set_x (bv, index, value)
 219 @deffnx {C Function} scm_r6rs_bytevector_u64_native_set_x (bv, index, value)
 220 @deffnx {C Function} scm_r6rs_bytevector_s64_native_set_x (bv, index, value)
 221 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
 222 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
 223 host's native endianness.
 224 @end deffn
 225
 226
 227 @node Bytevectors and Integer Lists
 228 @subsection Converting Bytevectors to/from Integer Lists
 229
 230 Bytevector contents can readily be converted to/from lists of signed or
 231 unsigned integers:
 232
 233 @lisp
 234 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
 235                        (endianness little) 2)
 236 @result{} (-1 -1)
 237 @end lisp
 238
 239 @deffn {Scheme Procedure} bytevector->u8-list bv
 240 @deffnx {C Function} scm_r6rs_bytevector_to_u8_list (bv)
 241 Return a newly allocated list of unsigned 8-bit integers from the
 242 contents of @var{bv}.
 243 @end deffn
 244
 245 @deffn {Scheme Procedure} u8-list->bytevector lst
 246 @deffnx {C Function} scm_r6rs_u8_list_to_bytevector (lst)
 247 Return a newly allocated bytevector consisting of the unsigned 8-bit
 248 integers listed in @var{lst}.
 249 @end deffn
 250
 251 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
 252 @deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
 253 @deffnx {C Function} scm_r6rs_bytevector_to_uint_list (bv, endianness, size)
 254 @deffnx {C Function} scm_r6rs_bytevector_to_sint_list (bv, endianness, size)
 255 Return a list of unsigned (resp. signed) integers of @var{size} bytes
 256 representing the contents of @var{bv}, decoded according to
 257 @var{endianness}.
 258 @end deffn
 259
 260
 261 FIXME: Finish.
 262
 263 @c LocalWords:  Bytevectors bytevector bytevectors endianness  endian accessors
 264 @c LocalWords:  endiannesses
 265
 266 @c Local Variables:
 267 @c ispell-local-dictionary: "american"
 268 @c End:
 269