mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
Import documentation for the R6RS bytevector and port APIs.
* doc/ref/api-compound.texi (Uniform Numeric Vectors): Add xref to the bytevector API. * doc/ref/api-data.texi (Bytevectors): New node. * doc/ref/api-io.texi (R6RS I/O Ports): New node.
This commit is contained in:
Ludovic Courtès
parent
fa1804e943
commit
b242715b28
3 changed files with 668 additions and 3 deletions
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Guile Reference Manual.
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009
|
||||
@c Free Software Foundation, Inc.
|
||||
@c See the file guile.texi for copying conditions.
|
||||
|
||||
|
|
@ -1405,6 +1405,12 @@ C}), but returns a pointer to the elements of a uniform numeric vector
|
|||
of the indicated kind.
|
||||
@end deftypefn
|
||||
|
||||
Uniform numeric vectors can be written to and read from input/output
|
||||
ports using the procedures listed below. However, bytevectors may often
|
||||
be more convenient for binary input/output since they provide more
|
||||
flexibility in the interpretation of raw byte sequences
|
||||
(@pxref{Bytevectors}).
|
||||
|
||||
@deffn {Scheme Procedure} uniform-vector-read! uvec [port_or_fd [start [end]]]
|
||||
@deffnx {C Function} scm_uniform_vector_read_x (uvec, port_or_fd, start, end)
|
||||
Fill the elements of @var{uvec} by reading
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@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.
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
@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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@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.
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
||||
@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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue