[Guile-commits] branch main updated: Document R7RS functions related to bytevectors

[Daniel Llorens]

This is an automated email from the git hooks/post-receive script.

lloda pushed a commit to branch main
in repository guile.

The following commit(s) were added to refs/heads/main by this push:
     new e903b7679 Document R7RS functions related to bytevectors
e903b7679 is described below

commit e903b76795ad6f72b0312eade8950203fb14f914
Author: Daniel Llorens <lloda@sarc.name>
AuthorDate: Sun Jan 15 22:41:48 2023 +0100

    Document R7RS functions related to bytevectors
    
    * doc/ref/api-data.texi (Bytevectors): Fix typo in (r6:bytevector-copy),
      index need not be positive.
      Fix typos in bytevector-length, bytevector=, bytevector-fill!.
      New node 'Bytevector Procedures in R7RS'.
      (Bytevector Procedures in R7RS): Document R7RS bytevector,
      bytevector-copy, bytevector-copy!, bytevector-append.
    * doc/ref/api-io.texi (Binary I/O): Document R7RS
      open-output-bytevector, write-u8, read-u8, peek-u8,
      get-output-bytevector, open-input-bytevector, read-bytevector!,
      read-bytevector, write-bytevector.
    * doc/ref/r7rs.texi (R7RS support): Link to R7RS standard.
