@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
* 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.
@rnindex list?
@deffn {Scheme Procedure} list? x
@deffnx {C Function} scm_list_p (x)
-Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
+Return @code{#t} if @var{x} is a proper list, else @code{#f}.
@end deffn
The predicate @code{null?} is often used in list-processing code to
@rnindex null?
@deffn {Scheme Procedure} null? x
@deffnx {C Function} scm_null_p (x)
-Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
+Return @code{#t} if @var{x} is the empty list, else @code{#f}.
@end deffn
@deftypefn {C Function} int scm_is_null (SCM x)
@end lisp
@code{append} doesn't modify the given lists, but the return may share
-structure with the final @var{obj}. @code{append!} modifies the
-given lists to form its return.
+structure with the final @var{obj}. @code{append!} is permitted, but
+not required, to modify the given lists to form its return.
For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
of the list operands @var{lst} @dots{} @var{obj}. That @var{lstlst}
@deffnx {C Function} scm_reverse_x (lst, newtail)
Return a list comprising the elements of @var{lst}, in reverse order.
-@code{reverse} constructs a new list, @code{reverse!} modifies
-@var{lst} in constructing its return.
+@code{reverse} constructs a new list. @code{reverse!} is permitted, but
+not required, to modify @var{lst} in constructing its return.
For @code{reverse!}, the optional @var{newtail} is appended to the
result. @var{newtail} isn't reversed, it simply becomes the list
characters or some of the other data types. The read syntax for vectors
is as follows: A sharp sign (@code{#}), followed by an opening
parentheses, all elements of the vector in their respective read syntax,
-and finally a closing parentheses. The following are examples of the
-read syntax for vectors; where the first vector only contains numbers
-and the second three different object types: a string, a symbol and a
-number in hexadecimal notation.
+and finally a closing parentheses. Like strings, vectors do not have to
+be quoted.
+
+The following are examples of the read syntax for vectors; where the
+first vector only contains numbers and the second three different object
+types: a string, a symbol and a number in hexadecimal notation.
@lisp
#(1 2 3)
#("Hello" foo #xdeadbeef)
@end lisp
-Like lists, vectors have to be quoted:
-
-@lisp
-'#(a b c) @result{} #(a b c)
-@end lisp
-
@node Vector Creation
@subsubsection Dynamic Vector Creation and Validation
Return a newly allocated list composed of the elements of @var{v}.
@lisp
-(vector->list '#(dah dah didah)) @result{} (dah dah didah)
+(vector->list #(dah dah didah)) @result{} (dah dah didah)
(list->vector '(dididit dah)) @result{} #(dididit dah)
@end lisp
@end deffn
Return the contents of position @var{k} of @var{vec}.
@var{k} must be a valid index of @var{vec}.
@lisp
-(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
+(vector-ref #(1 1 2 3 5 8 13 21) 5) @result{} 8
+(vector-ref #(1 1 2 3 5 8 13 21)
(let ((i (round (* 2 (acos -1)))))
(if (inexact? i)
(inexact->exact i)
#*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)
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
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
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::
@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
@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
@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
@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}.
with its own new record interface, leading to a maze of record APIs.
At the highest level is SRFI-9, a high-level record interface
-implemented by most Scheme implementations (@pxref{SRFI-9}). It defines
-a simple and efficient syntactic abstraction of record types and their
-associated type predicate, fields, and field accessors. SRFI-9 is
+implemented by most Scheme implementations (@pxref{SRFI-9 Records}). It
+defines a simple and efficient syntactic abstraction of record types and
+their associated type predicate, fields, and field accessors. SRFI-9 is
suitable for most uses, and this is the recommended way to create record
types in Guile. Similar high-level record APIs include SRFI-35
(@pxref{SRFI-35}) and R6RS records (@pxref{rnrs records syntactic}).
(use-modules (srfi srfi-9))
@end example
-@deffn {library syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{}
+@deffn {Scheme Syntax} define-record-type type @* (constructor fieldname @dots{}) @* predicate @* (fieldname accessor [modifier]) @dots{}
@sp 1
Create a new record type, and make various @code{define}s for using
it. This syntax can only occur at the top-level, not nested within
An example will illustrate typical usage,
@example
-(define-record-type employee-type
+(define-record-type <employee>
(make-employee name age salary)
employee?
- (name get-employee-name)
- (age get-employee-age set-employee-age)
- (salary get-employee-salary set-employee-salary))
+ (name employee-name)
+ (age employee-age set-employee-age!)
+ (salary employee-salary set-employee-salary!))
@end example
This creates a new employee data type, with name, age and salary
can all then be used as for example,
@example
-employee-type @result{} #<record-type employee-type>
+<employee> @result{} #<record-type <employee>>
(define fred (make-employee "Fred" 45 20000.00))
(employee? fred) @result{} #t
-(get-employee-age fred) @result{} 45
-(set-employee-salary fred 25000.00) ;; pay rise
+(employee-age fred) @result{} 45
+(set-employee-salary! fred 25000.00) ;; pay rise
@end example
The functions created by @code{define-record-type} are ordinary
This example prints the employee's name in brackets, for instance @code{[Fred]}.
@example
-(set-record-type-printer! employee-type
+(set-record-type-printer! <employee>
(lambda (record port)
(write-char #\[ port)
- (display (get-employee-name record) port)
+ (display (employee-name record) port)
(write-char #\] port)))
@end example
Note that in many ways, this interface is too low-level for every-day
use. Most uses of records are better served by SRFI-9 records.
-@xref{SRFI-9}.
+@xref{SRFI-9 Records}.
@deffn {Scheme Procedure} record? obj
Return @code{#t} if @var{obj} is a record of any type and @code{#f}
added.
@end deffn
+@deffn {Scheme Procedure} alist->hash-table alist
+@deffnx {Scheme Procedure} alist->hashq-table alist
+@deffnx {Scheme Procedure} alist->hashv-table alist
+@deffnx {Scheme Procedure} alist->hashx-table hash assoc alist
+Convert @var{alist} into a hash table. When keys are repeated in
+@var{alist}, the leftmost association takes precedence.
+
+@example
+(use-modules (ice-9 hash-table))
+(alist->hash-table '((foo . 1) (bar . 2)))
+@end example
+
+When converting to an extended hash table, custom @var{hash} and
+@var{assoc} procedures must be provided.
+
+@example
+(alist->hashx-table hash assoc '((foo . 1) (bar . 2)))
+@end example
+
+@end deffn
+
@deffn {Scheme Procedure} hash-table? obj
@deffnx {C Function} scm_hash_table_p (obj)
Return @code{#t} if @var{obj} is a abstract hash table object.
HCoop / bpt / guile.git / blobdiff