summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarius Vollmer <mvo@zagadka.de>2004-11-02 20:16:06 +0000
committerMarius Vollmer <mvo@zagadka.de>2004-11-02 20:16:06 +0000
commit34dedee007ebce9b664abd75b39471334704148b (patch)
treeed6c4209347144d665fcad238bee43dcadad6904
parent5d1015ec8cfcdf3a67592dfc296e180d37bc4d10 (diff)
downloadguile-34dedee007ebce9b664abd75b39471334704148b.tar.gz
More docs.
-rw-r--r--doc/ref/api-compound.texi59
1 files changed, 49 insertions, 10 deletions
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 98ed98993..0df53b604 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -818,9 +818,10 @@ same vector, @code{vector-move-right!} is usually appropriate when
@node Uniform Vectors
@subsection Uniform Vectors
-A uniform vector is a vector elements are all of a single type. Guile
-offers uniform vectors for signed and unsigned 8-bit, 16-bit, 32-bit,
-and 64-bit integers and for two sizes of floating point values.
+A uniform vector is a vector whose elements are all of a single type.
+Guile offers uniform 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
@@ -829,7 +830,7 @@ that the procedures described here do not apply to these two data types.
However, both strings and bit vectors are arrays, @xref{Arrays}.
Uniform vectors are the special case of one-dimensional, uniform,
-zero-origin array.
+zero-origin arrays.
Uniform vectors can be useful since they consume less memory than the
non-uniform, general vectors. Also, since the types they can store
@@ -839,12 +840,18 @@ 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.)
+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 vectors from C are listed at the end of this section.
Procedures similar to the vector procedures (@pxref{Vectors}) are
provided for handling these homogeneous vectors, but they are distinct
-datatypes and the two cannot be inter-mixed.
+datatypes and the two cannot be inter-mixed. If you want to work
+primarily with uniform vectorsd, 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.
One set of these procedures is a generic one: it works with all types of
uniform vectors. In addition to that, there is a set of procedures for
@@ -853,9 +860,6 @@ 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.
-(Functions for efficiently working with uniform vectors from C are
-listed at the end of this section.)
-
The generic set of procedures uses @code{uniform-vector} in its names,
the specific ones use the tag from the following table.
@@ -1151,6 +1155,35 @@ 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 newly allocated homogeneous numeric vector of the indicated
+type, initialized with the elements of @var{obj}, which must be a list,
+a vector, or a uniform vector.
+@end deffn
+
@deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
Return @code{1} when @var{uvec} is a uniform vector, @code{0} otherwise.
@end deftypefn
@@ -1206,6 +1239,12 @@ Finish the access to the elements of a uniform vector, as exlained
above.
@end deftypefn
+@deftypefn {C Function} void scm_frame_uniform_vector_release (SCM uvec)
+Arrange for @code{uniform_vector_release} to be called with @var{uvec}
+when the current frame is unwound, implicitely or explicitely;
+@xref{Frames}.
+@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