summaryrefslogtreecommitdiffstats
path: root/byte.txi
diff options
context:
space:
mode:
authorSteve Langasek <vorlon@debian.org>2005-01-10 08:53:33 +0000
committerBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:30 -0800
commite33f9eb9cf5cc29c36ce2aa7e10cd0f37ae0cc8e (patch)
treeabbf06041619e445f9d0b772b0d58132009d8234 /byte.txi
parentf559c149c83da84d0b1c285f0298c84aec564af9 (diff)
parent8466d8cfa486fb30d1755c4261b781135083787b (diff)
downloadslib-e33f9eb9cf5cc29c36ce2aa7e10cd0f37ae0cc8e.tar.gz
slib-e33f9eb9cf5cc29c36ce2aa7e10cd0f37ae0cc8e.zip
Import Debian changes 3a1-4.2debian/3a1-4.2
slib (3a1-4.2) unstable; urgency=low * Non-maintainer upload. * Add guile.init.local for use within the build dir, since otherwise we have an (earlier unnoticed) circular build-dep due to a difference between scm and guile. slib (3a1-4.1) unstable; urgency=low * Non-maintainer upload. * Build-depend on guile-1.6 instead of scm, since the new version of scm is wedged in unstable (closes: #281809). slib (3a1-4) unstable; urgency=low * Also check for expected creation on slibcat. (Closes: #240096) slib (3a1-3) unstable; urgency=low * Also check for /usr/share/guile/1.6/slib before installing for guile 1.6. (Closes: #239267) slib (3a1-2) unstable; urgency=low * Add format.scm back into slib until gnucash stops using it. * Call guile-1.6 new-catalog (Closes: #238231) slib (3a1-1) unstable; urgency=low * New upstream release * Remove Info section from doc-base file (Closes: #186950) * Remove period from end of description (linda, lintian) * html gen fixed upstream (Closes: #111778) slib (2d4-2) unstable; urgency=low * Fix url for upstream source (Closes: #144981) * Fix typo in slib.texi (enquque->enqueue) (Closes: #147475) * Add build depends. slib (2d4-1) unstable; urgency=low * New upstream. slib (2d3-1) unstable; urgency=low * New upstream. * Remove texi2html call in debian/rules. Now done upstream. Add make html instead. * Changes to rules and doc-base to conform to upstream html gen * Clean up upstream makefile to make sure it cleans up after itself.
Diffstat (limited to 'byte.txi')
-rw-r--r--byte.txi179
1 files changed, 179 insertions, 0 deletions
diff --git a/byte.txi b/byte.txi
new file mode 100644
index 0000000..01c725b
--- /dev/null
+++ b/byte.txi
@@ -0,0 +1,179 @@
+@code{(require 'byte)}
+@ftindex byte
+
+@noindent
+Some algorithms are expressed in terms of arrays of small integers.
+Using Scheme strings to implement these arrays is not portable vis-a-vis
+the correspondence between integers and characters and non-ascii
+character sets. These functions abstract the notion of a @dfn{byte}.
+@cindex byte
+@cindex byte
+
+
+@defun byte-ref bytes k
+
+@var{k} must be a valid index of @var{bytes}. @code{byte-ref} returns byte @var{k} of @var{bytes} using
+zero-origin indexing.
+@end defun
+
+@deffn {Procedure} byte-set! bytes k byte
+
+@var{k} must be a valid index of @var{bytes}, and @var{byte} must be a small
+nonnegative integer. @code{byte-set!} stores @var{byte} in element @var{k} of @var{bytes} and
+returns an unspecified value. @c <!>
+@end deffn
+
+@defun make-bytes k byte
+
+
+@defunx make-bytes k
+@code{make-bytes} returns a newly allocated byte-array of length @var{k}. If @var{byte} is
+given, then all elements of the byte-array are initialized to @var{byte},
+otherwise the contents of the byte-array are unspecified.
+@end defun
+
+@defun bytes-length bytes
+
+@code{bytes-length} returns length of byte-array @var{bytes}.
+@end defun
+
+@defun bytes byte @dots{}
+
+Returns a newly allocated byte-array composed of the small
+nonnegative arguments.
+@end defun
+
+@defun bytes->list bytes
+
+@code{bytes->list} returns a newly allocated list of the bytes that make up the
+given byte-array.
+@end defun
+
+@defun list->bytes bytes
+
+@code{list->bytes} returns a newly allocated byte-array formed from the small
+nonnegative integers in the list @var{bytes}.
+@end defun
+@noindent
+@code{Bytes->list} and @code{list->bytes} are inverses so far as
+@code{equal?} is concerned.
+@findex equal?
+
+
+@defun bytes-copy bytes
+
+Returns a newly allocated copy of the given @var{bytes}.
+@end defun
+
+@deffn {Procedure} bytes-reverse! bytes
+
+Reverses the order of byte-array @var{bytes}.
+@end deffn
+
+@defun bytes-reverse bytes
+
+Returns a newly allocated bytes-array consisting of the elements of
+@var{bytes} in reverse order.
+@end defun
+@noindent
+@cindex binary
+Input and output of bytes should be with ports opened in @dfn{binary}
+@cindex binary
+mode (@pxref{Input/Output}). Calling @code{open-file} with @r{'rb} or
+@findex open-file
+@r{'wb} modes argument will return a binary port if the Scheme
+implementation supports it.
+
+
+@defun write-byte byte port
+
+
+@defunx write-byte byte
+Writes the byte @var{byte} (not an external representation of the byte) to
+the given @var{port} and returns an unspecified value. The @var{port} argument may
+be omitted, in which case it defaults to the value returned by
+@code{current-output-port}.
+@findex current-output-port
+@end defun
+
+@defun read-byte port
+
+
+@defunx read-byte
+Returns the next byte available from the input @var{port}, updating the @var{port}
+to point to the following byte. If no more bytes are available, an
+end-of-file object is returned. @var{port} may be omitted, in which case it
+defaults to the value returned by @code{current-input-port}.
+@findex current-input-port
+@end defun
+@noindent
+When reading and writing binary numbers with @code{read-bytes} and
+@code{write-bytes}, the sign of the length argument determines the
+endianness (order) of bytes. Positive treats them as big-endian,
+the first byte input or output is highest order. Negative treats
+them as little-endian, the first byte input or output is the lowest
+order.
+
+@noindent
+Once read in, SLIB treats byte sequences as big-endian. The
+multi-byte sequences produced and used by number conversion routines
+@pxref{Byte/Number Conversions} are always big-endian.
+
+
+@defun read-bytes n port
+
+
+@defunx read-bytes n
+@code{read-bytes} returns a newly allocated bytes-array filled with
+@code{(abs @var{n})} bytes read from @var{port}. If @var{n} is positive, then
+the first byte read is stored at index 0; otherwise the last byte
+read is stored at index 0. Note that the length of the returned
+string will be less than @code{(abs @var{n})} if @var{port} reaches
+end-of-file.
+
+@var{port} may be omitted, in which case it defaults to the value returned
+by @code{current-input-port}.
+@end defun
+
+@defun write-bytes bytes n port
+
+
+@defunx write-bytes bytes n
+@code{write-bytes} writes @code{(abs @var{n})} bytes to output-port @var{port}. If @var{n} is
+positive, then the first byte written is index 0 of @var{bytes}; otherwise
+the last byte written is index 0 of @var{bytes}. @code{write-bytes} returns an unspecified
+value.
+
+@var{port} may be omitted, in which case it defaults to the value returned
+by @code{current-output-port}.
+@end defun
+@noindent
+@code{substring-read!} and @code{substring-write} provide
+lower-level procedures for reading and writing blocks of bytes. The
+relative size of @var{start} and @var{end} determines the order of
+writing.
+
+
+@deffn {Procedure} substring-read! string start end port
+
+
+@deffnx {Procedure} substring-read! string start end
+Fills @var{string} with up to @code{(abs (- @var{start} @var{end}))} bytes
+read from @var{port}. The first byte read is stored at index @var{string}.
+@code{substring-read!} returns the number of bytes read.
+
+@var{port} may be omitted, in which case it defaults to the value returned
+by @code{current-input-port}.
+@end deffn
+
+@defun substring-write string start end port
+
+
+@defunx substring-write string start end
+@code{substring-write} writes @code{(abs (- @var{start} @var{end}))} bytes to
+output-port @var{port}. The first byte written is index @var{start} of @var{string}. @code{substring-write}
+returns the number of bytes written.
+
+@var{port} may be omitted, in which case it defaults to the value returned
+by @code{current-output-port}.
+@end defun