---
 doc/ref/api-data.texi | 114 ++++++++++++++++++++++++++++++++++++++++++-----
 doc/ref/api-io.texi   | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/ref/r7rs.texi     |   6 +--
 3 files changed, 227 insertions(+), 14 deletions(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index d332aa997..bc3f3af2f 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -6635,14 +6635,15 @@ and writing.
 @cindex bytevector
 @cindex R6RS
 
-A @dfn{bytevector} is a raw bit string.  The @code{(rnrs bytevectors)}
+A @dfn{bytevector} is a raw byte string.  The @code{(rnrs bytevectors)}
 module provides the programming interface specified by the
 @uref{http://www.r6rs.org/, Revised^6 Report 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.
+interpret their contents in a number of ways: 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 @ref{R7RS Support,R7RS} offers its own set of bytevector
+procedures (@pxref{Bytevector Procedures in R7RS}).
 
 The R6RS (Section 4.3.4) specifies an external representation for
 bytevectors, whereby the octets (integers in the range 0--255) contained
@@ -6673,6 +6674,7 @@ Bytevectors can be used with the binary input/output 
primitives
 * Bytevectors as Strings::      Interpreting bytes as Unicode strings.
 * Bytevectors as Arrays::       Guile extension to the bytevector API.
 * Bytevectors as Uniform Vectors::  Bytevectors and SRFI-4.
+* Bytevector Procedures in R7RS:: R7RS interface for bytevectors.
 * Bytevector Slices::           Aliases for parts of a bytevector.
 @end menu
 
@@ -6722,6 +6724,7 @@ The objects denoting big- and little-endianness, 
respectively.
 Bytevectors can be created, copied, and analyzed with the following
 procedures and C functions.
 
+@anchor{x-make-bytevector}
 @deffn {Scheme Procedure} make-bytevector len [fill]
 @deffnx {C Function} scm_make_bytevector (len, fill)
 @deffnx {C Function} scm_c_make_bytevector (size_t len)
@@ -6730,6 +6733,7 @@ is given, fill it with @var{fill}; @var{fill} must be in 
the range
 [-128,255].
 @end deffn
 
+@anchor{x-bytevector?}
 @deffn {Scheme Procedure} bytevector? obj
 @deffnx {C Function} scm_bytevector_p (obj)
 Return true if @var{obj} is a bytevector.
@@ -6739,6 +6743,7 @@ Return true if @var{obj} is a bytevector.
 Equivalent to @code{scm_is_true (scm_bytevector_p (obj))}.
 @end deftypefn
 
+@anchor{x-bytevector-length}
 @deffn {Scheme Procedure} bytevector-length bv
 @deffnx {C Function} scm_bytevector_length (bv)
 Return the length in bytes of bytevector @var{bv}.
@@ -6750,31 +6755,33 @@ Likewise, return the length in bytes of bytevector 
@var{bv}.
 
 @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
+Return @code{#t} if @var{bv1} equals @var{bv2}---i.e., if they have the same
 length and contents.
 @end deffn
 
 @deffn {Scheme Procedure} bytevector-fill! bv fill [start [end]]
 @deffnx {C Function} scm_bytevector_fill_x (bv, fill)
 Fill positions [@var{start} ... @var{end}) of bytevector @var{bv} with
-byte @var{fill}. @var{start} defaults to 0 and @var{end} defaults to the
-length of @var{bv}.@footnote{R6RS defines @code{(bytevector-fill! bv
-fill)}. Arguments @var{start} and @var{end} are a Guile extension
+byte @var{fill}.  @var{start} defaults to 0 and @var{end} defaults to the
+length of @var{bv}.@footnote{R6RS only defines @code{(bytevector-fill! bv
+fill)}.  Arguments @var{start} and @var{end} are a Guile extension
 (cf. @ref{x-vector-fill!,@code{vector-fill!}},
 @ref{x-string-fill!,@code{string-fill!}}).}
 @end deffn
 
+@anchor{x-r6:bytevector-copy!}
 @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})
+reading from @var{source-start} (an index index within @var{source})
 and writing at @var{target-start}.
 
 It is permitted for the @var{source} and @var{target} regions to
-overlap. In that case, copying takes place as if the source is first
+overlap.  In that case, copying takes place as if the source is first
 copied into a temporary bytevector and then into the destination.
 @end deffn
 
+@anchor{x-r6:bytevector-copy}
 @deffn {Scheme Procedure} bytevector-copy bv
 @deffnx {C Function} scm_bytevector_copy (bv)
 Return a newly allocated copy of @var{bv}.
@@ -6852,6 +6859,7 @@ Set the @var{size}-byte long signed integer at 
@var{index} to
 The following procedures are similar to the ones above, but specialized
 to a given integer size:
 
+@anchor{x-bytevector-u8-ref}
 @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
@@ -6873,6 +6881,7 @@ Return the unsigned @var{n}-bit (signed) integer (where 
@var{n} is 8,
 @var{endianness}.
 @end deffn
 
+@anchor{x-bytevector-u8-set!}
 @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
@@ -6952,6 +6961,7 @@ Return a newly allocated list of unsigned 8-bit integers 
from the
 contents of @var{bv}.
 @end deffn
 
+@anchor{x-u8-list->bytevector}
 @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
@@ -7109,6 +7119,87 @@ Bytevectors may also be accessed with the SRFI-4 API. 
@xref{SRFI-4 and
 Bytevectors}, for more information.
 
 
+@node Bytevector Procedures in R7RS
+@subsubsection Bytevector Procedures in R7RS
+
+The @ref{R7RS Support,R7RS} (Section 6.9) defines a set of
+bytevector manipulation procedures, accessible with
+
+@example
+(use-modules (scheme base))
+@end example
+
+Of these, @ref{x-make-bytevector,@code{make-bytevector}},
+@ref{x-bytevector?,@code{bytevector?}},
+@ref{x-bytevector-length,@code{bytevector-length}},
+@ref{x-bytevector-u8-ref,@code{bytevector-u8-ref}} and
+@ref{x-bytevector-u8-set!,@code{bytevector-u8-set!}} have the same
+definition as in R6RS.  The procedures listed below either have a
+different definition in R7RS and R6RS, or are not defined in R6RS.
+
+@deffn {Scheme Procedure} bytevector arg @dots{}
+Return a newly allocated bytevector composed of the given arguments.
+Analogous to @code{list}.
+
+@lisp
+(bytevector 2 3 4) @result{} #vu8(2 3 4)
+@end lisp
+
+See also @ref{x-u8-list->bytevector,@code{u8-list->bytevector}}.
+@end deffn
+
+@anchor{x-r7:bytevector-copy}
+@deffn {Scheme Procedure} bytevector-copy bv [start [end]]
+Returns a newly allocated bytevector containing the elements of @var{bv}
+in the range [@var{start} ... @var{end}).  @var{start} defaults to 0 and
+@var{end} defaults to the length of @var{bv}.
+
+@lisp
+(define bv #vu8(0 1 2 3 4 5))
+(bytevector-copy bv) @result{} #vu8(0 1 2 3 4 5)
+(bytevector-copy bv 2) @result{} #vu8(2 3 4 5)
+(bytevector-copy bv 2 4) @result{} #vu8(2 3)
+@end lisp
+
+See also @ref{x-r6:bytevector-copy,the R6RS version}.
+@end deffn
+
+@anchor{x-r7:bytevector-copy!}
+@deffn {Scheme Procedure} bytevector-copy! dst at src [start [end]]
+Copy the block of elements from bytevector @var{src} in the range
+[@var{start} ... @var{end}) into bytevector @var{dst}, starting at
+position @var{at}.  @var{start} defaults to 0 and @var{end} defaults to
+the length of @var{src}.  It is an error for @var{dst}
+to have a length less than @var{at} + (@var{end} - @var{start}).
+
+See also @ref{x-r6:bytevector-copy!,the R6RS version}.  With
+
+@lisp
+(use-modules ((rnrs bytevectors) #:prefix r6:)
+             ((scheme base) #:prefix r7:))
+@end lisp
+
+the following calls are equivalent:
+
+@lisp
+(r6:bytevector-copy! source source-start target target-start len)
+(r7:bytevector-copy! target target-start source source-start (+ source-start 
len))
+@end lisp
+
+@end deffn
+
+@rnindex bytevector-append
+@deffn {Scheme Procedure} bytevector-append arg @dots{}
+Return a newly allocated bytevector whose characters form the
+concatenation of the given bytevectors @var{arg} @enddots{}
+
+@lisp
+(bytevector-append #vu8(0 1 2) #vu8(3 4 5))
+@result{} #vu8(0 1 2 3 4 5)
+@end lisp
+@end deffn
+
+
 @node Bytevector Slices
 @subsubsection Bytevector Slices
 
@@ -7152,6 +7243,7 @@ bv
 @result{} #vu8(0 1 77 3 4 5 6 7 8 9)
 @end lisp
 
+
 @node Arrays
 @subsection Arrays
 @tpindex Arrays
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index a0be2dd57..86f83e85e 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -150,12 +150,14 @@ some different kind of port, that's not the case: all 
ports in Guile are
 both binary and textual ports.
 
 @cindex binary input
+@anchor{x-get-u8}
 @deffn {Scheme Procedure} get-u8 port
 @deffnx {C Function} scm_get_u8 (port)
 Return an octet read from @var{port}, an input port, blocking as
 necessary, or the end-of-file object.
 @end deffn
 
+@anchor{x-lookahead-u8}
 @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
@@ -227,6 +229,7 @@ will be read again in last-in first-out order.
 To perform binary output on a port, use @code{put-u8} or
 @code{put-bytevector}.
 
+@anchor{x-put-u8}
 @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
@@ -239,6 +242,124 @@ Write the contents of @var{bv} to @var{port}, optionally 
starting at
 index @var{start} and limiting to @var{count} octets.
 @end deffn
 
+@subsubheading Binary I/O in R7RS
+
+@ref{R7RS Standard Libraries,R7RS} defines the following binary I/O
+procedures.  Access them with
+
+@example
+(use-modules (scheme base))
+@end example
+
+@anchor{x-open-output-bytevector}
+@deffn {Scheme Procedure} open-output-bytevector
+Returns a binary output port that will accumulate bytes
+for retrieval by @ref{x-get-output-bytevector,@code{get-output-bytevector}}.
+@end deffn
+
+@deffn {Scheme Procedure} write-u8 byte [out]
+Writes @var{byte} to the given binary output port @var{out} and returns
+an unspecified value.  @var{out} defaults to @code{(current-output-port)}.
+
+See also @ref{x-put-u8,@code{put-u8}}.
+@end deffn
+
+@deffn {Scheme Procedure} read-u8 [in]
+Returns the next byte available from the binary input port @var{in},
+updating the port to point to the following byte.  If no more bytes are
+available, an end-of-file object is returned.  @var{in} defaults to
+@code{(current-input-port)}.
+
+See also @ref{x-get-u8,@code{get-u8}}.
+@end deffn
+
+@deffn {Scheme Procedure} peek-u8 [in]
+Returns the next byte available from the binary input port @var{in},
+but without updating the port to point to the following
+byte.  If no more bytes are available, an end-of-file object
+is returned.  @var{in} defaults to @code{(current-input-port)}.
+
+See also @ref{x-lookahead-u8,@code{lookahead-u8}}.
+@end deffn
+
+@anchor{x-get-output-bytevector}
+@deffn {Scheme Procedure} get-output-bytevector port
+Returns a bytevector consisting of the bytes that have been output to
+@var{port} so far in the order they were output.  It is an error if
+@var{port} was not created with
+@ref{x-open-output-bytevector,@code{open-output-bytevector}}.
+
+@example
+(define out (open-output-bytevector))
+(write-u8 1 out)
+(write-u8 2 out)
+(write-u8 3 out)
+(get-output-bytevector out) @result{} #vu8(1 2 3)
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} open-input-bytevector bv
+Takes a bytevector @var{bv} and returns a binary input port that
+delivers bytes from @var{bv}.
+
+@example
+(define in (open-input-bytevector #vu8(1 2 3)))
+(read-u8 in) @result{} 1
+(peek-u8 in) @result{} 2
+(read-u8 in) @result{} 2
+(read-u8 in) @result{} 3
+(read-u8 in) @result{} #<eof>
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} read-bytevector! bv [port [start [end]]]
+Reads the next @var{end} - @var{start} bytes, or as many as are
+available before the end of file, from the binary input port into the
+bytevector @var{bv} in left-to-right order beginning at the @var{start}
+position.  If @var{end} is not supplied, reads until the end of @var{bv}
+has been reached.  If @var{start} is not supplied, reads beginning at
+position 0.
+
+Returns the number of bytes read.  If no bytes are available, an
+end-of-file object is returned.
+
+@example
+(define in (open-input-bytevector #vu8(1 2 3)))
+(define bv (make-bytevector 5 0))
+(read-bytevector! bv in 1 3) @result{} 2
+bv @result{} #vu8(0 1 2 0 0 0)
+@end example
+
+@end deffn
+
+@deffn {Scheme Procedure} read-bytevector k in
+Reads the next @var{k} bytes, or as many as are available before the end
+of file if that is less than @var{k}, from the binary input port
+@var{in} into a newly allocated bytevector in left-to-right order, and
+returns the bytevector.  If no bytes are available before the end of
+file, an end-of-file object is returned.
+
+@example
+(define bv #vu8(1 2 3))
+(read-bytevector 2 (open-input-bytevector bv)) @result{} #vu8(1 2)
+(read-bytevector 10 (open-input-bytevector bv)) @result{} #vu8(1 2 3)
+@end example
+
+@end deffn
+
+@deffn {Scheme Procedure} write-bytevector bv [port [start [end]]]
+Writes the bytes of bytevector @var{bv} from @var{start} to @var{end} in
+left-to-right order to the binary output @var{port}.  @var{start}
+defaults to 0 and @var{end} defaults to the length of @var{bv}.
+
+@example
+(define out (open-output-bytevector))
+(write-bytevector #vu8(0 1 2 3 4) out 2 4)
+(get-output-bytevector out) @result{} #vu8(2 3)
+@end example
+
+@end deffn
+
 @node Encoding
 @subsection Encoding
 
diff --git a/doc/ref/r7rs.texi b/doc/ref/r7rs.texi
index c315b1f47..837fe8925 100644
--- a/doc/ref/r7rs.texi
+++ b/doc/ref/r7rs.texi
@@ -8,9 +8,9 @@
 @section R7RS Support
 @cindex R7RS
 
-The R7RS standard is essentially R5RS (directly supported by Guile),
-plus a module facility, plus an organization of bindings into a standard
-set of modules.
+The @uref{https://small.r7rs.org/,R7RS} standard is essentially R5RS
+(directly supported by Guile), plus a module facility, plus an
+organization of bindings into a standard set of modules.
 
 Happily, the syntax for R7RS modules was chosen to be compatible with
 R6RS, and so Guile's documentation there applies.  @xref{R6RS