mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-11 14:21:10 +02:00
Code Activity

(SRFI-4): Revise for clarity, give each function

Browse source 
explicitly rather than showing TAG so Emacs info-look can find them,
merge "SRFI-4 - Read Syntax" and "SRFI-4 - Procedures" into just one
node.
This commit is contained in:
Kevin Ryde 2004-02-15 00:18:24 +00:00
parent 0e43f514aa
commit f85f9591e0
1 changed files with 123 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

212
doc/ref/srfi-modules.texi
View file

@ -973,127 +973,161 @@ from separate @code{and} and @code{let*}, or from @code{cond} with
@node SRFI-4 @node SRFI-4
@section SRFI-4 - Homogeneous numeric vector datatypes. @section SRFI-4 - Homogeneous numeric vector datatypes
@cindex SRFI-4 @cindex SRFI-4
@c FIXME::martin: Review me! @c FIXME::martin: Review me!
SRFI-4 defines a set of datatypes for vectors whose elements are all SRFI-4 defines a set of datatypes and functions for vectors whose
of the same numeric type. Vectors for signed and unsigned exact elements are numbers, all of the same numeric type. Vectors for
integer or inexact real numbers in several precisions are available. signed and unsigned exact integers and inexact reals in several
precisions are available. Being homogeneous means they require less
memory than normal vectors.
The functions and the read syntax in this section are made available
with
@lisp
(use-modules (srfi srfi-4))
@end lisp
Procedures similar to the vector procedures (@pxref{Vectors}) are Procedures similar to the vector procedures (@pxref{Vectors}) are
provided for handling these homogeneous vectors, but they are distinct provided for handling these homogeneous vectors, but they are distinct
datatypes. datatypes and the two cannot be inter-mixed.
The reason for providing this set of datatypes is that with the
limitation (all elements must have the same type), it is possible to
implement them much more memory-efficient than normal, heterogenous
vectors.
If you want to use these datatypes and the corresponding procedures,
you have to use the module @code{(srfi srfi-4)}.
Ten vector data types are provided: Unsigned and signed integer values Ten vector data types are provided: Unsigned and signed integer values
with 8, 16, 32 and 64 bits and floating point values with 32 and 64 with 8, 16, 32 and 64 bits and floating point values with 32 and 64
bits. In the following descriptions, the tags @code{u8}, @code{s8}, bits. The type is indicated by a tag in the function names,
@code{u16}, @code{s16}, @code{u32}, @code{s32}, @code{u64}, @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32}, @code{s32},
@code{s64}, @code{f32}, @code{f64}, respectively, are used for @code{u64}, @code{s64}, @code{f32}, @code{f64}.
denoting the various types.
@menu The external representation (ie.@: read syntax) for these vectors is
* SRFI-4 - Read Syntax:: How to write homogeneous vector literals. similar to normal Scheme vectors, but with an additional tag
* SRFI-4 - Procedures:: Available homogeneous vector procedures. indiciating the vector's type. For example,
@end menu
@node SRFI-4 - Read Syntax
@subsection SRFI-4 - Read Syntax
Homogeneous numeric vectors have an external representation (read
syntax) similar to normal Scheme vectors, but with an additional tag
telling the vector's type.
@lisp @lisp
#u16(1 2 3) #u16(1 2 3)
@end lisp
denotes a homogeneous numeric vector of three elements, which are the
values 1, 2 and 3, represented as 16-bit unsigned integers.
Correspondingly,
@lisp
#f64(3.1415 2.71) #f64(3.1415 2.71)
@end lisp @end lisp
denotes a vector of two elements, which are the values 3.1415 and Note that the read syntax for floating-point here conflicts with
2.71, represented as floating-point values of 64 bit precision. @code{#f} for false. In Standard Scheme one can write @code{(1
#f3)} for a three element list @code{(1 #f 3)}, but with the SRFI-4
module @code{(1 #f3)} is invalid. @code{(1 #f 3)} is almost certainly
what one should write anyway to make the intention clear, so this is
rarely a problem.
Please note that the read syntax for floating-point vectors conflicts @deffn {Scheme Procedure} u8vector? obj
with Standard Scheme, because there @code{#f} is defined to be the @deffnx {Scheme Procedure} s8vector? obj
literal false value. That means, that with the loaded SRFI-4 module, @deffnx {Scheme Procedure} u16vector? obj
it is not possible to enter some list like @deffnx {Scheme Procedure} s16vector? obj
@deffnx {Scheme Procedure} u32vector? obj
@lisp @deffnx {Scheme Procedure} s32vector? obj
'(1 #f3) @deffnx {Scheme Procedure} u64vector? obj
@end lisp @deffnx {Scheme Procedure} s64vector? obj
@deffnx {Scheme Procedure} f32vector? obj
and hope that it will be parsed as a three-element list with the @deffnx {Scheme Procedure} f64vector? obj
elements 1, @code{#f} and 3. In normal use, this should be no Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
problem, because people tend to terminate tokens sensibly when writing indicated type.
Scheme expressions.
@node SRFI-4 - Procedures
@subsection SRFI-4 Procedures
The procedures listed in this section are provided for all homogeneous
numeric vector datatypes. For brevity, they are not all documented,
but a summary of the procedures is given. In the following
descriptions, you can replace @code{TAG} by any of the datatype
indicators @code{u8}, @code{s8}, @code{u16}, @code{s16}, @code{u32},
@code{s32}, @code{u64}, @code{s64}, @code{f32} and @code{f64}.
For example, you can use the procedures @code{u8vector?},
@code{make-s8vector}, @code{u16vector}, @code{u32vector-length},
@code{s64vector-ref}, @code{f32vector-set!} or @code{f64vector->list}.
@deffn {Scheme Procedure} TAGvector? obj
Return @code{#t} if @var{obj} is a homogeneous numeric vector of type
@code{TAG}.
@end deffn @end deffn
@deffn {Scheme Procedure} make-TAGvector n [value] @deffn {Scheme Procedure} make-u8vector n [value]
Create a newly allocated homogeneous numeric vector of type @deffnx {Scheme Procedure} make-s8vector n [value]
@code{TAG}, which can hold @var{n} elements. If @var{value} is given, @deffnx {Scheme Procedure} make-u16vector n [value]
the vector is initialized with the value, otherwise, the contents of @deffnx {Scheme Procedure} make-s16vector n [value]
the returned vector is not specified. @deffnx {Scheme Procedure} make-u32vector n [value]
@deffnx {Scheme Procedure} make-s32vector n [value]
@deffnx {Scheme Procedure} make-u64vector n [value]
@deffnx {Scheme Procedure} make-s64vector n [value]
@deffnx {Scheme Procedure} make-f32vector n [value]
@deffnx {Scheme Procedure} make-f64vector n [value]
Return a newly allocated homogeneous numeric vector holding @var{n}
elements of the indicated type. If @var{value} is given, the vector
is initialized with that value, otherwise the contents are
unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} TAGvector value1 @dots{} @deffn {Scheme Procedure} u8vector value @dots{}
Create a newly allocated homogeneous numeric vector of type @deffnx {Scheme Procedure} s8vector value @dots{}
@code{TAG}. The returned vector is as long as the number of arguments @deffnx {Scheme Procedure} u16vector value @dots{}
given, and is initialized with the argument values. @deffnx {Scheme Procedure} s16vector value @dots{}
@deffnx {Scheme Procedure} u32vector value @dots{}
@deffnx {Scheme Procedure} s32vector value @dots{}
@deffnx {Scheme Procedure} u64vector value @dots{}
@deffnx {Scheme Procedure} s64vector value @dots{}
@deffnx {Scheme Procedure} f32vector value @dots{}
@deffnx {Scheme Procedure} f64vector value @dots{}
Return a newly allocated homogeneous numeric vector of the indicated
type, holding the given parameter @var{value}s. The vector length is
the number of parameters given.
@end deffn @end deffn
@deffn {Scheme Procedure} TAGvector-length TAGvec @deffn {Scheme Procedure} u8vector-length vec
Return the number of elements in @var{TAGvec}. @deffnx {Scheme Procedure} s8vector-length vec
@deffnx {Scheme Procedure} u16vector-length vec
@deffnx {Scheme Procedure} s16vector-length vec
@deffnx {Scheme Procedure} u32vector-length vec
@deffnx {Scheme Procedure} s32vector-length vec
@deffnx {Scheme Procedure} u64vector-length vec
@deffnx {Scheme Procedure} s64vector-length vec
@deffnx {Scheme Procedure} f32vector-length vec
@deffnx {Scheme Procedure} f64vector-length vec
Return the number of elements in @var{vec}.
@end deffn @end deffn
@deffn {Scheme Procedure} TAGvector-ref TAGvec i @deffn {Scheme Procedure} u8vector-ref vec i
Return the element at index @var{i} in @var{TAGvec}. @deffnx {Scheme Procedure} s8vector-ref vec i
@deffnx {Scheme Procedure} u16vector-ref vec i
@deffnx {Scheme Procedure} s16vector-ref vec i
@deffnx {Scheme Procedure} u32vector-ref vec i
@deffnx {Scheme Procedure} s32vector-ref vec i
@deffnx {Scheme Procedure} u64vector-ref vec i
@deffnx {Scheme Procedure} s64vector-ref vec i
@deffnx {Scheme Procedure} f32vector-ref vec i
@deffnx {Scheme Procedure} f64vector-ref vec i
Return the element at index @var{i} in @var{vec}. The first element
in @var{vec} is index 0.
@end deffn @end deffn
@deffn {Scheme Procedure} TAGvector-ref TAGvec i value @deffn {Scheme Procedure} u8vector-ref vec i value
Set the element at index @var{i} in @var{TAGvec} to @var{value}. The @deffnx {Scheme Procedure} s8vector-ref vec i value
return value is not specified. @deffnx {Scheme Procedure} u16vector-ref vec i value
@deffnx {Scheme Procedure} s16vector-ref vec i value
@deffnx {Scheme Procedure} u32vector-ref vec i value
@deffnx {Scheme Procedure} s32vector-ref vec i value
@deffnx {Scheme Procedure} u64vector-ref vec i value
@deffnx {Scheme Procedure} s64vector-ref vec i value
@deffnx {Scheme Procedure} f32vector-ref vec i value
@deffnx {Scheme Procedure} f64vector-ref vec i value
Set the element at index @var{i} in @var{vec} to @var{value}. The
first element in @var{vec} is index 0. The return value is
unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} TAGvector->list TAGvec @deffn {Scheme Procedure} u8vector->list vec
Return a newly allocated list holding all elements of @var{TAGvec}. @deffnx {Scheme Procedure} s8vector->list vec
@deffnx {Scheme Procedure} u16vector->list vec
@deffnx {Scheme Procedure} s16vector->list vec
@deffnx {Scheme Procedure} u32vector->list vec
@deffnx {Scheme Procedure} s32vector->list vec
@deffnx {Scheme Procedure} u64vector->list vec
@deffnx {Scheme Procedure} s64vector->list vec
@deffnx {Scheme Procedure} f32vector->list vec
@deffnx {Scheme Procedure} f64vector->list vec
Return a newly allocated list holding all elements of @var{vec}.
@end deffn @end deffn
@deffn {Scheme Procedure} list->TAGvector lst @deffn {Scheme Procedure} list->u8vector lst
Return a newly allocated homogeneous numeric vector of type @code{TAG}, @deffnx {Scheme Procedure} list->s8vector lst
@deffnx {Scheme Procedure} list->u16vector lst
@deffnx {Scheme Procedure} list->s16vector lst
@deffnx {Scheme Procedure} list->u32vector lst
@deffnx {Scheme Procedure} list->s32vector lst
@deffnx {Scheme Procedure} list->u64vector lst
@deffnx {Scheme Procedure} list->s64vector lst
@deffnx {Scheme Procedure} list->f32vector lst
@deffnx {Scheme Procedure} list->f64vector lst
Return a newly allocated homogeneous numeric vector of the indicated type,
initialized with the elements of the list @var{lst}. initialized with the elements of the list @var{lst}.
@end deffn @end deffn