[PATCH] R6RS bytevector/port API documentation

[Ludovic Courtès]

Hello,

Attached is the proposed documentation of the R6RS bytevector and port
APIs I just added.  The "Bytevectors" node right is after "Strings" but
we might just as well put it between "Uniform Numeric Vectors" and "Bit
Vectors".  Opinions?

FYI, the printed manual reaches 656 pages.  :-)

Thanks in advance,
Ludo'.

From 2492f5f9287381abf201929ffd6af5731995c88f Mon Sep 17 00:00:00 2001
From: =?utf-8?q?Ludovic=20Court=C3=A8s?= <address@hidden>
Date: Thu, 28 May 2009 23:57:31 +0200
Subject: [PATCH] Import documentation for the R6RS bytevector and port APIs.

* doc/ref/api-data.texi (Bytevectors): New node.

* doc/ref/api-io.texi (R6RS I/O Ports): New node.
---
 doc/ref/api-data.texi |  397 ++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/ref/api-io.texi   |  266 +++++++++++++++++++++++++++++++++-
 2 files changed, 661 insertions(+), 2 deletions(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index b529199..8dbad38 100755
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 
2007, 2008
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 
2007, 2008, 2009
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -45,6 +45,7 @@ For the documentation of such @dfn{compound} data types, see
 * Characters::                  Single characters.
 * Character Sets::              Sets of characters.
 * Strings::                     Sequences of characters.
+* Bytevectors::                 Sequences of bytes.
 * Regular Expressions::         Pattern matching and substitution.
 * Symbols::                     Symbols.
 * Keywords::                    Self-quoting, customizable display keywords.
@@ -3746,6 +3747,400 @@ is larger than @var{max_len}, only @var{max_len} bytes 
have been
 stored and you probably need to try again with a larger buffer.
 @end deftypefn
 
address@hidden Bytevectors
address@hidden Bytevectors
+
address@hidden bytevector
address@hidden R6RS
+
+A @dfn{bytevector} is a raw bit string.  The @code{(rnrs bytevector)}
+module provides the programming interface specified by the
address@hidden://www.r6rs.org/, Revised Report^6 on the Algorithmic Language
+Scheme (R6RS)}.  It contains procedures to manipulate bytevectors and
+interpret their contents in a number of ways: bytevector contents can be
+accessed as signed or unsigned integer of various sizes and endianness,
+as IEEE-754 floating point numbers, or as strings.  It is a useful tool
+to encode and decode binary data.
+
+The R6RS (Section 4.3.4) specifies an external representation for
+bytevectors, whereby the octets (integers in the range 0--255) contained
+in the bytevector are represented as a list prefixed by @code{#vu8}:
+
address@hidden
+#vu8(1 53 204)
address@hidden lisp
+
+denotes a 3-byte bytevector containing the octets 1, 53, and 204.  Like
+string literals, booleans, etc., bytevectors are ``self-quoting'', i.e.,
+they do not need to be quoted:
+
address@hidden
+#vu8(1 53 204)
address@hidden #vu8(1 53 204)
address@hidden lisp
+
+Bytevectors can be used with the binary input/output primitives of the
+R6RS (@pxref{R6RS I/O Ports}).
+
address@hidden
+* Bytevector Endianness::       Dealing with byte order.
+* Bytevector Manipulation::     Creating, copying, manipulating bytevectors.
+* Bytevectors as Integers::     Interpreting bytes as integers.
+* Bytevectors and Integer Lists::  Converting to/from an integer list.
+* Bytevectors as Floats::       Interpreting bytes as real numbers.
+* Bytevectors as Strings::      Interpreting bytes as Unicode strings.
address@hidden menu
+
address@hidden Bytevector Endianness
address@hidden Endianness
+
address@hidden endianness
address@hidden byte order
address@hidden word order
+
+Some of the following procedures take an @var{endianness} parameter.
+The @dfn{endianness} is defined is defined as the order of bytes in
+multi-byte numbers: numbers encoded in @dfn{big endian} have their most
+significant bytes written first, whereas numbers encoded in @dfn{little
+endian} have their least significant bytes address@hidden and little
+endian are the most common ``endiannesses'' but others exist.  For
+instance, the GNU MP library allows @dfn{word order} to be specified
+independently of @dfn{byte order} (@pxref{Integer Import and Export,,,
+gmp, The GNU Multiple Precision Arithmetic Library Manual}).}  Little
+endian is the native endianness of the IA32 architecture and its
+derivatives, while big endian is native to SPARC and PowerPC, among
+others.  The @code{native-endianness} procedure returns the native
+endianness of the machine it runs on.
+
address@hidden {Scheme Procedure} native-endianness
address@hidden {C Function} scm_native_endianness ()
+Return a value denoting the native endianness of the host machine.
address@hidden deffn
+
address@hidden {Scheme Macro} endianness symbol
+Return an object denoting the endianness specified by @var{symbol}.  If
address@hidden is neither @code{big} nor @code{little} then a compile-time
+error is raised.
address@hidden deffn
+
address@hidden {C Variable} scm_endianness_big
address@hidden {C Variable} scm_endianness_little
+The objects denoting big (resp. little) endianness.
address@hidden defvr
+
+
address@hidden Bytevector Manipulation
address@hidden Manipulating Bytevectors
+
+Bytevectors can be created, copied, and analyzed with the following
+procedures.
+
address@hidden {Scheme Procedure} make-bytevector len [fill]
address@hidden {C Function} scm_make_bytevector (len, fill)
address@hidden {C Function} scm_c_make_bytevector (unsigned len)
+Return a new bytevector of @var{len} bytes.  Optionally, if @var{fill}
+is given, fill it with @var{fill}; @var{fill} must be an 8-bit signed
+integer, i.e., in the range [-128,127].
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector? obj
address@hidden {C Function} scm_bytevector_p (obj)
+Return true if @var{obj} is a bytevector.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-length bv
address@hidden {C Function} scm_bytevector_length (bv)
+Return the length in bytes of bytevector @var{bv}.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector=? bv1 bv2
address@hidden {C Function} scm_bytevector_eq_p (bv1, bv2)
+Return is @var{bv1} equals to @var{bv2}---i.e., if they have the same
+length and contents.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-fill! bv fill
address@hidden {C Function} scm_bytevector_fill_x (bv, fill)
+Fill bytevector @var{bv} with @var{fill}, a byte.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-copy! source source-start target 
target-start len
address@hidden {C Function} scm_bytevector_copy_x (source, source_start, 
target, target_start, len)
+Copy @var{len} bytes from @var{source} into @var{target}, starting
+reading from @var{source-start} (a positive index within @var{source})
+and start writing at @var{target-start}.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-copy bv
address@hidden {C Function} scm_bytevector_copy (bv)
+Return a newly allocated copy of @var{bv}.
address@hidden deffn
+
+Low-level C macros are available.  They do not perform any
+type-checking; as such they should be used with care.
+
address@hidden {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
+Return the length in bytes of bytevector @var{bv}.
address@hidden deftypefn
+
address@hidden {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
+Return a pointer to the contents of bytevector @var{bv}.
address@hidden deftypefn
+
+
address@hidden Bytevectors as Integers
address@hidden Interpreting Bytevector Contents as Integers
+
+The contents of a bytevector can be interpreted as a sequence of
+integers of any given size, sign, and endianness.
+
address@hidden
+(let ((bv (make-bytevector 4)))
+  (bytevector-u8-set! bv 0 #x12)
+  (bytevector-u8-set! bv 1 #x34)
+  (bytevector-u8-set! bv 2 #x56)
+  (bytevector-u8-set! bv 3 #x78)
+
+  (map (lambda (number)
+         (number->string number 16))
+       (list (bytevector-u8-ref bv 0)
+             (bytevector-u16-ref bv 0 (endianness big))
+             (bytevector-u32-ref bv 0 (endianness little)))))
+
address@hidden ("12" "1234" "78563412")
address@hidden lisp
+
+The most generic procedures to interpret bytevector contents as integers
+are described below.
+
address@hidden {Scheme Procedure} bytevector-uint-ref bv index endianness size
address@hidden {Scheme Procedure} bytevector-sint-ref bv index endianness size
address@hidden {C Function} scm_bytevector_uint_ref (bv, index, endianness, 
size)
address@hidden {C Function} scm_bytevector_sint_ref (bv, index, endianness, 
size)
+Return the @var{size}-byte long unsigned (resp. signed) integer at
+index @var{index} in @var{bv}, decoded according to @var{endianness}.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-uint-set! bv index value 
endianness size
address@hidden {Scheme Procedure} bytevector-sint-set! bv index value 
endianness size
address@hidden {C Function} scm_bytevector_uint_set_x (bv, index, value, 
endianness, size)
address@hidden {C Function} scm_bytevector_sint_set_x (bv, index, value, 
endianness, size)
+Set the @var{size}-byte long unsigned (resp. signed) integer at
address@hidden to @var{value}, encoded according to @var{endianness}.
address@hidden deffn
+
+The following procedures are similar to the ones above, but specialized
+to a given integer size:
+
address@hidden {Scheme Procedure} bytevector-u8-ref bv index
address@hidden {Scheme Procedure} bytevector-s8-ref bv index
address@hidden {Scheme Procedure} bytevector-u16-ref bv index endianness
address@hidden {Scheme Procedure} bytevector-s16-ref bv index endianness
address@hidden {Scheme Procedure} bytevector-u32-ref bv index endianness
address@hidden {Scheme Procedure} bytevector-s32-ref bv index endianness
address@hidden {Scheme Procedure} bytevector-u64-ref bv index endianness
address@hidden {Scheme Procedure} bytevector-s64-ref bv index endianness
address@hidden {C Function} scm_bytevector_u8_ref (bv, index)
address@hidden {C Function} scm_bytevector_s8_ref (bv, index)
address@hidden {C Function} scm_bytevector_u16_ref (bv, index, endianness)
address@hidden {C Function} scm_bytevector_s16_ref (bv, index, endianness)
address@hidden {C Function} scm_bytevector_u32_ref (bv, index, endianness)
address@hidden {C Function} scm_bytevector_s32_ref (bv, index, endianness)
address@hidden {C Function} scm_bytevector_u64_ref (bv, index, endianness)
address@hidden {C Function} scm_bytevector_s64_ref (bv, index, endianness)
+Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
+16, 32 or 64) from @var{bv} at @var{index}, decoded according to
address@hidden
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-u8-set! bv index value
address@hidden {Scheme Procedure} bytevector-s8-set! bv index value
address@hidden {Scheme Procedure} bytevector-u16-set! bv index value endianness
address@hidden {Scheme Procedure} bytevector-s16-set! bv index value endianness
address@hidden {Scheme Procedure} bytevector-u32-set! bv index value endianness
address@hidden {Scheme Procedure} bytevector-s32-set! bv index value endianness
address@hidden {Scheme Procedure} bytevector-u64-set! bv index value endianness
address@hidden {Scheme Procedure} bytevector-s64-set! bv index value endianness
address@hidden {C Function} scm_bytevector_u8_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_s8_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_u16_set_x (bv, index, value, 
endianness)
address@hidden {C Function} scm_bytevector_s16_set_x (bv, index, value, 
endianness)
address@hidden {C Function} scm_bytevector_u32_set_x (bv, index, value, 
endianness)
address@hidden {C Function} scm_bytevector_s32_set_x (bv, index, value, 
endianness)
address@hidden {C Function} scm_bytevector_u64_set_x (bv, index, value, 
endianness)
address@hidden {C Function} scm_bytevector_s64_set_x (bv, index, value, 
endianness)
+Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
+8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to
address@hidden
address@hidden deffn
+
+Finally, a variant specialized for the host's endianness is available
+for each of these functions (with the exception of the @code{u8}
+accessors, for obvious reasons):
+
address@hidden {Scheme Procedure} bytevector-u16-native-ref bv index
address@hidden {Scheme Procedure} bytevector-s16-native-ref bv index
address@hidden {Scheme Procedure} bytevector-u32-native-ref bv index
address@hidden {Scheme Procedure} bytevector-s32-native-ref bv index
address@hidden {Scheme Procedure} bytevector-u64-native-ref bv index
address@hidden {Scheme Procedure} bytevector-s64-native-ref bv index
address@hidden {C Function} scm_bytevector_u16_native_ref (bv, index)
address@hidden {C Function} scm_bytevector_s16_native_ref (bv, index)
address@hidden {C Function} scm_bytevector_u32_native_ref (bv, index)
address@hidden {C Function} scm_bytevector_s32_native_ref (bv, index)
address@hidden {C Function} scm_bytevector_u64_native_ref (bv, index)
address@hidden {C Function} scm_bytevector_s64_native_ref (bv, index)
+Return the unsigned @var{n}-bit (signed) integer (where @var{n} is 8,
+16, 32 or 64) from @var{bv} at @var{index}, decoded according to the
+host's native endianness.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-u16-native-set! bv index value
address@hidden {Scheme Procedure} bytevector-s16-native-set! bv index value
address@hidden {Scheme Procedure} bytevector-u32-native-set! bv index value
address@hidden {Scheme Procedure} bytevector-s32-native-set! bv index value
address@hidden {Scheme Procedure} bytevector-u64-native-set! bv index value
address@hidden {Scheme Procedure} bytevector-s64-native-set! bv index value
address@hidden {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
address@hidden {C Function} scm_bytevector_s64_native_set_x (bv, index, value)
+Store @var{value} as an @var{n}-bit (signed) integer (where @var{n} is
+8, 16, 32 or 64) in @var{bv} at @var{index}, encoded according to the
+host's native endianness.
address@hidden deffn
+
+
address@hidden Bytevectors and Integer Lists
address@hidden Converting Bytevectors to/from Integer Lists
+
+Bytevector contents can readily be converted to/from lists of signed or
+unsigned integers:
+
address@hidden
+(bytevector->sint-list (u8-list->bytevector (make-list 4 255))
+                       (endianness little) 2)
address@hidden (-1 -1)
address@hidden lisp
+
address@hidden {Scheme Procedure} bytevector->u8-list bv
address@hidden {C Function} scm_bytevector_to_u8_list (bv)
+Return a newly allocated list of unsigned 8-bit integers from the
+contents of @var{bv}.
address@hidden deffn
+
address@hidden {Scheme Procedure} u8-list->bytevector lst
address@hidden {C Function} scm_u8_list_to_bytevector (lst)
+Return a newly allocated bytevector consisting of the unsigned 8-bit
+integers listed in @var{lst}.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector->uint-list bv endianness size
address@hidden {Scheme Procedure} bytevector->sint-list bv endianness size
address@hidden {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
address@hidden {C Function} scm_bytevector_to_sint_list (bv, endianness, size)
+Return a list of unsigned (resp. signed) integers of @var{size} bytes
+representing the contents of @var{bv}, decoded according to
address@hidden
address@hidden deffn
+
address@hidden {Scheme Procedure} uint-list->bytevector lst endianness size
address@hidden {Scheme Procedure} sint-list->bytevector lst endianness size
address@hidden {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
address@hidden {C Function} scm_sint_list_to_bytevector (lst, endianness, size)
+Return a new bytevector containing the unsigned (resp. signed) integers
+listed in @var{lst} and encoded on @var{size} bytes according to
address@hidden
address@hidden deffn
+
address@hidden Bytevectors as Floats
address@hidden Interpreting Bytevector Contents as Floating Point Numbers
+
address@hidden IEEE-754 floating point numbers
+
+Bytevector contents can also be accessed as IEEE-754 single- or
+double-precision floating point numbers (respectively 32 and 64-bit
+long) using the procedures described here.
+
address@hidden {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
address@hidden {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
address@hidden {C Function} scm_bytevector_ieee_single_ref (bv, index, 
endianness)
address@hidden {C Function} scm_bytevector_ieee_double_ref (bv, index, 
endianness)
+Return the IEEE-754 single-precision floating point number from @var{bv}
+at @var{index} according to @var{endianness}.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-ieee-single-set! bv index value 
endianness
address@hidden {Scheme Procedure} bytevector-ieee-double-set! bv index value 
endianness
address@hidden {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, 
endianness)
address@hidden {C Function} scm_bytevector_ieee_double_set_x (bv, index, value, 
endianness)
+Store real number @var{value} in @var{bv} at @var{index} according to
address@hidden
address@hidden deffn
+
+Specialized procedures are also available:
+
address@hidden {Scheme Procedure} bytevector-ieee-single-native-ref bv index
address@hidden {Scheme Procedure} bytevector-ieee-double-native-ref bv index
address@hidden {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
address@hidden {C Function} scm_bytevector_ieee_double_native_ref (bv, index)
+Return the IEEE-754 single-precision floating point number from @var{bv}
+at @var{index} according to the host's native endianness.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector-ieee-single-native-set! bv index 
value
address@hidden {Scheme Procedure} bytevector-ieee-double-native-set! bv index 
value
address@hidden {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, 
value)
address@hidden {C Function} scm_bytevector_ieee_double_native_set_x (bv, index, 
value)
+Store real number @var{value} in @var{bv} at @var{index} according to
+the host's native endianness.
address@hidden deffn
+
+
address@hidden Bytevectors as Strings
address@hidden Interpreting Bytevector Contents as Unicode Strings
+
address@hidden Unicode string encoding
+
+Bytevector contents can also be interpreted as Unicode strings encoded
+in one of the most commonly available encoding address@hidden
+1.8 does @emph{not} support Unicode strings.  Therefore, the procedures
+described here assume that Guile strings are internally encoded
+according to the current locale.  For instance, if @code{$LC_CTYPE} is
address@hidden, then @code{string->utf-8} @i{et al.} will
+assume that Guile strings are Latin-1-encoded.}.
+
address@hidden
+(utf8->string (u8-list->bytevector '(99 97 102 101)))
address@hidden "cafe"
+
+(string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
address@hidden #vu8(99 97 102 195 169)
address@hidden lisp
+
address@hidden {Scheme Procedure} string->utf8 str
address@hidden {Scheme Procedure} string->utf16 str
address@hidden {Scheme Procedure} string->utf32 str
address@hidden {C Function} scm_string_to_utf8 (str)
address@hidden {C Function} scm_string_to_utf16 (str)
address@hidden {C Function} scm_string_to_utf32 (str)
+Return a newly allocated bytevector that contains the UTF-8, UTF-16, or
+UTF-32 (aka. UCS-4) encoding of @var{str}.
address@hidden deffn
+
address@hidden {Scheme Procedure} utf8->string utf
address@hidden {Scheme Procedure} utf16->string utf
address@hidden {Scheme Procedure} utf32->string utf
address@hidden {C Function} scm_utf8_to_string (utf)
address@hidden {C Function} scm_utf16_to_string (utf)
address@hidden {C Function} scm_utf32_to_string (utf)
+Return a newly allocated string that contains from the UTF-8-, UTF-16-,
+or UTF-32-decoded contents of bytevector @var{utf}.
address@hidden deffn
+
+
 @node Regular Expressions
 @subsection Regular Expressions
 @tpindex Regular expressions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index f69d07e..12c19b7 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 
2009
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -18,6 +18,7 @@
 * Block Reading and Writing::   Reading and writing blocks of text.
 * Default Ports::               Defaults for input, output and errors.
 * Port Types::                  Types of port and how to make them.
+* R6RS I/O Ports::              The R6RS port API.
 * I/O Extensions::              Using and extending ports in C.
 @end menu
 
@@ -1023,6 +1024,269 @@ documentation for @code{open-file} in @ref{File Ports}.
 @end deffn
 
 
address@hidden R6RS I/O Ports
address@hidden R6RS I/O Ports
+
address@hidden R6RS
address@hidden R6RS ports
+
+The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on
+the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
+io ports)} module.  It provides features, such as binary I/O and Unicode
+string I/O, that complement or refine Guile's historical port API
+presented above (@pxref{Input and Output}).
+
address@hidden FIXME: Update description when implemented.
address@hidden: The implementation of this R6RS API is currently far from
+complete, notably due to the lack of support for Unicode I/O and strings.
+
address@hidden
+* R6RS End-of-File::            The end-of-file object.
+* R6RS Port Manipulation::      Manipulating R6RS ports.
+* R6RS Binary Input::           Binary input.
+* R6RS Binary Output::          Binary output.
address@hidden menu
+
address@hidden R6RS End-of-File
address@hidden The End-of-File Object
+
address@hidden EOF
address@hidden end-of-file
+
+R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
+ports)} module:
+
address@hidden {Scheme Procedure} eof-object? obj
address@hidden {C Function} scm_eof_object_p (obj)
+Return true if @var{obj} is the end-of-file (EOF) object.
address@hidden deffn
+
+In addition, the following procedure is provided:
+
address@hidden {Scheme Procedure} eof-object
address@hidden {C Function} scm_eof_object ()
+Return the end-of-file (EOF) object.
+
address@hidden
+(eof-object? (eof-object))
address@hidden #t
address@hidden lisp
address@hidden deffn
+
+
address@hidden R6RS Port Manipulation
address@hidden Port Manipulation
+
+The procedures listed below operate on any kind of R6RS I/O port.
+
address@hidden {Scheme Procedure} port-position port
+If @var{port} supports it (see below), return the offset (an integer)
+indicating where the next octet will be read from/written to in
address@hidden  If @var{port} does not support this operation, an error
+condition is raised.
+
+This is similar to Guile's @code{seek} procedure with the
address@hidden argument (@pxref{Random Access}).
address@hidden deffn
+
address@hidden {Scheme Procedure} port-has-port-position? port
+Return @code{#t} is @var{port} supports @code{port-position}.
address@hidden deffn
+
address@hidden {Scheme Procedure} set-port-position! port offset
+If @var{port} supports it (see below), set the position where the next
+octet will be read from/written to @var{port} to @var{offset} (an
+integer).  If @var{port} does not support this operation, an error
+condition is raised.
+
+This is similar to Guile's @code{seek} procedure with the
address@hidden argument (@pxref{Random Access}).
address@hidden deffn
+
address@hidden {Scheme Procedure} port-has-set-port-position!? port
+Return @code{#t} is @var{port} supports @code{set-port-position!}.
address@hidden deffn
+
address@hidden {Scheme Procedure} call-with-port port proc
+Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
+of @var{proc}.  Return the return values of @var{proc}.
address@hidden deffn
+
+
address@hidden R6RS Binary Input
address@hidden Binary Input
+
address@hidden binary input
+
+R6RS binary input ports can be created with the procedures described
+below.
+
address@hidden {Scheme Procedure} open-bytevector-input-port bv [transcoder]
address@hidden {C Function} scm_open_bytevector_input_port (bv, transcoder)
+Return an input port whose contents are drawn from bytevector @var{bv}
+(@pxref{Bytevectors}).
+
address@hidden FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
address@hidden deffn
+
address@hidden custom binary input ports
+
address@hidden {Scheme Procedure} make-custom-binary-input-port id read! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_input_port (id, read!, 
get-position, set-position!, close)
+Return a new custom binary input address@hidden is similar in spirit
+to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
+string) whose input is drained by invoking @var{read!} and passing it a
+bytevector, an index where bytes should be written, and the number of
+bytes to read.  The @code{read!}  procedure must return an integer
+indicating the number of bytes read, or @code{0} to indicate the
+end-of-file.
+
+Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
+that will be called when @var{port-position} is invoked on the custom
+binary port and should return an integer indicating the position within
+the underlying data stream; if @var{get-position} was not supplied, the
+returned port does not support @var{port-position}.
+
+Likewise, if @var{set-position!} is not @code{#f}, it should be a
+one-argument procedure.  When @var{set-port-position!} is invoked on the
+custom binary input port, @var{set-position!} is passed an integer
+indicating the position of the next byte is to read.
+
+Finally, if @var{close} is not @code{#f}, it must be a thunk.  It is
+invoked when the custom binary input port is closed.
+
+Using a custom binary input port, the @code{open-bytevector-input-port}
+procedure could be implemented as follows:
+
address@hidden
+(define (open-bytevector-input-port source)
+  (define position 0)
+  (define length (bytevector-length source))
+
+  (define (read! bv start count)
+    (let ((count (min count (- length position))))
+      (bytevector-copy! source position
+                        bv start count)
+      (set! position (+ position count))
+      count))
+
+  (define (get-position) position)
+
+  (define (set-position! new-position)
+    (set! position new-position))
+
+  (make-custom-binary-input-port "the port" read!
+                                  get-position
+                                  set-position!))
+
+(read (open-bytevector-input-port (string->utf8 "hello")))
address@hidden hello
address@hidden lisp
address@hidden deffn
+
address@hidden binary input
+Binary input is achieved using the procedures below:
+
address@hidden {Scheme Procedure} get-u8 port
address@hidden {C Function} scm_get_u8 (port)
+Return an octet read from @var{port}, a binary input port, blocking as
+necessary, or the end-of-file object.
address@hidden deffn
+
address@hidden {Scheme Procedure} lookahead-u8 port
address@hidden {C Function} scm_lookahead_u8 (port)
+Like @code{get-u8} but does not update @var{port}'s position to point
+past the octet.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-n port count
address@hidden {C Function} scm_get_bytevector_n (port, count)
+Read @var{count} octets from @var{port}, blocking as necessary and
+return a bytevector containing the octets read.  If fewer bytes are
+available, a bytevector smaller than @var{count} is returned.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-n! port bv start count
address@hidden {C Function} scm_get_bytevector_n_x (port, bv, start, count)
+Read @var{count} bytes from @var{port} and store them in @var{bv}
+starting at index @var{start}.  Return either the number of bytes
+actually read or the end-of-file object.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-some port
address@hidden {C Function} scm_get_bytevector_some (port)
+Read from @var{port}, blocking as necessary, until data are available or
+and end-of-file is reached.  Return either a new bytevector containing
+the data read or the end-of-file object.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-all port
address@hidden {C Function} scm_get_bytevector_all (port)
+Read from @var{port}, blocking as necessary, until the end-of-file is
+reached.  Return either a new bytevector containing the data read or the
+end-of-file object (if no data were available).
address@hidden deffn
+
address@hidden R6RS Binary Output
address@hidden Binary Output
+
+Binary output ports can be created with the procedures below.
+
address@hidden {Scheme Procedure} open-bytevector-output-port [transcoder]
address@hidden {C Function} scm_open_bytevector_output_port (transcoder)
+Return two values: a binary output port and a procedure.  The latter
+should be called with zero arguments to obtain a bytevector containing
+the data accumulated by the port, as illustrated below.
+
address@hidden
+(call-with-values
+  (lambda ()
+    (open-bytevector-output-port))
+  (lambda (port get-bytevector)
+    (display "hello" port)
+    (get-bytevector)))
+
address@hidden #vu8(104 101 108 108 111)
address@hidden lisp
+
address@hidden FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
address@hidden deffn
+
address@hidden custom binary output ports
+
address@hidden {Scheme Procedure} make-custom-binary-output-port id write! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_output_port (id, write!, 
get-position, set-position!, close)
+Return a new custom binary output port named @var{id} (a string) whose
+output is sunk by invoking @var{write!} and passing it a bytevector, an
+index where bytes should be read from this bytevector, and the number of
+bytes to be ``written''.  The @code{write!}  procedure must return an
+integer indicating the number of bytes actually written; when it is
+passed @code{0} as the number of bytes to write, it should behave as
+though an end-of-file was sent to the byte sink.
+
+The other arguments are as for @code{make-custom-binary-input-port}
+(@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}).
address@hidden deffn
+
address@hidden binary output
+Writing to a binary output port can be done using the following
+procedures:
+
address@hidden {Scheme Procedure} put-u8 port octet
address@hidden {C Function} scm_put_u8 (port, octet)
+Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
+binary output port.
address@hidden deffn
+
address@hidden {Scheme Procedure} put-bytevector port bv [start [count]]
address@hidden {C Function} scm_put_bytevector (port, bv, start, count)
+Write the contents of @var{bv} to @var{port}, optionally starting at
+index @var{start} and limiting to @var{count} octets.
address@hidden deffn
+
+
 @node I/O Extensions
 @subsection Using and Extending Ports in C
 
-- 
1.6.1.3

pgph6ri7tKk7G.pgp
Description: PGP signature