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 * R6RS I/O Ports::              Input/output ports.
  11 @end menu
  12
  13 @c *********************************************************************
  14 @node Bytevectors
  15 @section Bytevectors
  16
  17 @cindex bytevector
  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 The R6RS (Section 4.3.4) specifies an external representation for
  27 bytevectors, whereby the octets (integers in the range 0--255) contained
  28 in the bytevector are represented as a list prefixed by @code{#vu8}:
  29
  30 @lisp
  31 #vu8(1 53 204)
  32 @end lisp
  33
  34 denotes a 3-byte bytevector containing the octets 1, 53, and 204.  Like
  35 string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
  36 they do not need to be quoted:
  37
  38 @lisp
  39 #vu8(1 53 204)
  40 @result{} #vu8(1 53 204)
  41 @end lisp
  42
  43 @menu
  44 * Bytevector Endianness::       Dealing with byte order.
  45 * Bytevector Manipulation::     Creating, copying, manipulating bytevectors.
  46 * Bytevectors as Integers::     Interpreting bytes as integers.
  47 * Bytevectors and Integer Lists::  Converting to/from an integer list.
  48 * Bytevectors as Floats::       Interpreting bytes as real numbers.
  49 * Bytevectors as Strings::      Interpreting bytes as Unicode strings.
  50 @end menu
  51
  52 @node Bytevector Endianness
  53 @subsection Endianness
  54
  55 @cindex endianness
  56 @cindex byte order
  57 @cindex word order
  58
  59 Some of the following procedures take an @var{endianness} parameter.
  60 The @dfn{endianness} is defined is defined as the order of bytes in
  61 multi-byte numbers: numbers encoded in @dfn{big endian} have their most
  62 significant bytes written first, whereas numbers encoded in @dfn{little
  63 endian} have their least significant bytes first@footnote{Big and little
  64 endian are the most common ``endiannesses'' but others exist.  For
  65 instance, the GNU MP library allows @dfn{word order} to be specified
  66 independently of @dfn{byte order} (@pxref{Integer Import and Export,,,
  67 gmp, The GNU Multiple Precision Arithmetic Library Manual}).}  Little
  68 endian is the native endianness of the IA32 architecture and its
  69 derivatives, while big endian is native to SPARC and PowerPC, among
  70 others.  The @code{native-endianness} procedure returns the native
  71 endianness of the machine it runs on.
  72
  73 @deffn {Scheme Procedure} native-endianness
  74 @deffnx {C Function} scm_r6rs_native_endianness ()
  75 Return a value denoting the native endianness of the host machine.
  76 @end deffn
  77
  78 @deffn {Scheme Macro} endianness symbol
  79 Return an object denoting the endianness specified by @var{symbol}.  If
  80 @var{symbol} is neither @code{big} nor @code{little} then a compile-time
  81 error is raised.
  82 @end deffn
  83
  84 @defvr {C Variable} scm_r6rs_endianness_big
  85 @defvrx {C Variable} scm_r6rs_endianness_little
  86 The objects denoting big (resp. little) endianness.
  87 @end defvr
  88
  89
  90 @node Bytevector Manipulation
  91 @subsection Manipulating Bytevectors
  92
  93 Bytevectors can be created, copied, and analyzed with the following
  94 procedures.
  95
  96 @deffn {Scheme Procedure} make-bytevector len [fill]
  97 @deffnx {C Function} scm_r6rs_make_bytevector (len, fill)
  98 @deffnx {C Function} scm_r6rs_c_make_bytevector (unsigned len)
  99 Return a new bytevector of @var{len} bytes.  Optionally, if @var{fill}
 100 is given, fill it with @var{fill}; @var{fill} must be an 8-bit signed
 101 integer, i.e., in the range [-128,127].
 102 @end deffn
 103
 104 @deffn {Scheme Procedure} bytevector? obj
 105 @deffnx {C Function} scm_r6rs_bytevector_p (obj)
 106 Return true if @var{obj} is a bytevector.
 107 @end deffn
 108
 109 @deffn {Scheme Procedure} bytevector-length bv
 110 @deffnx {C Function} scm_r6rs_bytevector_length (bv)
 111 Return the length in bytes of bytevector @var{bv}.
 112 @end deffn
 113
 114 @deffn {Scheme Procedure} bytevector=? bv1 bv2
 115 @deffnx {C Function} scm_r6rs_bytevector_eq_p (bv1, bv2)
 116 Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
 117 length and contents.
 118 @end deffn
 119
 120 @deffn {Scheme Procedure} bytevector-fill! bv fill
 121 @deffnx {C Function} scm_r6rs_bytevector_fill_x (bv, fill)
 122 Fill bytevector @var{bv} with @var{fill}, a byte.
 123 @end deffn
 124
 125 @deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
 126 @deffnx {C Function} scm_r6rs_bytevector_copy_x (source, source_start, target, target_start, len)
 127 Copy @var{len} bytes from @var{source} into @var{target}, starting
 128 reading from @var{source-start} (a positive index within @var{source})
 129 and start writing at @var{target-start}.
 130 @end deffn
 131
 132 @deffn {Scheme Procedure} bytevector-copy bv
 133 @deffnx {C Function} scm_r6rs_bytevector_copy (bv)
 134 Return a newly allocated copy of @var{bv}.
 135 @end deffn
 136
 137 Low-level C macros are available.  They do not perform any
 138 type-checking; as such they should be used with care.
 139
 140 @deftypefn {C Macro} size_t SCM_R6RS_BYTEVECTOR_LENGTH (bv)
 141 Return the length in bytes of bytevector @var{bv}.
 142 @end deftypefn
 143
 144 @deftypefn {C Macro} {signed char *} SCM_R6RS_BYTEVECTOR_CONTENTS (bv)
 145 Return a pointer to the contents of bytevector @var{bv}.
 146 @end deftypefn
 147
 148
 149 @node Bytevectors as Integers
 150 @subsection Interpreting Bytevector Contents as Integers
 151
 152 The contents of a bytevector can be interpreted as a sequence of
 153 integers of any given size, sign, and endianness.
 154
 155 @lisp
 156 (let ((bv (make-bytevector 4)))
 157   (bytevector-u8-set! bv 0 #x12)
 158   (bytevector-u8-set! bv 1 #x34)
 159   (bytevector-u8-set! bv 2 #x56)
 160   (bytevector-u8-set! bv 3 #x78)
 161
 162   (map (lambda (number)
 163          (number->string number 16))
 164        (list (bytevector-u8-ref bv 0)
 165              (bytevector-u16-ref bv 0 (endianness big))
 166              (bytevector-u32-ref bv 0 (endianness little)))))
 167
 168 @result{} ("12" "1234" "78563412")
 169 @end lisp
 170
 171 The most generic procedures to interpret bytevector contents as integers
 172 are described below.
 173
 174 @deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
 175 @deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
 176 @deffnx {C Function} scm_r6rs_bytevector_uint_ref (bv, index, endianness, size)
 177 @deffnx {C Function} scm_r6rs_bytevector_sint_ref (bv, index, endianness, size)
 178 Return the @var{size}-byte long unsigned (resp. signed) integer at
 179 index @var{index} in @var{bv}, decoded according to @var{endianness}.
 180 @end deffn
 181
 182 @deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
 183 @deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
 184 @deffnx {C Function} scm_r6rs_bytevector_uint_set_x (bv, index, value, endianness, size)
 185 @deffnx {C Function} scm_r6rs_bytevector_sint_set_x (bv, index, value, endianness, size)
 186 Set the @var{size}-byte long unsigned (resp. signed) integer at
 187 @var{index} to @var{value}, encoded according to @var{endianness}.
 188 @end deffn
 189
 190 The following procedures are similar to the ones above, but specialized
 191 to a given integer size:
 192
 193 @deffn {Scheme Procedure} bytevector-u8-ref bv index
 194 @deffnx {Scheme Procedure} bytevector-s8-ref bv index
 195 @deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
 196 @deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
 197 @deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
 198 @deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
 199 @deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
 200 @deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
 201 @deffnx {C Function} scm_r6rs_bytevector_u8_ref (bv, index)
 202 @deffnx {C Function} scm_r6rs_bytevector_s8_ref (bv, index)
 203 @deffnx {C Function} scm_r6rs_bytevector_u16_ref (bv, index, endianness)
 204 @deffnx {C Function} scm_r6rs_bytevector_s16_ref (bv, index, endianness)
 205 @deffnx {C Function} scm_r6rs_bytevector_u32_ref (bv, index, endianness)
 206 @deffnx {C Function} scm_r6rs_bytevector_s32_ref (bv, index, endianness)
 207 @deffnx {C Function} scm_r6rs_bytevector_u64_ref (bv, index, endianness)
 208 @deffnx {C Function} scm_r6rs_bytevector_s64_ref (bv, index, endianness)
 209 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
 210 16, 32 or 64) from @var{bv} at @var{index}, decoded according to
 211 @var{endianness}.
 212 @end deffn
 213
 214 @deffn {Scheme Procedure} bytevector-u8-set! bv index value
 215 @deffnx {Scheme Procedure} bytevector-s8-set! bv index value
 216 @deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
 217 @deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
 218 @deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
 219 @deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
 220 @deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
 221 @deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
 222 @deffnx {C Function} scm_r6rs_bytevector_u8_set_x (bv, index, value)
 223 @deffnx {C Function} scm_r6rs_bytevector_s8_set_x (bv, index, value)
 224 @deffnx {C Function} scm_r6rs_bytevector_u16_set_x (bv, index, value, endianness)
 225 @deffnx {C Function} scm_r6rs_bytevector_s16_set_x (bv, index, value, endianness)
 226 @deffnx {C Function} scm_r6rs_bytevector_u32_set_x (bv, index, value, endianness)
 227 @deffnx {C Function} scm_r6rs_bytevector_s32_set_x (bv, index, value, endianness)
 228 @deffnx {C Function} scm_r6rs_bytevector_u64_set_x (bv, index, value, endianness)
 229 @deffnx {C Function} scm_r6rs_bytevector_s64_set_x (bv, index, value, endianness)
 230 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
 231 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
 232 @var{endianness}.
 233 @end deffn
 234
 235 Finally, a variant specialized for the host's endianness is available
 236 for each of these functions (with the exception of the @code{u8}
 237 accessors, for obvious reasons):
 238
 239 @deffn {Scheme Procedure} bytevector-u16-native-ref bv index
 240 @deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
 241 @deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
 242 @deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
 243 @deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
 244 @deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
 245 @deffnx {C Function} scm_r6rs_bytevector_u16_native_ref (bv, index)
 246 @deffnx {C Function} scm_r6rs_bytevector_s16_native_ref (bv, index)
 247 @deffnx {C Function} scm_r6rs_bytevector_u32_native_ref (bv, index)
 248 @deffnx {C Function} scm_r6rs_bytevector_s32_native_ref (bv, index)
 249 @deffnx {C Function} scm_r6rs_bytevector_u64_native_ref (bv, index)
 250 @deffnx {C Function} scm_r6rs_bytevector_s64_native_ref (bv, index)
 251 Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
 252 16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
 253 host's native endianness.
 254 @end deffn
 255
 256 @deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
 257 @deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
 258 @deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
 259 @deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
 260 @deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
 261 @deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
 262 @deffnx {C Function} scm_r6rs_bytevector_u16_native_set_x (bv, index, value)
 263 @deffnx {C Function} scm_r6rs_bytevector_s16_native_set_x (bv, index, value)
 264 @deffnx {C Function} scm_r6rs_bytevector_u32_native_set_x (bv, index, value)
 265 @deffnx {C Function} scm_r6rs_bytevector_s32_native_set_x (bv, index, value)
 266 @deffnx {C Function} scm_r6rs_bytevector_u64_native_set_x (bv, index, value)
 267 @deffnx {C Function} scm_r6rs_bytevector_s64_native_set_x (bv, index, value)
 268 Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
 269 8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
 270 host's native endianness.
 271 @end deffn
 272
 273
 274 @node Bytevectors and Integer Lists
 275 @subsection Converting Bytevectors to/from Integer Lists
 276
 277 Bytevector contents can readily be converted to/from lists of signed or
 278 unsigned integers:
 279
 280 @lisp
 281 (bytevector->sint-list (u8-list->bytevector (make-list 4 255))
 282                        (endianness little) 2)
 283 @result{} (-1 -1)
 284 @end lisp
 285
 286 @deffn {Scheme Procedure} bytevector->u8-list bv
 287 @deffnx {C Function} scm_r6rs_bytevector_to_u8_list (bv)
 288 Return a newly allocated list of unsigned 8-bit integers from the
 289 contents of @var{bv}.
 290 @end deffn
 291
 292 @deffn {Scheme Procedure} u8-list->bytevector lst
 293 @deffnx {C Function} scm_r6rs_u8_list_to_bytevector (lst)
 294 Return a newly allocated bytevector consisting of the unsigned 8-bit
 295 integers listed in @var{lst}.
 296 @end deffn
 297
 298 @deffn {Scheme Procedure} bytevector->uint-list bv endianness size
 299 @deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
 300 @deffnx {C Function} scm_r6rs_bytevector_to_uint_list (bv, endianness, size)
 301 @deffnx {C Function} scm_r6rs_bytevector_to_sint_list (bv, endianness, size)
 302 Return a list of unsigned (resp. signed) integers of @var{size} bytes
 303 representing the contents of @var{bv}, decoded according to
 304 @var{endianness}.
 305 @end deffn
 306
 307
 308 @node Bytevectors as Floats
 309 @subsection Interpreting Bytevector Contents as Floating Point Numbers
 310
 311 @cindex IEEE-754 floating point numbers
 312
 313 Bytevector contents can also be accessed as IEEE-754 single- or
 314 double-precision floating point numbers (respectively 32 and 64-bit
 315 long) using the procedures described here.
 316
 317 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
 318 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
 319 @deffnx {C Function} scm_r6rs_bytevector_ieee_single_ref (bv, index, endianness)
 320 @deffnx {C Function} scm_r6rs_bytevector_ieee_double_ref (bv, index, endianness)
 321 Return the IEEE-754 single-precision floating point number from @var{bv}
 322 at @var{index} according to @var{endianness}.
 323 @end deffn
 324
 325 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
 326 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
 327 @deffnx scm_r6rs_bytevector_ieee_single_set_x (bv, index, value, endianness)
 328 @deffnx scm_r6rs_bytevector_ieee_double_set_x (bv, index, value, endianness)
 329 Store real number @var{value} in @var{bv} at @var{index} according to
 330 @var{endianness}.
 331 @end deffn
 332
 333 Specialized procedures are also available:
 334
 335 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
 336 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
 337 @deffnx {C Function} scm_r6rs_bytevector_ieee_single_native_ref (bv, index)
 338 @deffnx {C Function} scm_r6rs_bytevector_ieee_double_native_ref (bv, index)
 339 Return the IEEE-754 single-precision floating point number from @var{bv}
 340 at @var{index} according to the host's native endianness.
 341 @end deffn
 342
 343 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
 344 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
 345 @deffnx scm_r6rs_bytevector_ieee_single_native_set_x (bv, index, value)
 346 @deffnx scm_r6rs_bytevector_ieee_double_native_set_x (bv, index, value)
 347 Store real number @var{value} in @var{bv} at @var{index} according to
 348 the host's native endianness.
 349 @end deffn
 350
 351
 352 @node Bytevectors as Strings
 353 @subsection Interpreting Bytevector Contents as Unicode Strings
 354
 355 Bytevector contents can also be interpreted as Unicode strings encoded
 356 in one of the most commonly available encoding formats@footnote{Guile
 357 1.8 does @emph{not} support Unicode strings.  Therefore, the procedures
 358 described here assume that Guile strings are internally encoded
 359 according to the current locale.  For instance, if @code{$LC_CTYPE} is
 360 @code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
 361 assume that Guile strings are Latin-1-encoded.}.
 362
 363 @lisp
 364 (utf8->string (u8-list->bytevector '(99 97 102 101)))
 365 @result{} "cafe"
 366
 367 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
 368 @result{} #vu8(99 97 102 195 169)
 369 @end lisp
 370
 371 @deffn {Scheme Procedure} string->utf8 str
 372 @deffnx {Scheme Procedure} string->utf16 str
 373 @deffnx {Scheme Procedure} string->utf32 str
 374 @deffnx {C Function} scm_r6rs_string_to_utf8 (str)
 375 @deffnx {C Function} scm_r6rs_string_to_utf16 (str)
 376 @deffnx {C Function} scm_r6rs_string_to_utf32 (str)
 377 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
 378 UTF-32 (aka. UCS-4) encoding of @var{str}.
 379 @end deffn
 380
 381 @deffn {Scheme Procedure} utf8->string utf
 382 @deffnx {Scheme Procedure} utf16->string utf
 383 @deffnx {Scheme Procedure} utf32->string utf
 384 @deffnx {C Function} scm_r6rs_utf8_to_string (utf)
 385 @deffnx {C Function} scm_r6rs_utf16_to_string (utf)
 386 @deffnx {C Function} scm_r6rs_utf32_to_string (utf)
 387 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
 388 or UTF-32-decoded contents of bytevector @var{utf}.
 389 @end deffn
 390
 391
 392 @c *********************************************************************
 393 @node R6RS I/O Ports
 394 @section I/O Ports
 395
 396 The I/O port API of the R6RS is provided by the @code{(rnrs io ports)}
 397 module.  In many areas it complements or refines Guile's own historical
 398 port API (@pxref{Input and Output,,, guile, The GNU Guile Reference
 399 Manual}).
 400
 401 @c FIXME: Update description when implemented.
 402 @emph{Note}: The implementation of this R6RS API is currently far from
 403 complete, notably due to the lack of support for Unicode I/O and strings
 404 in Guile 1.8.
 405
 406 @menu
 407 * R6RS End-of-File::            The end-of-file object.
 408 * R6RS Port Manipulation::      Manipulating R6RS ports.
 409 * R6RS Binary Input::           Binary input.
 410 * R6RS Binary Output::          Binary output.
 411 @end menu
 412
 413 @node R6RS End-of-File
 414 @subsection The End-of-File Object
 415
 416 @cindex EOF
 417 @cindex end-of-file
 418
 419 R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
 420 ports)} module:
 421
 422 @deffn {Scheme Procedure} eof-object? obj
 423 @deffnx {C Function} scm_eof_object_p (obj)
 424 Return true if @var{obj} is the end-of-file (EOF) object.
 425 @end deffn
 426
 427 In addition, the following procedure is provided:
 428
 429 @deffn {Scheme Procedure} eof-object
 430 @deffnx {C Function} scm_r6rs_eof_object ()
 431 Return the end-of-file (EOF) object.
 432
 433 @lisp
 434 (eof-object? (eof-object))
 435 @result{} #t
 436 @end lisp
 437 @end deffn
 438
 439
 440 @node R6RS Port Manipulation
 441 @subsection Port Manipulation
 442
 443 The procedures listed below operate on any kind of R6RS I/O port.
 444
 445 @deffn {Scheme Procedure} port-position port
 446 If @var{port} supports it (see below), return the offset (an integer)
 447 indicating where the next octet will be read from/written to in
 448 @var{port}.  If @var{port} does not support this operation, an error
 449 condition is raised.
 450
 451 This is similar to Guile's @code{seek} procedure with the
 452 @code{SEEK_CUR} argument (@pxref{Random Access,,, guile, The GNU Guile
 453 Reference Manual}).
 454 @end deffn
 455
 456 @deffn {Scheme Procedure} port-has-port-position? port
 457 Return @code{#t} is @var{port} supports @code{port-position}.
 458 @end deffn
 459
 460 @deffn {Scheme Procedure} set-port-position! port offset
 461 If @var{port} supports it (see below), set the position where the next
 462 octet will be read from/written to @var{port} to @var{offset} (an
 463 integer).  If @var{port} does not support this operation, an error
 464 condition is raised.
 465
 466 This is similar to Guile's @code{seek} procedure with the
 467 @code{SEEK_SET} argument (@pxref{Random Access,,, guile, The GNU Guile
 468 Reference Manual}).
 469 @end deffn
 470
 471 @deffn {Scheme Procedure} port-has-set-port-position!? port
 472 Return @code{#t} is @var{port} supports @code{set-port-position!}.
 473 @end deffn
 474
 475 @deffn {Scheme Procedure} call-with-port port proc
 476 Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
 477 of @var{proc}.  Return the return values of @var{proc}.
 478 @end deffn
 479
 480
 481 @node R6RS Binary Input
 482 @subsection Binary Input
 483
 484 @cindex binary input
 485
 486 R6RS binary input ports can be created with the procedures described
 487 below.
 488
 489 @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
 490 @deffnx {C Function} scm_r6rs_open_bytevector_input_port (bv, transcoder)
 491 Return an input port whose contents are drawn from bytevector @var{bv}
 492 (@pxref{Bytevectors}).
 493
 494 @c FIXME: Update description when implemented.
 495 The @var{transcoder} argument is currently not supported.
 496 @end deffn
 497
 498 @cindex custom binary input ports
 499
 500 @deffn {Scheme Procedure} make-custom-binary-input-port id read! [get-position [set-position! [close]]]
 501 @deffnx {C Function} scm_r6rs_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
 502 Return a new custom binary input port@footnote{This is similar in spirit
 503 to Guile's @dfn{soft ports} (@pxref{Soft Ports,,, guile, The GNU Guile
 504 Reference Manual}).} named @var{id} (a string) whose input is drained by
 505 invoking @var{read!} and passing it a bytevector, an index where bytes
 506 should be written, and the number of bytes to read.  The @code{read!}
 507 procedure must return an integer indicating the number of bytes read, or
 508 @code{0} to indicate the end-of-file.
 509
 510 Optionally, @var{get-position}, a thunk, will be called when
 511 @var{port-position} is invoked on the custom binary port and should
 512 return an integer indicating the position within the underlying data
 513 stream; if @var{get-position} was not supplied, the returned port does
 514 not support @var{port-position}.
 515
 516 Likewise, if @var{set-position!} is given, it should be a one-argument
 517 procedure.  When @var{set-port-position!} is invoked on the custom
 518 binary input port, @var{set-position!} is passed an integer indicating
 519 the position of the next byte is to read.
 520
 521 Finally, if @var{close} is supplied, it must be a thunk.  It is invoked
 522 when the custom binary input port is closed.
 523
 524 Using a custom binary input port, the @code{open-bytevector-input-port}
 525 could be implemented as follows:
 526
 527 @lisp
 528 (define (open-bytevector-input-port source)
 529   (define position 0)
 530   (define length (bytevector-length source))
 531
 532   (define (read! bv start count)
 533     (let ((count (min count (- length position))))
 534       (bytevector-copy! source position
 535                         bv start count)
 536       (set! position (+ position count))
 537       count))
 538
 539   (define (get-position) position)
 540
 541   (define (set-position! new-position)
 542     (set! position new-position))
 543
 544   (make-custom-binary-input-port "the port" read!
 545                                   get-position
 546                                   set-position!))
 547
 548 (read (open-bytevector-input-port (string->utf8 "hello")))
 549 @result{} hello
 550 @end lisp
 551 @end deffn
 552
 553 @cindex binary input
 554 Binary input is achieved using the procedures below:
 555
 556 @deffn {Scheme Procedure} get-u8 port
 557 @deffnx {C Function} scm_r6rs_get_u8 (port)
 558 Return an octet read from @var{port}, a binary input port, blocking as
 559 necessary, or the end-of-file object.
 560 @end deffn
 561
 562 @deffn {Scheme Procedure} lookahead-u8 port
 563 @deffnx {C Function} scm_r6rs_lookahead_u8 (port)
 564 Like @code{get-u8} but does not update @var{port}'s position to point
 565 past the octet.
 566 @end deffn
 567
 568 @deffn {Scheme Procedure} get-bytevector-n port count
 569 @deffnx {C Function} scm_r6rs_get_bytevector_n (port, count)
 570 Read @var{count} octets from @var{port}, blocking as necessary and
 571 return a bytevector containing the octets read.  If fewer bytes are
 572 available, a bytevector smaller than @var{count} is returned.
 573 @end deffn
 574
 575 @deffn {Scheme Procedure} get-bytevector-n! port bv start count
 576 @deffnx {C Function} scm_r6rs_get_bytevector_n_x (port, bv, start, count)
 577 Read @var{count} bytes from @var{port} and store them in @var{bv}
 578 starting at index @var{start}.  Return either the number of bytes
 579 actually read or the end-of-file object.
 580 @end deffn
 581
 582 @deffn {Scheme Procedure} get-bytevector-some port
 583 @deffnx {C Function} scm_r6rs_get_bytevector_some (port)
 584 Read from @var{port}, blocking as necessary, until data are available or
 585 and end-of-file is reached.  Return either a new bytevector containing
 586 the data read or the end-of-file object.
 587 @end deffn
 588
 589 @deffn {Scheme Procedure} get-bytevector-all port
 590 @deffnx {C Function} scm_r6rs_get_bytevector_all (port)
 591 Read from @var{port}, blocking as necessary, until the end-of-file is
 592 reached.  Return either a new bytevector containing the data read or the
 593 end-of-file object (if no data were available).
 594 @end deffn
 595
 596 @node R6RS Binary Output
 597 @subsection Binary Output
 598
 599 Binary output ports can be created with the procedures below.
 600
 601 @deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
 602 @deffnx {C Function} scm_r6rs_open_bytevector_output_port (transcoder)
 603 Return two values: a binary output port and a procedure.  The latter
 604 should be called with zero arguments to obtain a bytevector containing
 605 the data accumulated by the port, as illustrated below.
 606
 607 @lisp
 608 (call-with-values
 609   (lambda ()
 610     (open-bytevector-output-port))
 611   (lambda (port get-bytevector)
 612     (display "hello" port)
 613     (get-bytevector)))
 614
 615 @result{} #vu8(104 101 108 108 111)
 616 @end lisp
 617
 618 @c FIXME: Update description when implemented.
 619 The @var{transcoder} argument is currently not supported.
 620 @end deffn
 621
 622 @cindex binary output
 623 Writing to a binary output port can be done using the following
 624 procedures:
 625
 626 @deffn {Scheme Procedure} put-u8 port octet
 627 @deffnx {C Function} scm_r6rs_put_u8 (port, octet)
 628 Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
 629 binary output port.
 630 @end deffn
 631
 632 @deffn {Scheme Procedure} put-bytevector port bv [start [count]]
 633 @deffnx {C Function} scm_r6rs_put_bytevector (port, bv, start, count)
 634 Write the contents of @var{bv} to @var{port}, optionally starting at
 635 index @var{start} and limiting to @var{count} octets.
 636 @end deffn
 637
 638
 639 @c LocalWords:  Bytevectors bytevector bytevectors endianness  endian accessors
 640 @c LocalWords:  endiannesses
 641
 642 @c Local Variables:
 643 @c ispell-local-dictionary: "american"
 644 @c End:
 645