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 @deffn {Scheme Procedure} uint-list->bytevector lst endianness size
 308 @deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
 309 @deffnx {C Function} scm_r6rs_uint_list_to_bytevector (lst, endianness, size)
 310 @deffnx {C Function} scm_r6rs_sint_list_to_bytevector (lst, endianness, size)
 311 Return a new bytevector containing the unsigned (resp. signed) integers
 312 listed in @var{lst} and encoded on @var{size} bytes according to
 313 @var{endianness}.
 314 @end deffn
 315
 316 @node Bytevectors as Floats
 317 @subsection Interpreting Bytevector Contents as Floating Point Numbers
 318
 319 @cindex IEEE-754 floating point numbers
 320
 321 Bytevector contents can also be accessed as IEEE-754 single- or
 322 double-precision floating point numbers (respectively 32 and 64-bit
 323 long) using the procedures described here.
 324
 325 @deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
 326 @deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
 327 @deffnx {C Function} scm_r6rs_bytevector_ieee_single_ref (bv, index, endianness)
 328 @deffnx {C Function} scm_r6rs_bytevector_ieee_double_ref (bv, index, endianness)
 329 Return the IEEE-754 single-precision floating point number from @var{bv}
 330 at @var{index} according to @var{endianness}.
 331 @end deffn
 332
 333 @deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
 334 @deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
 335 @deffnx scm_r6rs_bytevector_ieee_single_set_x (bv, index, value, endianness)
 336 @deffnx scm_r6rs_bytevector_ieee_double_set_x (bv, index, value, endianness)
 337 Store real number @var{value} in @var{bv} at @var{index} according to
 338 @var{endianness}.
 339 @end deffn
 340
 341 Specialized procedures are also available:
 342
 343 @deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
 344 @deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
 345 @deffnx {C Function} scm_r6rs_bytevector_ieee_single_native_ref (bv, index)
 346 @deffnx {C Function} scm_r6rs_bytevector_ieee_double_native_ref (bv, index)
 347 Return the IEEE-754 single-precision floating point number from @var{bv}
 348 at @var{index} according to the host's native endianness.
 349 @end deffn
 350
 351 @deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
 352 @deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
 353 @deffnx scm_r6rs_bytevector_ieee_single_native_set_x (bv, index, value)
 354 @deffnx scm_r6rs_bytevector_ieee_double_native_set_x (bv, index, value)
 355 Store real number @var{value} in @var{bv} at @var{index} according to
 356 the host's native endianness.
 357 @end deffn
 358
 359
 360 @node Bytevectors as Strings
 361 @subsection Interpreting Bytevector Contents as Unicode Strings
 362
 363 Bytevector contents can also be interpreted as Unicode strings encoded
 364 in one of the most commonly available encoding formats@footnote{Guile
 365 1.8 does @emph{not} support Unicode strings.  Therefore, the procedures
 366 described here assume that Guile strings are internally encoded
 367 according to the current locale.  For instance, if @code{$LC_CTYPE} is
 368 @code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
 369 assume that Guile strings are Latin-1-encoded.}.
 370
 371 @lisp
 372 (utf8->string (u8-list->bytevector '(99 97 102 101)))
 373 @result{} "cafe"
 374
 375 (string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
 376 @result{} #vu8(99 97 102 195 169)
 377 @end lisp
 378
 379 @deffn {Scheme Procedure} string->utf8 str
 380 @deffnx {Scheme Procedure} string->utf16 str
 381 @deffnx {Scheme Procedure} string->utf32 str
 382 @deffnx {C Function} scm_r6rs_string_to_utf8 (str)
 383 @deffnx {C Function} scm_r6rs_string_to_utf16 (str)
 384 @deffnx {C Function} scm_r6rs_string_to_utf32 (str)
 385 Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
 386 UTF-32 (aka. UCS-4) encoding of @var{str}.
 387 @end deffn
 388
 389 @deffn {Scheme Procedure} utf8->string utf
 390 @deffnx {Scheme Procedure} utf16->string utf
 391 @deffnx {Scheme Procedure} utf32->string utf
 392 @deffnx {C Function} scm_r6rs_utf8_to_string (utf)
 393 @deffnx {C Function} scm_r6rs_utf16_to_string (utf)
 394 @deffnx {C Function} scm_r6rs_utf32_to_string (utf)
 395 Return a newly allocated string that contains from the UTF-8-, UTF-16-,
 396 or UTF-32-decoded contents of bytevector @var{utf}.
 397 @end deffn
 398
 399
 400 @c *********************************************************************
 401 @node R6RS I/O Ports
 402 @section I/O Ports
 403
 404 The I/O port API of the R6RS is provided by the @code{(rnrs io ports)}
 405 module.  In many areas it complements or refines Guile's own historical
 406 port API (@pxref{Input and Output,,, guile, The GNU Guile Reference
 407 Manual}).
 408
 409 @c FIXME: Update description when implemented.
 410 @emph{Note}: The implementation of this R6RS API is currently far from
 411 complete, notably due to the lack of support for Unicode I/O and strings
 412 in Guile 1.8.
 413
 414 @menu
 415 * R6RS End-of-File::            The end-of-file object.
 416 * R6RS Port Manipulation::      Manipulating R6RS ports.
 417 * R6RS Binary Input::           Binary input.
 418 * R6RS Binary Output::          Binary output.
 419 @end menu
 420
 421 @node R6RS End-of-File
 422 @subsection The End-of-File Object
 423
 424 @cindex EOF
 425 @cindex end-of-file
 426
 427 R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
 428 ports)} module:
 429
 430 @deffn {Scheme Procedure} eof-object? obj
 431 @deffnx {C Function} scm_eof_object_p (obj)
 432 Return true if @var{obj} is the end-of-file (EOF) object.
 433 @end deffn
 434
 435 In addition, the following procedure is provided:
 436
 437 @deffn {Scheme Procedure} eof-object
 438 @deffnx {C Function} scm_r6rs_eof_object ()
 439 Return the end-of-file (EOF) object.
 440
 441 @lisp
 442 (eof-object? (eof-object))
 443 @result{} #t
 444 @end lisp
 445 @end deffn
 446
 447
 448 @node R6RS Port Manipulation
 449 @subsection Port Manipulation
 450
 451 The procedures listed below operate on any kind of R6RS I/O port.
 452
 453 @deffn {Scheme Procedure} port-position port
 454 If @var{port} supports it (see below), return the offset (an integer)
 455 indicating where the next octet will be read from/written to in
 456 @var{port}.  If @var{port} does not support this operation, an error
 457 condition is raised.
 458
 459 This is similar to Guile's @code{seek} procedure with the
 460 @code{SEEK_CUR} argument (@pxref{Random Access,,, guile, The GNU Guile
 461 Reference Manual}).
 462 @end deffn
 463
 464 @deffn {Scheme Procedure} port-has-port-position? port
 465 Return @code{#t} is @var{port} supports @code{port-position}.
 466 @end deffn
 467
 468 @deffn {Scheme Procedure} set-port-position! port offset
 469 If @var{port} supports it (see below), set the position where the next
 470 octet will be read from/written to @var{port} to @var{offset} (an
 471 integer).  If @var{port} does not support this operation, an error
 472 condition is raised.
 473
 474 This is similar to Guile's @code{seek} procedure with the
 475 @code{SEEK_SET} argument (@pxref{Random Access,,, guile, The GNU Guile
 476 Reference Manual}).
 477 @end deffn
 478
 479 @deffn {Scheme Procedure} port-has-set-port-position!? port
 480 Return @code{#t} is @var{port} supports @code{set-port-position!}.
 481 @end deffn
 482
 483 @deffn {Scheme Procedure} call-with-port port proc
 484 Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
 485 of @var{proc}.  Return the return values of @var{proc}.
 486 @end deffn
 487
 488
 489 @node R6RS Binary Input
 490 @subsection Binary Input
 491
 492 @cindex binary input
 493
 494 R6RS binary input ports can be created with the procedures described
 495 below.
 496
 497 @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
 498 @deffnx {C Function} scm_r6rs_open_bytevector_input_port (bv, transcoder)
 499 Return an input port whose contents are drawn from bytevector @var{bv}
 500 (@pxref{Bytevectors}).
 501
 502 @c FIXME: Update description when implemented.
 503 The @var{transcoder} argument is currently not supported.
 504 @end deffn
 505
 506 @cindex custom binary input ports
 507
 508 @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
 509 @deffnx {C Function} scm_r6rs_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
 510 Return a new custom binary input port@footnote{This is similar in spirit
 511 to Guile's @dfn{soft ports} (@pxref{Soft Ports,,, guile, The GNU Guile
 512 Reference Manual}).} named @var{id} (a string) whose input is drained by
 513 invoking @var{read!} and passing it a bytevector, an index where bytes
 514 should be written, and the number of bytes to read.  The @code{read!}
 515 procedure must return an integer indicating the number of bytes read, or
 516 @code{0} to indicate the end-of-file.
 517
 518 Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
 519 that will be called when @var{port-position} is invoked on the custom
 520 binary port and should return an integer indicating the position within
 521 the underlying data stream; if @var{get-position} was not supplied, the
 522 returned port does not support @var{port-position}.
 523
 524 Likewise, if @var{set-position!} is not @code{#f}, it should be a
 525 one-argument procedure.  When @var{set-port-position!} is invoked on the
 526 custom binary input port, @var{set-position!} is passed an integer
 527 indicating the position of the next byte is to read.
 528
 529 Finally, if @var{close} is not @code{#f}, it must be a thunk.  It is
 530 invoked when the custom binary input port is closed.
 531
 532 Using a custom binary input port, the @code{open-bytevector-input-port}
 533 could be implemented as follows:
 534
 535 @lisp
 536 (define (open-bytevector-input-port source)
 537   (define position 0)
 538   (define length (bytevector-length source))
 539
 540   (define (read! bv start count)
 541     (let ((count (min count (- length position))))
 542       (bytevector-copy! source position
 543                         bv start count)
 544       (set! position (+ position count))
 545       count))
 546
 547   (define (get-position) position)
 548
 549   (define (set-position! new-position)
 550     (set! position new-position))
 551
 552   (make-custom-binary-input-port "the port" read!
 553                                   get-position
 554                                   set-position!))
 555
 556 (read (open-bytevector-input-port (string->utf8 "hello")))
 557 @result{} hello
 558 @end lisp
 559 @end deffn
 560
 561 @cindex binary input
 562 Binary input is achieved using the procedures below:
 563
 564 @deffn {Scheme Procedure} get-u8 port
 565 @deffnx {C Function} scm_r6rs_get_u8 (port)
 566 Return an octet read from @var{port}, a binary input port, blocking as
 567 necessary, or the end-of-file object.
 568 @end deffn
 569
 570 @deffn {Scheme Procedure} lookahead-u8 port
 571 @deffnx {C Function} scm_r6rs_lookahead_u8 (port)
 572 Like @code{get-u8} but does not update @var{port}'s position to point
 573 past the octet.
 574 @end deffn
 575
 576 @deffn {Scheme Procedure} get-bytevector-n port count
 577 @deffnx {C Function} scm_r6rs_get_bytevector_n (port, count)
 578 Read @var{count} octets from @var{port}, blocking as necessary and
 579 return a bytevector containing the octets read.  If fewer bytes are
 580 available, a bytevector smaller than @var{count} is returned.
 581 @end deffn
 582
 583 @deffn {Scheme Procedure} get-bytevector-n! port bv start count
 584 @deffnx {C Function} scm_r6rs_get_bytevector_n_x (port, bv, start, count)
 585 Read @var{count} bytes from @var{port} and store them in @var{bv}
 586 starting at index @var{start}.  Return either the number of bytes
 587 actually read or the end-of-file object.
 588 @end deffn
 589
 590 @deffn {Scheme Procedure} get-bytevector-some port
 591 @deffnx {C Function} scm_r6rs_get_bytevector_some (port)
 592 Read from @var{port}, blocking as necessary, until data are available or
 593 and end-of-file is reached.  Return either a new bytevector containing
 594 the data read or the end-of-file object.
 595 @end deffn
 596
 597 @deffn {Scheme Procedure} get-bytevector-all port
 598 @deffnx {C Function} scm_r6rs_get_bytevector_all (port)
 599 Read from @var{port}, blocking as necessary, until the end-of-file is
 600 reached.  Return either a new bytevector containing the data read or the
 601 end-of-file object (if no data were available).
 602 @end deffn
 603
 604 @node R6RS Binary Output
 605 @subsection Binary Output
 606
 607 Binary output ports can be created with the procedures below.
 608
 609 @deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
 610 @deffnx {C Function} scm_r6rs_open_bytevector_output_port (transcoder)
 611 Return two values: a binary output port and a procedure.  The latter
 612 should be called with zero arguments to obtain a bytevector containing
 613 the data accumulated by the port, as illustrated below.
 614
 615 @lisp
 616 (call-with-values
 617   (lambda ()
 618     (open-bytevector-output-port))
 619   (lambda (port get-bytevector)
 620     (display "hello" port)
 621     (get-bytevector)))
 622
 623 @result{} #vu8(104 101 108 108 111)
 624 @end lisp
 625
 626 @c FIXME: Update description when implemented.
 627 The @var{transcoder} argument is currently not supported.
 628 @end deffn
 629
 630 @cindex binary output
 631 Writing to a binary output port can be done using the following
 632 procedures:
 633
 634 @deffn {Scheme Procedure} put-u8 port octet
 635 @deffnx {C Function} scm_r6rs_put_u8 (port, octet)
 636 Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
 637 binary output port.
 638 @end deffn
 639
 640 @deffn {Scheme Procedure} put-bytevector port bv [start [count]]
 641 @deffnx {C Function} scm_r6rs_put_bytevector (port, bv, start, count)
 642 Write the contents of @var{bv} to @var{port}, optionally starting at
 643 index @var{start} and limiting to @var{count} octets.
 644 @end deffn
 645
 646
 647 @c LocalWords:  Bytevectors bytevector bytevectors endianness  endian accessors
 648 @c LocalWords:  endiannesses
 649
 650 @c Local Variables:
 651 @c ispell-local-dictionary: "american"
 652 @c End:
 653