mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-06-29 14:30:34 +02:00
Merge remote-tracking branch 'origin/stable-2.0'
Conflicts: libguile/array-handle.c libguile/deprecated.h libguile/inline.c libguile/inline.h module/ice-9/deprecated.scm module/language/tree-il/peval.scm
This commit is contained in:
Andy Wingo
commit
9b977c836b
36 changed files with 873 additions and 384 deletions
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
|
||||
@c Free Software Foundation, Inc.
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
|
||||
@c 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
|
||||
@c See the file guile.texi for copying conditions.
|
||||
|
||||
@node Simple Data Types
|
||||
|
|
@ -414,6 +414,7 @@ function will always succeed and will always return an exact number.
|
|||
@deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x)
|
||||
@deftypefnx {C Function} size_t scm_to_size_t (SCM x)
|
||||
@deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x)
|
||||
@deftypefnx {C Function} scm_t_ptrdiff scm_to_ptrdiff_t (SCM x)
|
||||
@deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x)
|
||||
@deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x)
|
||||
@deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x)
|
||||
|
|
@ -447,6 +448,7 @@ the corresponding types are.
|
|||
@deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x)
|
||||
@deftypefnx {C Function} SCM scm_from_size_t (size_t x)
|
||||
@deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x)
|
||||
@deftypefnx {C Function} SCM scm_from_ptrdiff_t (scm_t_ptrdiff x)
|
||||
@deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x)
|
||||
@deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x)
|
||||
@deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x)
|
||||
|
|
@ -4548,7 +4550,7 @@ R6RS (@pxref{R6RS I/O Ports}).
|
|||
* Bytevectors and Integer Lists:: Converting to/from an integer list.
|
||||
* 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 Arrays:: Guile extension to the bytevector API.
|
||||
* Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4.
|
||||
@end menu
|
||||
|
||||
|
|
@ -4934,25 +4936,27 @@ or UTF-32-decoded contents of bytevector @var{utf}. For UTF-16 and UTF-32,
|
|||
it defaults to big endian.
|
||||
@end deffn
|
||||
|
||||
@node Bytevectors as Generalized Vectors
|
||||
@subsubsection Accessing Bytevectors with the Generalized Vector API
|
||||
@node Bytevectors as Arrays
|
||||
@subsubsection Accessing Bytevectors with the Array API
|
||||
|
||||
As an extension to the R6RS, Guile allows bytevectors to be manipulated
|
||||
with the @dfn{generalized vector} procedures (@pxref{Generalized
|
||||
Vectors}). This also allows bytevectors to be accessed using the
|
||||
generic @dfn{array} procedures (@pxref{Array Procedures}). When using
|
||||
these APIs, bytes are accessed one at a time as 8-bit unsigned integers:
|
||||
with the @dfn{array} procedures (@pxref{Arrays}). When using these
|
||||
APIs, bytes are accessed one at a time as 8-bit unsigned integers:
|
||||
|
||||
@example
|
||||
(define bv #vu8(0 1 2 3))
|
||||
|
||||
(generalized-vector? bv)
|
||||
(array? bv)
|
||||
@result{} #t
|
||||
|
||||
(generalized-vector-ref bv 2)
|
||||
(array-rank bv)
|
||||
@result{} 1
|
||||
|
||||
(array-ref bv 2)
|
||||
@result{} 2
|
||||
|
||||
(generalized-vector-set! bv 2 77)
|
||||
;; Note the different argument order on array-set!.
|
||||
(array-set! bv 77 2)
|
||||
(array-ref bv 2)
|
||||
@result{} 77
|
||||
|
||||
|
|
|
|||
|
|
@ -489,6 +489,8 @@ platform-dependent size:
|
|||
@defvrx {Scheme Variable} long
|
||||
@defvrx {Scheme Variable} unsigned-long
|
||||
@defvrx {Scheme Variable} size_t
|
||||
@defvrx {Scheme Variable} ssize_t
|
||||
@defvrx {Scheme Variable} ptrdiff_t
|
||||
Values exported by the @code{(system foreign)} module, representing C
|
||||
numeric types. For example, @code{long} may be @code{equal?} to
|
||||
@code{int64} on a 64-bit platform.
|
||||
|
|
@ -801,8 +803,8 @@ int64_t a; uint8_t b; @}}:
|
|||
@end example
|
||||
|
||||
As yet, Guile only has convenience routines to support
|
||||
conventionally-packed structs. But given the @code{bytevector->foreign}
|
||||
and @code{foreign->bytevector} routines, one can create and parse
|
||||
conventionally-packed structs. But given the @code{bytevector->pointer}
|
||||
and @code{pointer->bytevector} routines, one can create and parse
|
||||
tightly packed structs and unions by hand. See the code for
|
||||
@code{(system foreign)} for details.
|
||||
|
||||
|
|
|
|||
|
|
@ -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, 2010, 2011, 2012
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
|
||||
@c Free Software Foundation, Inc.
|
||||
@c See the file guile.texi for copying conditions.
|
||||
|
||||
|
|
@ -1770,8 +1770,8 @@ 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.
|
||||
Unless you really need to the limited generality of these functions, it
|
||||
is best to use the type-specific functions, or the array accessors.
|
||||
|
||||
@node SRFI-4 and Bytevectors
|
||||
@subsubsection SRFI-4 - Relation to bytevectors
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue