commit 681f05bfcca1243be688c10e6087869c2215e468
parent 9d59af7ab8d9eca1b9c64c4cf3d93a04dff8c7ba
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Sun, 4 Feb 2024 21:11:01 -0500
Bytevectors: Texify and clean up.
Diffstat:
1 file changed, 62 insertions(+), 99 deletions(-)
diff --git a/doc/r7rs-small/procedures/bytevectors.texinfo b/doc/r7rs-small/procedures/bytevectors.texinfo
@@ -1,45 +1,48 @@
@node Bytevectors
@section Bytevectors
-Bytevectors represent blocks of binary data. They are fixed-length sequences of bytes,
-where a byte is an exact integer in the range from 0 to 255 inclusive. A bytevector is
-typically more space-efficient than a vector containing the same values.
+@dfn{Bytevectors} represent blocks of binary data.
+They are fixed-length sequences of bytes, where
+a @dfn{byte} is an exact integer in the range from 0 to 255 inclusive.
+A bytevector is typically more space-efficient than a vector
+containing the same values.
+
+The @dfn{length} of a bytevector is the number of elements that it
+contains. This number is a non-negative integer that is fixed when
+the bytevector is created. The @dfn{valid indexes} of
+a bytevector are the exact non-negative integers less than the length of the
+bytevector, starting at index zero as with vectors.
+
+Bytevectors are written using the notation @code{#u8(}@var{byte} @dots{}@code{)}.
+For example, a bytevector of length 3 containing the byte 0 in element
+0, the byte 10 in element 1, and the byte 5 in
+element 2 can be written as follows:
-The length of a bytevector is the number of elements that it contains. This number is a
-non-negative integer that is fixed when the bytevector is created. The valid indexesof a
-bytevector are the exact non-negative integers less than the length of the bytevector,
-starting at index zero as with vectors.
-
-Bytevectors are written using the notation #u8(
-
-byte @dots{}). For example, a bytevector of length 3 containing the byte 0 in element 0, the byte
-10 in element 1, and the byte 5 in element 2 can be written as follows:
+@lisp
+#u8(0 10 5)
+@end lisp
-#u8(0 10 5) Bytevector constants are self-evaluating, so they do not need to be quoted in
-programs.
+Bytevector constants are self-evaluating, so they do not need to be quoted in programs.
@deffn procedure bytevector? obj
-Returns #t if
-
-obj is a bytevector. Otherwise, #f is returned.
+Returns @code{#t} if @var{obj} is a bytevector.
+Otherwise, @code{#f} is returned.
@end deffn
@deffn procedure make-bytevector k
@deffnx procedure make-bytevector k byte
-The make-bytevector procedure returns a newly allocated bytevector of length
-
-k. If
-
-byte is given, then all elements of the bytevector are initialized to
-
-byte, otherwise the contents of each element are unspecified.
+The @code{make-bytevector} procedure returns a newly allocated bytevector of
+length @var{k}. If @var{byte} is given, then all elements of the bytevector
+are initialized to @var{byte}, otherwise the contents of each
+element are unspecified.
@lisp
(make-bytevector 2 12) @result{} #u8(12 12)
@end lisp
+
@end deffn
@deffn procedure bytevector byte@dots{}
@@ -50,51 +53,35 @@ Returns a newly allocated bytevector containing its arguments.
(bytevector 1 3 5 1 3 5) @result{} #u8(1 3 5 1 3 5)
(bytevector) @result{} #u8()
@end lisp
+
@end deffn
@deffn procedure bytevector-length bytevector
Returns the length of
+@var{bytevector} in bytes as an exact integer.
-bytevector in bytes as an exact integer.
@end deffn
@deffn procedure bytevector-u8-ref bytevector k
-It is an error if
-
-k is not a valid index of
+It is an error if @var{k} is not a valid index of @var{bytevector}.
-bytevector.
-
-Returns the
-
-kth byte of
-
-bytevector.
+Returns the @var{k}th byte of @var{bytevector}.
@lisp
(bytevector-u8-ref '#u8(1 1 2 3 5 8 13 21)
5)
@result{} 8
@end lisp
+
@end deffn
@deffn procedure bytevector-u8-set! bytevector k byte
-It is an error if
-
-k is not a valid index of
-
-bytevector.
+It is an error if @var{k} is not a valid index of @var{bytevector}.
-Stores
-
-byte as the
-
-kth byte of
-
-bytevector.
+Stores @var{byte} as the @var{k}th byte of @var{bytevector}.
@lisp
(let ((bv (bytevector 1 2 3 4)))
@@ -102,58 +89,38 @@ bytevector.
bv)
@result{} #u8(1 3 3 4)
@end lisp
+
@end deffn
@deffn procedure bytevector-copy bytevector
@deffnx procedure bytevector-copy bytevector start
@deffnx procedure bytevector-copy bytevector start end
-Returns a newly allocated bytevector containing the bytes in
-
-bytevector between
-
-start and
-
-end.
+Returns a newly allocated bytevector containing the bytes in @var{bytevector}
+between @var{start} and @var{end}.
@lisp
(define a #u8(1 2 3 4 5))
(bytevector-copy a 2 4)) @result{} #u8(3 4)
@end lisp
+
@end deffn
@deffn procedure bytevector-copy! to at from
@deffnx procedure bytevector-copy! to at from start
@deffnx procedure bytevector-copy! to at from start end
-It is an error if
-
-at is less than zero or greater than the length of
-
-to. It is also an error if (- (bytevector-length
-
-to)
-
-at) is less than (-
-
-end
-
-start).
-
-Copies the bytes of bytevector
-
-from between
+It is an error if @var{at} is less than zero or greater than the length of @var{to}.
+It is also an error if @code{(- (bytevector-length }@var{to}@code{)} @var{at}@code{)}
+is less than @code{(- }@var{end} @var{start}@code{)}.
-start and
-
-end to bytevector
-
-to, starting at
-
-at. The order in which bytes are copied is unspecified, except that if the source and
-destination overlap, copying takes place as if the source is first copied into a temporary
-bytevector and then into the destination. This can be achieved without allocating storage
-by making sure to copy in the correct direction in such circumstances.
+Copies the bytes of bytevector @var{from} between @var{start} and @var{end}
+to bytevector @var{to}, starting at @var{at}. The order in which bytes are
+copied is unspecified, except that if the source and destination overlap,
+copying takes place as if the source is first copied into a temporary
+bytevector and then into the destination. This can be achieved without
+allocating storage by making sure to copy in the correct direction in
+such circumstances.
@lisp
(define a (bytevector 1 2 3 4 5))
@@ -162,19 +129,20 @@ by making sure to copy in the correct direction in such circumstances.
b @result{} #u8(10 1 2 40 50)
@end lisp
-Note: This procedure appears in R6RS, but places the source before the destination,
+Note: This procedure appears in @rsixrs{}, but places the source before the destination,
contrary to other such procedures in Scheme.
@end deffn
@deffn procedure bytevector-append bytevector@dots{}
Returns a newly allocated bytevector whose elements are the concatenation of the
-elements in the given bytevectors.
+elements in the given @var{bytevector}s.
@lisp
(bytevector-append #u8(0 1 2) #u8(3 4 5))
@result{} #u8(0 1 2 3 4 5)
@end lisp
+
@end deffn
@deffn procedure utf8->string bytevector
@@ -184,25 +152,20 @@ elements in the given bytevectors.
@deffnx procedure string->utf8 string start
@deffnx procedure string->utf8 string start end
-It is an error for
-
-bytevector to contain invalid UTF-8 byte sequences.
+It is an error for @var{bytevector} to contain invalid UTF-8 byte sequences.
-These procedures translate between strings and bytevectors that encode those strings
-using the UTF-8 encoding. The utf8->string procedure decodes the bytes of a bytevector
-between
-
-start and
-
-end and returns the corresponding string; the string->utf8 procedure encodes the
-characters of a string between
-
-start and
-
-end and returns the corresponding bytevector.
+These procedures translate between strings and bytevectors
+that encode those strings using the UTF-8 encoding.
+The @code{utf8->string} procedure decodes the bytes of
+a bytevector between @var{start} and @var{end}
+and returns the corresponding string;
+the @code{string->utf8} procedure encodes the characters of a
+string between @var{start} and @var{end}
+and returns the corresponding bytevector.
@lisp
(utf8->string #u8(#x41)) @result{} "A"
-(string->utf8 "λ") @result{} #u8(#xCE #xBB)
+(string->utf8 "@theultimate{}") @result{} #u8(#xCE #xBB)
@end lisp
+
@end deffn
