diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 33ccdfeae..69ef40d30 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -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, 2009 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009, 2010 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -22,7 +22,6 @@ values can be looked up within them. * Pairs:: Scheme's basic building block. * Lists:: Special list functions supported by Guile. * Vectors:: One-dimensional arrays of Scheme objects. -* Uniform Numeric Vectors:: Vectors with elements of a single numeric type. * Bit Vectors:: Vectors of bits. * Generalized Vectors:: Treating all vector-like things uniformly. * Arrays:: Matrices, etc. @@ -671,6 +670,7 @@ and that most array procedures operate happily on vectors * Vector Creation:: Dynamic vector creation and validation. * Vector Accessors:: Accessing and modifying vector contents. * Vector Accessing from C:: Ways to work with vectors from C. +* Uniform Numeric Vectors:: Vectors of unboxed numeric values. @end menu @@ -959,501 +959,17 @@ scm_array_handle_release (&handle); @end deftypefn @node Uniform Numeric Vectors -@subsection Uniform Numeric Vectors +@subsubsection Uniform Numeric Vectors A uniform numeric vector is a vector whose elements are all of a single numeric type. Guile offers uniform numeric vectors for signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of floating point values, and complex floating-point numbers of these two -sizes. - -Strings could be regarded as uniform vectors of characters, -@xref{Strings}. Likewise, bit vectors could be regarded as uniform -vectors of bits, @xref{Bit Vectors}. Both are sufficiently different -from uniform numeric vectors that the procedures described here do not -apply to these two data types. However, both strings and bit vectors -are generalized vectors, @xref{Generalized Vectors}, and arrays, -@xref{Arrays}. - -Uniform numeric vectors are the special case of one dimensional uniform -numeric arrays. - -Uniform numeric vectors can be useful since they consume less memory -than the non-uniform, general vectors. Also, since the types they can -store correspond directly to C types, it is easier to work with them -efficiently on a low level. Consider image processing as an example, -where you want to apply a filter to some image. While you could store -the pixels of an image in a general vector and write a general -convolution function, things are much more efficient with uniform -vectors: the convolution function knows that all pixels are unsigned -8-bit values (say), and can use a very tight inner loop. - -That is, when it is written in C. Functions for efficiently working -with uniform numeric vectors from C are listed at the end of this -section. - -Procedures similar to the vector procedures (@pxref{Vectors}) are -provided for handling these uniform vectors, but they are distinct -datatypes and the two cannot be inter-mixed. If you want to work -primarily with uniform numeric vectors, but want to offer support for -general vectors as a convenience, you can use one of the -@code{scm_any_to_*} functions. They will coerce lists and vectors to -the given type of uniform vector. Alternatively, you can write two -versions of your code: one that is fast and works only with uniform -numeric vectors, and one that works with any kind of vector but is -slower. - -One set of the procedures listed below is a generic one: it works with -all types of uniform numeric vectors. In addition to that, there is a -set of procedures for each type that only works with that type. Unless -you really need to the generality of the first set, it is best to use -the more specific functions. They might not be that much faster, but -their use can serve as a kind of declaration and makes it easier to -optimize later on. - -The generic set of procedures uses @code{uniform} in its names, the -specific ones use the tag from the following table. - -@table @nicode -@item u8 -unsigned 8-bit integers - -@item s8 -signed 8-bit integers - -@item u16 -unsigned 16-bit integers - -@item s16 -signed 16-bit integers - -@item u32 -unsigned 32-bit integers - -@item s32 -signed 32-bit integers - -@item u64 -unsigned 64-bit integers - -@item s64 -signed 64-bit integers - -@item f32 -the C type @code{float} - -@item f64 -the C type @code{double} - -@item c32 -complex numbers in rectangular form with the real and imaginary part -being a @code{float} - -@item c64 -complex numbers in rectangular form with the real and imaginary part -being a @code{double} - -@end table - -The external representation (ie.@: read syntax) for these vectors is -similar to normal Scheme vectors, but with an additional tag from the -table above indicating the vector's type. For example, - -@lisp -#u16(1 2 3) -#f64(3.1415 2.71) -@end lisp - -Note that the read syntax for floating-point here conflicts with -@code{#f} for false. In Standard Scheme one can write @code{(1 #f3)} -for a three element list @code{(1 #f 3)}, but for Guile @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. - -@deffn {Scheme Procedure} uniform-vector? obj -@deffnx {Scheme Procedure} u8vector? obj -@deffnx {Scheme Procedure} s8vector? obj -@deffnx {Scheme Procedure} u16vector? obj -@deffnx {Scheme Procedure} s16vector? obj -@deffnx {Scheme Procedure} u32vector? obj -@deffnx {Scheme Procedure} s32vector? obj -@deffnx {Scheme Procedure} u64vector? obj -@deffnx {Scheme Procedure} s64vector? obj -@deffnx {Scheme Procedure} f32vector? obj -@deffnx {Scheme Procedure} f64vector? obj -@deffnx {Scheme Procedure} c32vector? obj -@deffnx {Scheme Procedure} c64vector? obj -@deffnx {C Function} scm_uniform_vector_p (obj) -@deffnx {C Function} scm_u8vector_p (obj) -@deffnx {C Function} scm_s8vector_p (obj) -@deffnx {C Function} scm_u16vector_p (obj) -@deffnx {C Function} scm_s16vector_p (obj) -@deffnx {C Function} scm_u32vector_p (obj) -@deffnx {C Function} scm_s32vector_p (obj) -@deffnx {C Function} scm_u64vector_p (obj) -@deffnx {C Function} scm_s64vector_p (obj) -@deffnx {C Function} scm_f32vector_p (obj) -@deffnx {C Function} scm_f64vector_p (obj) -@deffnx {C Function} scm_c32vector_p (obj) -@deffnx {C Function} scm_c64vector_p (obj) -Return @code{#t} if @var{obj} is a homogeneous numeric vector of the -indicated type. -@end deffn - -@deffn {Scheme Procedure} make-u8vector n [value] -@deffnx {Scheme Procedure} make-s8vector n [value] -@deffnx {Scheme Procedure} make-u16vector n [value] -@deffnx {Scheme Procedure} make-s16vector n [value] -@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] -@deffnx {Scheme Procedure} make-c32vector n [value] -@deffnx {Scheme Procedure} make-c64vector n [value] -@deffnx {C Function} scm_make_u8vector n [value] -@deffnx {C Function} scm_make_s8vector n [value] -@deffnx {C Function} scm_make_u16vector n [value] -@deffnx {C Function} scm_make_s16vector n [value] -@deffnx {C Function} scm_make_u32vector n [value] -@deffnx {C Function} scm_make_s32vector n [value] -@deffnx {C Function} scm_make_u64vector n [value] -@deffnx {C Function} scm_make_s64vector n [value] -@deffnx {C Function} scm_make_f32vector n [value] -@deffnx {C Function} scm_make_f64vector n [value] -@deffnx {C Function} scm_make_c32vector n [value] -@deffnx {C Function} scm_make_c64vector 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 - -@deffn {Scheme Procedure} u8vector value @dots{} -@deffnx {Scheme Procedure} s8vector value @dots{} -@deffnx {Scheme Procedure} u16vector value @dots{} -@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{} -@deffnx {Scheme Procedure} c32vector value @dots{} -@deffnx {Scheme Procedure} c64vector value @dots{} -@deffnx {C Function} scm_u8vector (values) -@deffnx {C Function} scm_s8vector (values) -@deffnx {C Function} scm_u16vector (values) -@deffnx {C Function} scm_s16vector (values) -@deffnx {C Function} scm_u32vector (values) -@deffnx {C Function} scm_s32vector (values) -@deffnx {C Function} scm_u64vector (values) -@deffnx {C Function} scm_s64vector (values) -@deffnx {C Function} scm_f32vector (values) -@deffnx {C Function} scm_f64vector (values) -@deffnx {C Function} scm_c32vector (values) -@deffnx {C Function} scm_c64vector (values) -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 - -@deffn {Scheme Procedure} uniform-vector-length vec -@deffnx {Scheme Procedure} u8vector-length vec -@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 -@deffnx {Scheme Procedure} c32vector-length vec -@deffnx {Scheme Procedure} c64vector-length vec -@deffnx {C Function} scm_uniform_vector_length (vec) -@deffnx {C Function} scm_u8vector_length (vec) -@deffnx {C Function} scm_s8vector_length (vec) -@deffnx {C Function} scm_u16vector_length (vec) -@deffnx {C Function} scm_s16vector_length (vec) -@deffnx {C Function} scm_u32vector_length (vec) -@deffnx {C Function} scm_s32vector_length (vec) -@deffnx {C Function} scm_u64vector_length (vec) -@deffnx {C Function} scm_s64vector_length (vec) -@deffnx {C Function} scm_f32vector_length (vec) -@deffnx {C Function} scm_f64vector_length (vec) -@deffnx {C Function} scm_c32vector_length (vec) -@deffnx {C Function} scm_c64vector_length (vec) -Return the number of elements in @var{vec}. -@end deffn - -@deffn {Scheme Procedure} uniform-vector-ref vec i -@deffnx {Scheme Procedure} u8vector-ref vec i -@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 -@deffnx {Scheme Procedure} c32vector-ref vec i -@deffnx {Scheme Procedure} c64vector-ref vec i -@deffnx {C Function} scm_uniform_vector_ref (vec i) -@deffnx {C Function} scm_u8vector_ref (vec i) -@deffnx {C Function} scm_s8vector_ref (vec i) -@deffnx {C Function} scm_u16vector_ref (vec i) -@deffnx {C Function} scm_s16vector_ref (vec i) -@deffnx {C Function} scm_u32vector_ref (vec i) -@deffnx {C Function} scm_s32vector_ref (vec i) -@deffnx {C Function} scm_u64vector_ref (vec i) -@deffnx {C Function} scm_s64vector_ref (vec i) -@deffnx {C Function} scm_f32vector_ref (vec i) -@deffnx {C Function} scm_f64vector_ref (vec i) -@deffnx {C Function} scm_c32vector_ref (vec i) -@deffnx {C Function} scm_c64vector_ref (vec i) -Return the element at index @var{i} in @var{vec}. The first element -in @var{vec} is index 0. -@end deffn - -@deffn {Scheme Procedure} uniform-vector-set! vec i value -@deffnx {Scheme Procedure} u8vector-set! vec i value -@deffnx {Scheme Procedure} s8vector-set! vec i value -@deffnx {Scheme Procedure} u16vector-set! vec i value -@deffnx {Scheme Procedure} s16vector-set! vec i value -@deffnx {Scheme Procedure} u32vector-set! vec i value -@deffnx {Scheme Procedure} s32vector-set! vec i value -@deffnx {Scheme Procedure} u64vector-set! vec i value -@deffnx {Scheme Procedure} s64vector-set! vec i value -@deffnx {Scheme Procedure} f32vector-set! vec i value -@deffnx {Scheme Procedure} f64vector-set! vec i value -@deffnx {Scheme Procedure} c32vector-set! vec i value -@deffnx {Scheme Procedure} c64vector-set! vec i value -@deffnx {C Function} scm_uniform_vector_set_x (vec i value) -@deffnx {C Function} scm_u8vector_set_x (vec i value) -@deffnx {C Function} scm_s8vector_set_x (vec i value) -@deffnx {C Function} scm_u16vector_set_x (vec i value) -@deffnx {C Function} scm_s16vector_set_x (vec i value) -@deffnx {C Function} scm_u32vector_set_x (vec i value) -@deffnx {C Function} scm_s32vector_set_x (vec i value) -@deffnx {C Function} scm_u64vector_set_x (vec i value) -@deffnx {C Function} scm_s64vector_set_x (vec i value) -@deffnx {C Function} scm_f32vector_set_x (vec i value) -@deffnx {C Function} scm_f64vector_set_x (vec i value) -@deffnx {C Function} scm_c32vector_set_x (vec i value) -@deffnx {C Function} scm_c64vector_set_x (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 - -@deffn {Scheme Procedure} uniform-vector->list vec -@deffnx {Scheme Procedure} u8vector->list vec -@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 -@deffnx {Scheme Procedure} c32vector->list vec -@deffnx {Scheme Procedure} c64vector->list vec -@deffnx {C Function} scm_uniform_vector_to_list (vec) -@deffnx {C Function} scm_u8vector_to_list (vec) -@deffnx {C Function} scm_s8vector_to_list (vec) -@deffnx {C Function} scm_u16vector_to_list (vec) -@deffnx {C Function} scm_s16vector_to_list (vec) -@deffnx {C Function} scm_u32vector_to_list (vec) -@deffnx {C Function} scm_s32vector_to_list (vec) -@deffnx {C Function} scm_u64vector_to_list (vec) -@deffnx {C Function} scm_s64vector_to_list (vec) -@deffnx {C Function} scm_f32vector_to_list (vec) -@deffnx {C Function} scm_f64vector_to_list (vec) -@deffnx {C Function} scm_c32vector_to_list (vec) -@deffnx {C Function} scm_c64vector_to_list (vec) -Return a newly allocated list holding all elements of @var{vec}. -@end deffn - -@deffn {Scheme Procedure} list->u8vector lst -@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 -@deffnx {Scheme Procedure} list->c32vector lst -@deffnx {Scheme Procedure} list->c64vector lst -@deffnx {C Function} scm_list_to_u8vector (lst) -@deffnx {C Function} scm_list_to_s8vector (lst) -@deffnx {C Function} scm_list_to_u16vector (lst) -@deffnx {C Function} scm_list_to_s16vector (lst) -@deffnx {C Function} scm_list_to_u32vector (lst) -@deffnx {C Function} scm_list_to_s32vector (lst) -@deffnx {C Function} scm_list_to_u64vector (lst) -@deffnx {C Function} scm_list_to_s64vector (lst) -@deffnx {C Function} scm_list_to_f32vector (lst) -@deffnx {C Function} scm_list_to_f64vector (lst) -@deffnx {C Function} scm_list_to_c32vector (lst) -@deffnx {C Function} scm_list_to_c64vector (lst) -Return a newly allocated homogeneous numeric vector of the indicated type, -initialized with the elements of the list @var{lst}. -@end deffn - -@deffn {Scheme Procedure} any->u8vector obj -@deffnx {Scheme Procedure} any->s8vector obj -@deffnx {Scheme Procedure} any->u16vector obj -@deffnx {Scheme Procedure} any->s16vector obj -@deffnx {Scheme Procedure} any->u32vector obj -@deffnx {Scheme Procedure} any->s32vector obj -@deffnx {Scheme Procedure} any->u64vector obj -@deffnx {Scheme Procedure} any->s64vector obj -@deffnx {Scheme Procedure} any->f32vector obj -@deffnx {Scheme Procedure} any->f64vector obj -@deffnx {Scheme Procedure} any->c32vector obj -@deffnx {Scheme Procedure} any->c64vector obj -@deffnx {C Function} scm_any_to_u8vector (obj) -@deffnx {C Function} scm_any_to_s8vector (obj) -@deffnx {C Function} scm_any_to_u16vector (obj) -@deffnx {C Function} scm_any_to_s16vector (obj) -@deffnx {C Function} scm_any_to_u32vector (obj) -@deffnx {C Function} scm_any_to_s32vector (obj) -@deffnx {C Function} scm_any_to_u64vector (obj) -@deffnx {C Function} scm_any_to_s64vector (obj) -@deffnx {C Function} scm_any_to_f32vector (obj) -@deffnx {C Function} scm_any_to_f64vector (obj) -@deffnx {C Function} scm_any_to_c32vector (obj) -@deffnx {C Function} scm_any_to_c64vector (obj) -Return a (maybe newly allocated) uniform numeric vector of the indicated -type, initialized with the elements of @var{obj}, which must be a list, -a vector, or a uniform vector. When @var{obj} is already a suitable -uniform numeric vector, it is returned unchanged. -@end deffn - -@deftypefn {C Function} int scm_is_uniform_vector (SCM uvec) -Return non-zero when @var{uvec} is a uniform numeric vector, zero -otherwise. -@end deftypefn - -@deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len) -@deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len) -@deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len) -@deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len) -@deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len) -Return a new uniform numeric vector of the indicated type and length -that uses the memory pointed to by @var{data} to store its elements. -This memory will eventually be freed with @code{free}. The argument -@var{len} specifies the number of elements in @var{data}, not its size -in bytes. - -The @code{c32} and @code{c64} variants take a pointer to a C array of -@code{float}s or @code{double}s. The real parts of the complex numbers -are at even indices in that array, the corresponding imaginary parts are -at the following odd index. -@end deftypefn - -@deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec) -Return the number of elements of @var{uvec} as a @code{size_t}. -@end deftypefn - -@deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const float *} scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but -returns a pointer to the elements of a uniform numeric vector of the -indicated kind. -@end deftypefn - -@deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {float *} scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -@deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) -Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from -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-array-read! ura [port_or_fd [start [end]]] -@deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end] -@deffnx {C Function} scm_uniform_array_read_x (ura, port_or_fd, start, end) -Attempt to read all elements of @var{ura}, in lexicographic order, as -binary objects from @var{port-or-fdes}. -If an end of file is encountered, -the objects up to that point are put into @var{ura} -(starting at the beginning) and the remainder of the array is -unchanged. - -The optional arguments @var{start} and @var{end} allow -a specified region of a vector (or linearized array) to be read, -leaving the remainder of the vector unchanged. - -@code{uniform-array-read!} returns the number of objects read. -@var{port-or-fdes} may be omitted, in which case it defaults to the value -returned by @code{(current-input-port)}. -@end deffn - -@deffn {Scheme Procedure} uniform-vector-write uvec [port_or_fd [start [end]]] -@deffnx {C Function} scm_uniform_vector_write (uvec, port_or_fd, start, end) -Write the elements of @var{uvec} as raw bytes to -@var{port-or-fdes}, in the host byte order. - -The optional arguments @var{start} (inclusive) -and @var{end} (exclusive) allow -a specified region to be written. - -When @var{port-or-fdes} is a port, all specified elements -of @var{uvec} are attempted to be written, potentially blocking -while waiting for more room. -When @var{port-or-fd} is an integer, a single call to -write(2) is made. - -An error is signalled when the last element has only -been partially written in the single call to write(2). - -The number of objects actually written is returned. -@var{port-or-fdes} may be -omitted, in which case it defaults to the value returned by -@code{(current-output-port)}. -@end deffn +sizes. @xref{SRFI-4}, for more information. +For many purposes, bytevectors work just as well as uniform vectors, and have +the advantage that they integrate well with binary input and output. +@xref{Bytevectors}, for more information on bytevectors. @node Bit Vectors @subsection Bit Vectors diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 8e797acc3..bcde697c4 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -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, 2009 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -3942,6 +3942,7 @@ R6RS (@pxref{R6RS I/O Ports}). * Bytevectors as Floats:: Interpreting bytes as real numbers. * Bytevectors as Strings:: Interpreting bytes as Unicode strings. * Bytevectors as Generalized Vectors:: Guile extension to the bytevector API. +* Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4. @end menu @node Bytevector Endianness @@ -4338,6 +4339,13 @@ these APIs, bytes are accessed one at a time as 8-bit unsigned integers: @end example +@node Bytevectors as Uniform Vectors +@subsubsection Accessing Bytevectors with the SRFI-4 API + +Bytevectors may also be accessed with the SRFI-4 API. @xref{SRFI-4 and +Bytevectors}, for more information. + + @node Regular Expressions @subsection Regular Expressions @tpindex Regular expressions diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 043490ddb..d3eafc5c0 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -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, 2009 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1293,8 +1293,539 @@ from separate @code{and} and @code{let*}, or from @code{cond} with @subsection SRFI-4 - Homogeneous numeric vector datatypes @cindex SRFI-4 -The SRFI-4 procedures and data types are always available, @xref{Uniform -Numeric Vectors}. +SRFI-4 provides an interface to uniform numeric vectors: vectors whose elements +are all of a single numeric type. Guile offers uniform numeric vectors for +signed and unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of +floating point values, and, as an extension to SRFI-4, complex floating-point +numbers of these two sizes. + +The standard SRFI-4 procedures and data types may be included via loading the +appropriate module: + +@example +(use-modules (srfi srfi-4)) +@end example + +This module is currently a part of the default Guile environment, but it is a +good practice to explicitly import the module. In the future, using SRFI-4 +procedures without importing the SRFI-4 module will cause a deprecation message +to be printed. (Of course, one may call the C functions at any time. Would that +C had modules!) + +@menu +* SRFI-4 Overview:: The warp and weft of uniform numeric vectors. +* SRFI-4 API:: Uniform vectors, from Scheme and from C. +* SRFI-4 Generic Operations:: The general, operating on the specific. +* SRFI-4 and Bytevectors:: SRFI-4 vectors are backed by bytevectors. +* SRFI-4 Extensions:: Guile-specific extensions to the standard. +@end menu + +@node SRFI-4 Overview +@subsubsection SRFI-4 - Overview + +Uniform numeric vectors can be useful since they consume less memory +than the non-uniform, general vectors. Also, since the types they can +store correspond directly to C types, it is easier to work with them +efficiently on a low level. Consider image processing as an example, +where you want to apply a filter to some image. While you could store +the pixels of an image in a general vector and write a general +convolution function, things are much more efficient with uniform +vectors: the convolution function knows that all pixels are unsigned +8-bit values (say), and can use a very tight inner loop. + +This is implemented in Scheme by having the compiler notice calls to the SRFI-4 +accessors, and inline them to appropriate compiled code. From C you have access +to the raw array; functions for efficiently working with uniform numeric vectors +from C are listed at the end of this section. + +Uniform numeric vectors are the special case of one dimensional uniform +numeric arrays. + +There are 12 standard kinds of uniform numeric vectors, and they all have their +own complement of constructors, accessors, and so on. Procedures that operate on +a specific kind of uniform numeric vector have a ``tag'' in their name, +indicating the element type. + +@table @nicode +@item u8 +unsigned 8-bit integers + +@item s8 +signed 8-bit integers + +@item u16 +unsigned 16-bit integers + +@item s16 +signed 16-bit integers + +@item u32 +unsigned 32-bit integers + +@item s32 +signed 32-bit integers + +@item u64 +unsigned 64-bit integers + +@item s64 +signed 64-bit integers + +@item f32 +the C type @code{float} + +@item f64 +the C type @code{double} + +@end table + +In addition, Guile supports uniform arrays of complex numbers, with the +nonstandard tags: + +@table @nicode + +@item c32 +complex numbers in rectangular form with the real and imaginary part +being a @code{float} + +@item c64 +complex numbers in rectangular form with the real and imaginary part +being a @code{double} + +@end table + +The external representation (ie.@: read syntax) for these vectors is +similar to normal Scheme vectors, but with an additional tag from the +tables above indicating the vector's type. For example, + +@lisp +#u16(1 2 3) +#f64(3.1415 2.71) +@end lisp + +Note that the read syntax for floating-point here conflicts with +@code{#f} for false. In Standard Scheme one can write @code{(1 #f3)} +for a three element list @code{(1 #f 3)}, but for Guile @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. + + +@node SRFI-4 API +@subsubsection SRFI-4 - API + +Note that the @nicode{c32} and @nicode{c64} functions are only available from +@nicode{(srfi srfi-4 gnu)}. + +@deffn {Scheme Procedure} u8vector? obj +@deffnx {Scheme Procedure} s8vector? obj +@deffnx {Scheme Procedure} u16vector? obj +@deffnx {Scheme Procedure} s16vector? obj +@deffnx {Scheme Procedure} u32vector? obj +@deffnx {Scheme Procedure} s32vector? obj +@deffnx {Scheme Procedure} u64vector? obj +@deffnx {Scheme Procedure} s64vector? obj +@deffnx {Scheme Procedure} f32vector? obj +@deffnx {Scheme Procedure} f64vector? obj +@deffnx {Scheme Procedure} c32vector? obj +@deffnx {Scheme Procedure} c64vector? obj +@deffnx {C Function} scm_u8vector_p (obj) +@deffnx {C Function} scm_s8vector_p (obj) +@deffnx {C Function} scm_u16vector_p (obj) +@deffnx {C Function} scm_s16vector_p (obj) +@deffnx {C Function} scm_u32vector_p (obj) +@deffnx {C Function} scm_s32vector_p (obj) +@deffnx {C Function} scm_u64vector_p (obj) +@deffnx {C Function} scm_s64vector_p (obj) +@deffnx {C Function} scm_f32vector_p (obj) +@deffnx {C Function} scm_f64vector_p (obj) +@deffnx {C Function} scm_c32vector_p (obj) +@deffnx {C Function} scm_c64vector_p (obj) +Return @code{#t} if @var{obj} is a homogeneous numeric vector of the +indicated type. +@end deffn + +@deffn {Scheme Procedure} make-u8vector n [value] +@deffnx {Scheme Procedure} make-s8vector n [value] +@deffnx {Scheme Procedure} make-u16vector n [value] +@deffnx {Scheme Procedure} make-s16vector n [value] +@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] +@deffnx {Scheme Procedure} make-c32vector n [value] +@deffnx {Scheme Procedure} make-c64vector n [value] +@deffnx {C Function} scm_make_u8vector n [value] +@deffnx {C Function} scm_make_s8vector n [value] +@deffnx {C Function} scm_make_u16vector n [value] +@deffnx {C Function} scm_make_s16vector n [value] +@deffnx {C Function} scm_make_u32vector n [value] +@deffnx {C Function} scm_make_s32vector n [value] +@deffnx {C Function} scm_make_u64vector n [value] +@deffnx {C Function} scm_make_s64vector n [value] +@deffnx {C Function} scm_make_f32vector n [value] +@deffnx {C Function} scm_make_f64vector n [value] +@deffnx {C Function} scm_make_c32vector n [value] +@deffnx {C Function} scm_make_c64vector 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 + +@deffn {Scheme Procedure} u8vector value @dots{} +@deffnx {Scheme Procedure} s8vector value @dots{} +@deffnx {Scheme Procedure} u16vector value @dots{} +@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{} +@deffnx {Scheme Procedure} c32vector value @dots{} +@deffnx {Scheme Procedure} c64vector value @dots{} +@deffnx {C Function} scm_u8vector (values) +@deffnx {C Function} scm_s8vector (values) +@deffnx {C Function} scm_u16vector (values) +@deffnx {C Function} scm_s16vector (values) +@deffnx {C Function} scm_u32vector (values) +@deffnx {C Function} scm_s32vector (values) +@deffnx {C Function} scm_u64vector (values) +@deffnx {C Function} scm_s64vector (values) +@deffnx {C Function} scm_f32vector (values) +@deffnx {C Function} scm_f64vector (values) +@deffnx {C Function} scm_c32vector (values) +@deffnx {C Function} scm_c64vector (values) +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 + +@deffn {Scheme Procedure} u8vector-length vec +@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 +@deffnx {Scheme Procedure} c32vector-length vec +@deffnx {Scheme Procedure} c64vector-length vec +@deffnx {C Function} scm_u8vector_length (vec) +@deffnx {C Function} scm_s8vector_length (vec) +@deffnx {C Function} scm_u16vector_length (vec) +@deffnx {C Function} scm_s16vector_length (vec) +@deffnx {C Function} scm_u32vector_length (vec) +@deffnx {C Function} scm_s32vector_length (vec) +@deffnx {C Function} scm_u64vector_length (vec) +@deffnx {C Function} scm_s64vector_length (vec) +@deffnx {C Function} scm_f32vector_length (vec) +@deffnx {C Function} scm_f64vector_length (vec) +@deffnx {C Function} scm_c32vector_length (vec) +@deffnx {C Function} scm_c64vector_length (vec) +Return the number of elements in @var{vec}. +@end deffn + +@deffn {Scheme Procedure} u8vector-ref vec i +@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 +@deffnx {Scheme Procedure} c32vector-ref vec i +@deffnx {Scheme Procedure} c64vector-ref vec i +@deffnx {C Function} scm_u8vector_ref (vec i) +@deffnx {C Function} scm_s8vector_ref (vec i) +@deffnx {C Function} scm_u16vector_ref (vec i) +@deffnx {C Function} scm_s16vector_ref (vec i) +@deffnx {C Function} scm_u32vector_ref (vec i) +@deffnx {C Function} scm_s32vector_ref (vec i) +@deffnx {C Function} scm_u64vector_ref (vec i) +@deffnx {C Function} scm_s64vector_ref (vec i) +@deffnx {C Function} scm_f32vector_ref (vec i) +@deffnx {C Function} scm_f64vector_ref (vec i) +@deffnx {C Function} scm_c32vector_ref (vec i) +@deffnx {C Function} scm_c64vector_ref (vec i) +Return the element at index @var{i} in @var{vec}. The first element +in @var{vec} is index 0. +@end deffn + +@deffn {Scheme Procedure} u8vector-set! vec i value +@deffnx {Scheme Procedure} s8vector-set! vec i value +@deffnx {Scheme Procedure} u16vector-set! vec i value +@deffnx {Scheme Procedure} s16vector-set! vec i value +@deffnx {Scheme Procedure} u32vector-set! vec i value +@deffnx {Scheme Procedure} s32vector-set! vec i value +@deffnx {Scheme Procedure} u64vector-set! vec i value +@deffnx {Scheme Procedure} s64vector-set! vec i value +@deffnx {Scheme Procedure} f32vector-set! vec i value +@deffnx {Scheme Procedure} f64vector-set! vec i value +@deffnx {Scheme Procedure} c32vector-set! vec i value +@deffnx {Scheme Procedure} c64vector-set! vec i value +@deffnx {C Function} scm_u8vector_set_x (vec i value) +@deffnx {C Function} scm_s8vector_set_x (vec i value) +@deffnx {C Function} scm_u16vector_set_x (vec i value) +@deffnx {C Function} scm_s16vector_set_x (vec i value) +@deffnx {C Function} scm_u32vector_set_x (vec i value) +@deffnx {C Function} scm_s32vector_set_x (vec i value) +@deffnx {C Function} scm_u64vector_set_x (vec i value) +@deffnx {C Function} scm_s64vector_set_x (vec i value) +@deffnx {C Function} scm_f32vector_set_x (vec i value) +@deffnx {C Function} scm_f64vector_set_x (vec i value) +@deffnx {C Function} scm_c32vector_set_x (vec i value) +@deffnx {C Function} scm_c64vector_set_x (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 + +@deffn {Scheme Procedure} u8vector->list vec +@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 +@deffnx {Scheme Procedure} c32vector->list vec +@deffnx {Scheme Procedure} c64vector->list vec +@deffnx {C Function} scm_u8vector_to_list (vec) +@deffnx {C Function} scm_s8vector_to_list (vec) +@deffnx {C Function} scm_u16vector_to_list (vec) +@deffnx {C Function} scm_s16vector_to_list (vec) +@deffnx {C Function} scm_u32vector_to_list (vec) +@deffnx {C Function} scm_s32vector_to_list (vec) +@deffnx {C Function} scm_u64vector_to_list (vec) +@deffnx {C Function} scm_s64vector_to_list (vec) +@deffnx {C Function} scm_f32vector_to_list (vec) +@deffnx {C Function} scm_f64vector_to_list (vec) +@deffnx {C Function} scm_c32vector_to_list (vec) +@deffnx {C Function} scm_c64vector_to_list (vec) +Return a newly allocated list holding all elements of @var{vec}. +@end deffn + +@deffn {Scheme Procedure} list->u8vector lst +@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 +@deffnx {Scheme Procedure} list->c32vector lst +@deffnx {Scheme Procedure} list->c64vector lst +@deffnx {C Function} scm_list_to_u8vector (lst) +@deffnx {C Function} scm_list_to_s8vector (lst) +@deffnx {C Function} scm_list_to_u16vector (lst) +@deffnx {C Function} scm_list_to_s16vector (lst) +@deffnx {C Function} scm_list_to_u32vector (lst) +@deffnx {C Function} scm_list_to_s32vector (lst) +@deffnx {C Function} scm_list_to_u64vector (lst) +@deffnx {C Function} scm_list_to_s64vector (lst) +@deffnx {C Function} scm_list_to_f32vector (lst) +@deffnx {C Function} scm_list_to_f64vector (lst) +@deffnx {C Function} scm_list_to_c32vector (lst) +@deffnx {C Function} scm_list_to_c64vector (lst) +Return a newly allocated homogeneous numeric vector of the indicated type, +initialized with the elements of the list @var{lst}. +@end deffn + +@deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_s16vector (const scm_t_int16 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_s32vector (const scm_t_int32 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len) +@deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len) +@deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len) +@deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len) +@deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len) +Return a new uniform numeric vector of the indicated type and length +that uses the memory pointed to by @var{data} to store its elements. +This memory will eventually be freed with @code{free}. The argument +@var{len} specifies the number of elements in @var{data}, not its size +in bytes. + +The @code{c32} and @code{c64} variants take a pointer to a C array of +@code{float}s or @code{double}s. The real parts of the complex numbers +are at even indices in that array, the corresponding imaginary parts are +at the following odd index. +@end deftypefn + +@deftypefn {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const float *} scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but +returns a pointer to the elements of a uniform numeric vector of the +indicated kind. +@end deftypefn + +@deftypefn {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {float *} scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from +C}), but returns a pointer to the elements of a uniform numeric vector +of the indicated kind. +@end deftypefn + +@node SRFI-4 Generic Operations +@subsubsection SRFI-4 - Generic operations + +Guile also provides procedures that operate on all types of uniform numeric +vectors. In what is probably a bug, these procedures are currently available in +the default environment as well; however prudent hackers will make sure to +import @code{(srfi srfi-4 gnu)} before using these. + +@deftypefn {C Function} int scm_is_uniform_vector (SCM uvec) +Return non-zero when @var{uvec} is a uniform numeric vector, zero +otherwise. +@end deftypefn + +@deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec) +Return the number of elements of @var{uvec} as a @code{size_t}. +@end deftypefn + +@deffn {Scheme Procedure} uniform-vector? obj +@deffnx {C Function} scm_uniform_vector_p (obj) +Return @code{#t} if @var{obj} is a homogeneous numeric vector of the +indicated type. +@end deffn + +@deffn {Scheme Procedure} uniform-vector-length vec +@deffnx {C Function} scm_uniform_vector_length (vec) +Return the number of elements in @var{vec}. +@end deffn + +@deffn {Scheme Procedure} uniform-vector-ref vec i +@deffnx {C Function} scm_uniform_vector_ref (vec i) +Return the element at index @var{i} in @var{vec}. The first element +in @var{vec} is index 0. +@end deffn + +@deffn {Scheme Procedure} uniform-vector-set! vec i value +@deffnx {C Function} scm_uniform_vector_set_x (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 + +@deffn {Scheme Procedure} uniform-vector->list vec +@deffnx {C Function} scm_uniform_vector_to_list (vec) +Return a newly allocated list holding all elements of @var{vec}. +@end deffn + +@deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but +returns a pointer to the elements of a uniform numeric vector. +@end deftypefn + +@deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from +C}), but returns a pointer to the elements of a uniform numeric vector. +@end deftypefn + +Unless you really need to the limited generality of these functions, it is best +to use the type-specific functions, or the generalized vector accessors. + +@node SRFI-4 and Bytevectors +@subsubsection SRFI-4 - Relation to bytevectors + +Guile implements SRFI-4 vectors using bytevectors (@pxref{Bytevectors}). Often +when you have a numeric vector, you end up wanting to write its bytes somewhere, +or have access to the underlying bytes, or read in bytes from somewhere else. +Bytevectors are very good at this sort of thing. But the SRFI-4 APIs are nicer +to use when doing number-crunching, because they are addressed by element and +not by byte. + +So as a compromise, Guile allows all bytevector functions to operate on numeric +vectors. They address the underlying bytes in the native endianness, as one +would expect. + +Following the same reasoning, that it's just bytes underneath, Guile also allows +uniform vectors of a given type to be accessed as if they were of any type. One +can fill a @nicode{u32vector}, and access its elements with +@nicode{u8vector-ref}. One can use @nicode{f64vector-ref} on bytevectors. It's +all the same to Guile. + +In this way, uniform numeric vectors may be written to and read from +input/output ports using the procedures that operate on bytevectors. + +@xref{Bytevectors}, for more information. + + +@node SRFI-4 Extensions +@subsubsection SRFI-4 - Guile extensions + +Guile defines some useful extensions to SRFI-4, which are not available in the +default Guile environment. They may be imported by loading the extensions +module: + +@example +(use-modules (srfi srfi-4 gnu)) +@end example + +@deffn {Scheme Procedure} any->u8vector obj +@deffnx {Scheme Procedure} any->s8vector obj +@deffnx {Scheme Procedure} any->u16vector obj +@deffnx {Scheme Procedure} any->s16vector obj +@deffnx {Scheme Procedure} any->u32vector obj +@deffnx {Scheme Procedure} any->s32vector obj +@deffnx {Scheme Procedure} any->u64vector obj +@deffnx {Scheme Procedure} any->s64vector obj +@deffnx {Scheme Procedure} any->f32vector obj +@deffnx {Scheme Procedure} any->f64vector obj +@deffnx {Scheme Procedure} any->c32vector obj +@deffnx {Scheme Procedure} any->c64vector obj +@deffnx {C Function} scm_any_to_u8vector (obj) +@deffnx {C Function} scm_any_to_s8vector (obj) +@deffnx {C Function} scm_any_to_u16vector (obj) +@deffnx {C Function} scm_any_to_s16vector (obj) +@deffnx {C Function} scm_any_to_u32vector (obj) +@deffnx {C Function} scm_any_to_s32vector (obj) +@deffnx {C Function} scm_any_to_u64vector (obj) +@deffnx {C Function} scm_any_to_s64vector (obj) +@deffnx {C Function} scm_any_to_f32vector (obj) +@deffnx {C Function} scm_any_to_f64vector (obj) +@deffnx {C Function} scm_any_to_c32vector (obj) +@deffnx {C Function} scm_any_to_c64vector (obj) +Return a (maybe newly allocated) uniform numeric vector of the indicated +type, initialized with the elements of @var{obj}, which must be a list, +a vector, or a uniform vector. When @var{obj} is already a suitable +uniform numeric vector, it is returned unchanged. +@end deffn + @node SRFI-6 @subsection SRFI-6 - Basic String Ports