@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008
+@c 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.
* 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.
stored and you probably need to try again with a larger buffer.
@end deftypefn
+@node Bytevectors
+@subsection Bytevectors
+
+@cindex bytevector
+@cindex R6RS
+
+A @dfn{bytevector} is a raw bit string. The @code{(rnrs bytevector)}
+module provides the programming interface specified by the
+@uref{http://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}:
+
+@lisp
+#vu8(1 53 204)
+@end 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:
+
+@lisp
+#vu8(1 53 204)
+@result{} #vu8(1 53 204)
+@end lisp
+
+Bytevectors can be used with the binary input/output primitives of the
+R6RS (@pxref{R6RS I/O Ports}).
+
+@menu
+* 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.
+@end menu
+
+@node Bytevector Endianness
+@subsubsection Endianness
+
+@cindex endianness
+@cindex byte order
+@cindex 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 first@footnote{Big 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.
+
+@deffn {Scheme Procedure} native-endianness
+@deffnx {C Function} scm_native_endianness ()
+Return a value denoting the native endianness of the host machine.
+@end deffn
+
+@deffn {Scheme Macro} endianness symbol
+Return an object denoting the endianness specified by @var{symbol}. If
+@var{symbol} is neither @code{big} nor @code{little} then a compile-time
+error is raised.
+@end deffn
+
+@defvr {C Variable} scm_endianness_big
+@defvrx {C Variable} scm_endianness_little
+The objects denoting big (resp. little) endianness.
+@end defvr
+
+
+@node Bytevector Manipulation
+@subsubsection Manipulating Bytevectors
+
+Bytevectors can be created, copied, and analyzed with the following
+procedures.
+
+@deffn {Scheme Procedure} make-bytevector len [fill]
+@deffnx {C Function} scm_make_bytevector (len, fill)
+@deffnx {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].
+@end deffn
+
+@deffn {Scheme Procedure} bytevector? obj
+@deffnx {C Function} scm_bytevector_p (obj)
+Return true if @var{obj} is a bytevector.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-length bv
+@deffnx {C Function} scm_bytevector_length (bv)
+Return the length in bytes of bytevector @var{bv}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector=? bv1 bv2
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-fill! bv fill
+@deffnx {C Function} scm_bytevector_fill_x (bv, fill)
+Fill bytevector @var{bv} with @var{fill}, a byte.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-copy! source source-start target target-start len
+@deffnx {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}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-copy bv
+@deffnx {C Function} scm_bytevector_copy (bv)
+Return a newly allocated copy of @var{bv}.
+@end deffn
+
+Low-level C macros are available. They do not perform any
+type-checking; as such they should be used with care.
+
+@deftypefn {C Macro} size_t SCM_BYTEVECTOR_LENGTH (bv)
+Return the length in bytes of bytevector @var{bv}.
+@end deftypefn
+
+@deftypefn {C Macro} {signed char *} SCM_BYTEVECTOR_CONTENTS (bv)
+Return a pointer to the contents of bytevector @var{bv}.
+@end deftypefn
+
+
+@node Bytevectors as Integers
+@subsubsection 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.
+
+@lisp
+(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)))))
+
+@result{} ("12" "1234" "78563412")
+@end lisp
+
+The most generic procedures to interpret bytevector contents as integers
+are described below.
+
+@deffn {Scheme Procedure} bytevector-uint-ref bv index endianness size
+@deffnx {Scheme Procedure} bytevector-sint-ref bv index endianness size
+@deffnx {C Function} scm_bytevector_uint_ref (bv, index, endianness, size)
+@deffnx {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}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-uint-set! bv index value endianness size
+@deffnx {Scheme Procedure} bytevector-sint-set! bv index value endianness size
+@deffnx {C Function} scm_bytevector_uint_set_x (bv, index, value, endianness, size)
+@deffnx {C Function} scm_bytevector_sint_set_x (bv, index, value, endianness, size)
+Set the @var{size}-byte long unsigned (resp. signed) integer at
+@var{index} to @var{value}, encoded according to @var{endianness}.
+@end deffn
+
+The following procedures are similar to the ones above, but specialized
+to a given integer size:
+
+@deffn {Scheme Procedure} bytevector-u8-ref bv index
+@deffnx {Scheme Procedure} bytevector-s8-ref bv index
+@deffnx {Scheme Procedure} bytevector-u16-ref bv index endianness
+@deffnx {Scheme Procedure} bytevector-s16-ref bv index endianness
+@deffnx {Scheme Procedure} bytevector-u32-ref bv index endianness
+@deffnx {Scheme Procedure} bytevector-s32-ref bv index endianness
+@deffnx {Scheme Procedure} bytevector-u64-ref bv index endianness
+@deffnx {Scheme Procedure} bytevector-s64-ref bv index endianness
+@deffnx {C Function} scm_bytevector_u8_ref (bv, index)
+@deffnx {C Function} scm_bytevector_s8_ref (bv, index)
+@deffnx {C Function} scm_bytevector_u16_ref (bv, index, endianness)
+@deffnx {C Function} scm_bytevector_s16_ref (bv, index, endianness)
+@deffnx {C Function} scm_bytevector_u32_ref (bv, index, endianness)
+@deffnx {C Function} scm_bytevector_s32_ref (bv, index, endianness)
+@deffnx {C Function} scm_bytevector_u64_ref (bv, index, endianness)
+@deffnx {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
+@var{endianness}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-u8-set! bv index value
+@deffnx {Scheme Procedure} bytevector-s8-set! bv index value
+@deffnx {Scheme Procedure} bytevector-u16-set! bv index value endianness
+@deffnx {Scheme Procedure} bytevector-s16-set! bv index value endianness
+@deffnx {Scheme Procedure} bytevector-u32-set! bv index value endianness
+@deffnx {Scheme Procedure} bytevector-s32-set! bv index value endianness
+@deffnx {Scheme Procedure} bytevector-u64-set! bv index value endianness
+@deffnx {Scheme Procedure} bytevector-s64-set! bv index value endianness
+@deffnx {C Function} scm_bytevector_u8_set_x (bv, index, value)
+@deffnx {C Function} scm_bytevector_s8_set_x (bv, index, value)
+@deffnx {C Function} scm_bytevector_u16_set_x (bv, index, value, endianness)
+@deffnx {C Function} scm_bytevector_s16_set_x (bv, index, value, endianness)
+@deffnx {C Function} scm_bytevector_u32_set_x (bv, index, value, endianness)
+@deffnx {C Function} scm_bytevector_s32_set_x (bv, index, value, endianness)
+@deffnx {C Function} scm_bytevector_u64_set_x (bv, index, value, endianness)
+@deffnx {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
+@var{endianness}.
+@end 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):
+
+@deffn {Scheme Procedure} bytevector-u16-native-ref bv index
+@deffnx {Scheme Procedure} bytevector-s16-native-ref bv index
+@deffnx {Scheme Procedure} bytevector-u32-native-ref bv index
+@deffnx {Scheme Procedure} bytevector-s32-native-ref bv index
+@deffnx {Scheme Procedure} bytevector-u64-native-ref bv index
+@deffnx {Scheme Procedure} bytevector-s64-native-ref bv index
+@deffnx {C Function} scm_bytevector_u16_native_ref (bv, index)
+@deffnx {C Function} scm_bytevector_s16_native_ref (bv, index)
+@deffnx {C Function} scm_bytevector_u32_native_ref (bv, index)
+@deffnx {C Function} scm_bytevector_s32_native_ref (bv, index)
+@deffnx {C Function} scm_bytevector_u64_native_ref (bv, index)
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-u16-native-set! bv index value
+@deffnx {Scheme Procedure} bytevector-s16-native-set! bv index value
+@deffnx {Scheme Procedure} bytevector-u32-native-set! bv index value
+@deffnx {Scheme Procedure} bytevector-s32-native-set! bv index value
+@deffnx {Scheme Procedure} bytevector-u64-native-set! bv index value
+@deffnx {Scheme Procedure} bytevector-s64-native-set! bv index value
+@deffnx {C Function} scm_bytevector_u16_native_set_x (bv, index, value)
+@deffnx {C Function} scm_bytevector_s16_native_set_x (bv, index, value)
+@deffnx {C Function} scm_bytevector_u32_native_set_x (bv, index, value)
+@deffnx {C Function} scm_bytevector_s32_native_set_x (bv, index, value)
+@deffnx {C Function} scm_bytevector_u64_native_set_x (bv, index, value)
+@deffnx {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.
+@end deffn
+
+
+@node Bytevectors and Integer Lists
+@subsubsection Converting Bytevectors to/from Integer Lists
+
+Bytevector contents can readily be converted to/from lists of signed or
+unsigned integers:
+
+@lisp
+(bytevector->sint-list (u8-list->bytevector (make-list 4 255))
+ (endianness little) 2)
+@result{} (-1 -1)
+@end lisp
+
+@deffn {Scheme Procedure} bytevector->u8-list bv
+@deffnx {C Function} scm_bytevector_to_u8_list (bv)
+Return a newly allocated list of unsigned 8-bit integers from the
+contents of @var{bv}.
+@end deffn
+
+@deffn {Scheme Procedure} u8-list->bytevector lst
+@deffnx {C Function} scm_u8_list_to_bytevector (lst)
+Return a newly allocated bytevector consisting of the unsigned 8-bit
+integers listed in @var{lst}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector->uint-list bv endianness size
+@deffnx {Scheme Procedure} bytevector->sint-list bv endianness size
+@deffnx {C Function} scm_bytevector_to_uint_list (bv, endianness, size)
+@deffnx {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
+@var{endianness}.
+@end deffn
+
+@deffn {Scheme Procedure} uint-list->bytevector lst endianness size
+@deffnx {Scheme Procedure} sint-list->bytevector lst endianness size
+@deffnx {C Function} scm_uint_list_to_bytevector (lst, endianness, size)
+@deffnx {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
+@var{endianness}.
+@end deffn
+
+@node Bytevectors as Floats
+@subsubsection Interpreting Bytevector Contents as Floating Point Numbers
+
+@cindex 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.
+
+@deffn {Scheme Procedure} bytevector-ieee-single-ref bv index endianness
+@deffnx {Scheme Procedure} bytevector-ieee-double-ref bv index endianness
+@deffnx {C Function} scm_bytevector_ieee_single_ref (bv, index, endianness)
+@deffnx {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}.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-ieee-single-set! bv index value endianness
+@deffnx {Scheme Procedure} bytevector-ieee-double-set! bv index value endianness
+@deffnx {C Function} scm_bytevector_ieee_single_set_x (bv, index, value, endianness)
+@deffnx {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
+@var{endianness}.
+@end deffn
+
+Specialized procedures are also available:
+
+@deffn {Scheme Procedure} bytevector-ieee-single-native-ref bv index
+@deffnx {Scheme Procedure} bytevector-ieee-double-native-ref bv index
+@deffnx {C Function} scm_bytevector_ieee_single_native_ref (bv, index)
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} bytevector-ieee-single-native-set! bv index value
+@deffnx {Scheme Procedure} bytevector-ieee-double-native-set! bv index value
+@deffnx {C Function} scm_bytevector_ieee_single_native_set_x (bv, index, value)
+@deffnx {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.
+@end deffn
+
+
+@node Bytevectors as Strings
+@subsubsection Interpreting Bytevector Contents as Unicode Strings
+
+@cindex Unicode string encoding
+
+Bytevector contents can also be interpreted as Unicode strings encoded
+in one of the most commonly available encoding formats@footnote{Guile
+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
+@code{fr_FR.ISO-8859-1}, then @code{string->utf-8} @i{et al.} will
+assume that Guile strings are Latin-1-encoded.}.
+
+@lisp
+(utf8->string (u8-list->bytevector '(99 97 102 101)))
+@result{} "cafe"
+
+(string->utf8 "caf@'e") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT
+@result{} #vu8(99 97 102 195 169)
+@end lisp
+
+@deffn {Scheme Procedure} string->utf8 str
+@deffnx {Scheme Procedure} string->utf16 str
+@deffnx {Scheme Procedure} string->utf32 str
+@deffnx {C Function} scm_string_to_utf8 (str)
+@deffnx {C Function} scm_string_to_utf16 (str)
+@deffnx {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}.
+@end deffn
+
+@deffn {Scheme Procedure} utf8->string utf
+@deffnx {Scheme Procedure} utf16->string utf
+@deffnx {Scheme Procedure} utf32->string utf
+@deffnx {C Function} scm_utf8_to_string (utf)
+@deffnx {C Function} scm_utf16_to_string (utf)
+@deffnx {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}.
+@end deffn
+
+
@node Regular Expressions
@subsection Regular Expressions
@tpindex Regular expressions
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
+@c 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.
* 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
@end deffn
+@node R6RS I/O Ports
+@subsection R6RS I/O Ports
+
+@cindex R6RS
+@cindex 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}).
+
+@c FIXME: Update description when implemented.
+@emph{Note}: The implementation of this R6RS API is currently far from
+complete, notably due to the lack of support for Unicode I/O and strings.
+
+@menu
+* 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.
+@end menu
+
+@node R6RS End-of-File
+@subsubsection The End-of-File Object
+
+@cindex EOF
+@cindex end-of-file
+
+R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
+ports)} module:
+
+@deffn {Scheme Procedure} eof-object? obj
+@deffnx {C Function} scm_eof_object_p (obj)
+Return true if @var{obj} is the end-of-file (EOF) object.
+@end deffn
+
+In addition, the following procedure is provided:
+
+@deffn {Scheme Procedure} eof-object
+@deffnx {C Function} scm_eof_object ()
+Return the end-of-file (EOF) object.
+
+@lisp
+(eof-object? (eof-object))
+@result{} #t
+@end lisp
+@end deffn
+
+
+@node R6RS Port Manipulation
+@subsubsection Port Manipulation
+
+The procedures listed below operate on any kind of R6RS I/O port.
+
+@deffn {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
+@var{port}. If @var{port} does not support this operation, an error
+condition is raised.
+
+This is similar to Guile's @code{seek} procedure with the
+@code{SEEK_CUR} argument (@pxref{Random Access}).
+@end deffn
+
+@deffn {Scheme Procedure} port-has-port-position? port
+Return @code{#t} is @var{port} supports @code{port-position}.
+@end deffn
+
+@deffn {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
+@code{SEEK_SET} argument (@pxref{Random Access}).
+@end deffn
+
+@deffn {Scheme Procedure} port-has-set-port-position!? port
+Return @code{#t} is @var{port} supports @code{set-port-position!}.
+@end deffn
+
+@deffn {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}.
+@end deffn
+
+
+@node R6RS Binary Input
+@subsubsection Binary Input
+
+@cindex binary input
+
+R6RS binary input ports can be created with the procedures described
+below.
+
+@deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
+@deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
+Return an input port whose contents are drawn from bytevector @var{bv}
+(@pxref{Bytevectors}).
+
+@c FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
+@end deffn
+
+@cindex custom binary input ports
+
+@deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
+@deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
+Return a new custom binary input port@footnote{This 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:
+
+@lisp
+(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")))
+@result{} hello
+@end lisp
+@end deffn
+
+@cindex binary input
+Binary input is achieved using the procedures below:
+
+@deffn {Scheme Procedure} get-u8 port
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} lookahead-u8 port
+@deffnx {C Function} scm_lookahead_u8 (port)
+Like @code{get-u8} but does not update @var{port}'s position to point
+past the octet.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-n port count
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-n! port bv start count
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-some port
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-all port
+@deffnx {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).
+@end deffn
+
+@node R6RS Binary Output
+@subsubsection Binary Output
+
+Binary output ports can be created with the procedures below.
+
+@deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
+@deffnx {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.
+
+@lisp
+(call-with-values
+ (lambda ()
+ (open-bytevector-output-port))
+ (lambda (port get-bytevector)
+ (display "hello" port)
+ (get-bytevector)))
+
+@result{} #vu8(104 101 108 108 111)
+@end lisp
+
+@c FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
+@end deffn
+
+@cindex custom binary output ports
+
+@deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
+@deffnx {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}}).
+@end deffn
+
+@cindex binary output
+Writing to a binary output port can be done using the following
+procedures:
+
+@deffn {Scheme Procedure} put-u8 port octet
+@deffnx {C Function} scm_put_u8 (port, octet)
+Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
+binary output port.
+@end deffn
+
+@deffn {Scheme Procedure} put-bytevector port bv [start [count]]
+@deffnx {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.
+@end deffn
+
+
@node I/O Extensions
@subsection Using and Extending Ports in C
HCoop / bpt / guile.git / commitdiff