diff options
Diffstat (limited to 'doc/ref/api-compound.texi')
-rw-r--r-- | doc/ref/api-compound.texi | 137 |
1 files changed, 51 insertions, 86 deletions
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index be3d65f4e..6dfc5fdc0 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -@c 2007, 2009, 2010, 2011, 2012 Free Software Foundation, Inc. +@c 2007, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node Compound Data Types @@ -22,7 +22,6 @@ values can be looked up within them. * Lists:: Special list functions supported by Guile. * Vectors:: One-dimensional arrays of Scheme objects. * Bit Vectors:: Vectors of bits. -* Generalized Vectors:: Treating all vector-like things uniformly. * Arrays:: Matrices, etc. * VLists:: Vector-like lists. * Record Overview:: Walking through the maze of record APIs. @@ -993,9 +992,8 @@ are displayed as a sequence of @code{0}s and @code{1}s prefixed by #*00000000 @end example -Bit vectors are also generalized vectors, @xref{Generalized -Vectors}, and can thus be used with the array procedures, @xref{Arrays}. -Bit vectors are the special case of one dimensional bit arrays. +Bit vectors are the special case of one dimensional bit arrays, and can +thus be used with the array procedures, @xref{Arrays}. @deffn {Scheme Procedure} bitvector? obj @deffnx {C Function} scm_bitvector_p (obj) @@ -1163,74 +1161,6 @@ Like @code{scm_bitvector_elements}, but the pointer is good for reading and writing. @end deftypefn -@node Generalized Vectors -@subsection Generalized Vectors - -Guile has a number of data types that are generally vector-like: -strings, uniform numeric vectors, bytevectors, bitvectors, and of course -ordinary vectors of arbitrary Scheme values. These types are disjoint: -a Scheme value belongs to at most one of the five types listed above. - -If you want to gloss over this distinction and want to treat all four -types with common code, you can use the procedures in this section. -They work with the @emph{generalized vector} type, which is the union -of the five vector-like types. - -@deffn {Scheme Procedure} generalized-vector? obj -@deffnx {C Function} scm_generalized_vector_p (obj) -Return @code{#t} if @var{obj} is a vector, bytevector, string, -bitvector, or uniform numeric vector. -@end deffn - -@deffn {Scheme Procedure} generalized-vector-length v -@deffnx {C Function} scm_generalized_vector_length (v) -Return the length of the generalized vector @var{v}. -@end deffn - -@deffn {Scheme Procedure} generalized-vector-ref v idx -@deffnx {C Function} scm_generalized_vector_ref (v, idx) -Return the element at index @var{idx} of the -generalized vector @var{v}. -@end deffn - -@deffn {Scheme Procedure} generalized-vector-set! v idx val -@deffnx {C Function} scm_generalized_vector_set_x (v, idx, val) -Set the element at index @var{idx} of the -generalized vector @var{v} to @var{val}. -@end deffn - -@deffn {Scheme Procedure} generalized-vector->list v -@deffnx {C Function} scm_generalized_vector_to_list (v) -Return a new list whose elements are the elements of the -generalized vector @var{v}. -@end deffn - -@deftypefn {C Function} int scm_is_generalized_vector (SCM obj) -Return @code{1} if @var{obj} is a vector, string, -bitvector, or uniform numeric vector; else return @code{0}. -@end deftypefn - -@deftypefn {C Function} size_t scm_c_generalized_vector_length (SCM v) -Return the length of the generalized vector @var{v}. -@end deftypefn - -@deftypefn {C Function} SCM scm_c_generalized_vector_ref (SCM v, size_t idx) -Return the element at index @var{idx} of the generalized vector @var{v}. -@end deftypefn - -@deftypefn {C Function} void scm_c_generalized_vector_set_x (SCM v, size_t idx, SCM val) -Set the element at index @var{idx} of the generalized vector @var{v} -to @var{val}. -@end deftypefn - -@deftypefn {C Function} void scm_generalized_vector_get_handle (SCM v, scm_t_array_handle *handle) -Like @code{scm_array_get_handle} but an error is signalled when @var{v} -is not of rank one. You can use @code{scm_array_handle_ref} and -@code{scm_array_handle_set} to read and write the elements of @var{v}, -or you can use functions like @code{scm_array_handle_<foo>_elements} to -deal with specific types of vectors. -@end deftypefn - @node Arrays @subsection Arrays @tpindex Arrays @@ -1239,13 +1169,13 @@ deal with specific types of vectors. number of dimensions. Each cell can be accessed in constant time by supplying an index for each dimension. -In the current implementation, an array uses a generalized vector for -the actual storage of its elements. Any kind of generalized vector -will do, so you can have arrays of uniform numeric values, arrays of -characters, arrays of bits, and of course, arrays of arbitrary Scheme -values. For example, arrays with an underlying @code{c64vector} might -be nice for digital signal processing, while arrays made from a -@code{u8vector} might be used to hold gray-scale images. +In the current implementation, an array uses a vector of some kind for +the actual storage of its elements. Any kind of vector will do, so you +can have arrays of uniform numeric values, arrays of characters, arrays +of bits, and of course, arrays of arbitrary Scheme values. For example, +arrays with an underlying @code{c64vector} might be nice for digital +signal processing, while arrays made from a @code{u8vector} might be +used to hold gray-scale images. The number of dimensions of an array is called its @dfn{rank}. Thus, a matrix is an array of rank 2, while a vector has rank 1. When @@ -1267,9 +1197,9 @@ matrix with zero columns and 3 rows is different from a matrix with 3 columns and zero rows, which again is different from a vector of length zero. -Generalized vectors, such as strings, uniform numeric vectors, -bytevectors, bit vectors and ordinary vectors, are the special case of -one dimensional arrays. +The array procedures are all polymorphic, treating strings, uniform +numeric vectors, bytevectors, bit vectors and ordinary vectors as one +dimensional arrays. @menu * Array Syntax:: @@ -1462,6 +1392,7 @@ as elements in the list. @end deffn @deffn {Scheme Procedure} array-type array +@deffnx {C Function} scm_array_type (array) Return the type of @var{array}. This is the `vectag' used for printing @var{array} (or @code{#t} for ordinary arrays) and can be used with @code{make-typed-array} to create an array of the same kind @@ -1469,6 +1400,7 @@ as @var{array}. @end deffn @deffn {Scheme Procedure} array-ref array idx @dots{} +@deffnx {C Function} scm_array_ref (array, idxlist) Return the element at @code{(idx @dots{})} in @var{array}. @example @@ -1479,7 +1411,7 @@ Return the element at @code{(idx @dots{})} in @var{array}. @deffn {Scheme Procedure} array-in-bounds? array idx @dots{} @deffnx {C Function} scm_array_in_bounds_p (array, idxlist) -Return @code{#t} if the given index would be acceptable to +Return @code{#t} if the given indices would be acceptable to @code{array-ref}. @example @@ -1520,6 +1452,13 @@ For example, @end example @end deffn +@deffn {Scheme Procedure} array-length array +@deffnx {C Function} scm_array_length (array) +@deffnx {C Function} size_t scm_c_array_length (array) +Return the length of an array: its first dimension. It is an error to +ask for the length of an array of rank 0. +@end deffn + @deffn {Scheme Procedure} array-rank array @deffnx {C Function} scm_array_rank (array) Return the rank of @var{array}. @@ -3796,8 +3735,9 @@ key is not found. #f @end lisp -There is no procedure for calculating the number of key/value-pairs in -a hash table, but @code{hash-fold} can be used for doing exactly that. +Interesting results can be computed by using @code{hash-fold} to work +through each element. This example will count the total number of +elements: @lisp (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h) @@ -3805,6 +3745,24 @@ a hash table, but @code{hash-fold} can be used for doing exactly that. 3 @end lisp +The same thing can be done with the procedure @code{hash-count}, which +can also count the number of elements matching a particular predicate. +For example, count the number of elements with string values: + +@lisp +(hash-count (lambda (key value) (string? value)) h) +@result{} +2 +@end lisp + +Counting all the elements is a simple task using @code{const}: + +@lisp +(hash-count (const #t) h) +@result{} +3 +@end lisp + @node Hash Table Reference @subsubsection Hash Table Reference @@ -4032,6 +3990,13 @@ For example, the following returns a count of how many keys in @end example @end deffn +@deffn {Scheme Procedure} hash-count pred table +@deffnx {C Function} scm_hash_count (pred, table) +Return the number of elements in the given hash @var{table} that cause +@code{(@var{pred} @var{key} @var{value})} to return true. To quickly +determine the total number of elements, use @code{(const #t)} for +@var{pred}. +@end deffn @c Local Variables: @c TeX-master: "guile.texi" |