@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
But beware, if you want to try out these examples, you have to
@dfn{quote} the expressions. More information about quotation is
-available in the section (REFFIXME). The correct way to try these
-examples is as follows.
+available in the section @ref{Expression Syntax}. The correct way
+to try these examples is as follows.
@lisp
'(1 . 2)
()
@end lisp
-This example also shows that lists have to be quoted (REFFIXME) when
-written, because they would otherwise be mistakingly taken as procedure
-applications (@pxref{Simple Invocation}).
+This example also shows that lists have to be quoted when written
+(@pxref{Expression Syntax}), because they would otherwise be
+mistakingly taken as procedure applications (@pxref{Simple
+Invocation}).
@node List Predicates
order as in @var{lst}. The order in which @var{pred} is applied to
the list elements is not specified.
-@code{filter!} is allowed, but not required to modify the structure of
+@code{filter} does not change @var{lst}, but the result may share a
+tail with it. @code{filter!} may modify @var{lst} to construct its
+return.
@end deffn
@node List Searching
@var{vec}. No type or range checking is done.
@end deftypefn
-@deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET_X (SCM vec, size_t idx, SCM val)
+@deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val)
Sets the element at position @var{idx} in the simple vector
@var{vec} to @var{val}. No type or range checking is done.
@end deftypefn
Return @code{#t} if all arguments are arrays with the same shape, the
same type, and have corresponding elements which are either
@code{equal?} or @code{array-equal?}. This function differs from
-@code{equal?} in that a one dimensional shared array may be
-@var{array-equal?} but not @var{equal?} to a vector or uniform vector.
+@code{equal?} (@pxref{Equality}) in that a one dimensional shared
+array may be @code{array-equal?} but not @code{equal?} to a vector or
+uniform vector.
@end deffn
@c FIXME: array-map! accepts no source arrays at all, and in that
@example
(make-shared-array #1(a b c d e f g h i j k l)
- (lambda (i) (* i 3))
+ (lambda (i) (list (* i 3)))
4)
@result{} #1(a d g j)
@end example
the danger of a deadlock. In a multi-threaded program, you will need
additional synchronization to avoid modifying reserved arrays.)
-You must take care to always unreserve an array after reserving it, also
-in the presence of non-local exits. To simplify this, reserving and
-unreserving work like a frame (@pxref{Frames}): a call to
-@code{scm_array_get_handle} can be thought of as beginning a frame and
-@code{scm_array_handle_release} as ending it. When a non-local exit
-happens between these two calls, the array is implicitely unreserved.
+You must take care to always unreserve an array after reserving it,
+also in the presence of non-local exits. To simplify this, reserving
+and unreserving work like a dynwind context (@pxref{Dynamic Wind}): a
+call to @code{scm_array_get_handle} can be thought of as beginning a
+dynwind context and @code{scm_array_handle_release} as ending it.
+When a non-local exit happens between these two calls, the array is
+implicitely unreserved.
That is, you need to properly pair reserving and unreserving in your
code, but you don't need to worry about non-local exits.
-These calls and other pairs of calls that establish dynamic contexts
-need to be properly nested. If you begin a frame prior to reserving an
-array, you need to unreserve the array before ending the frame.
-Likewise, when reserving two or more arrays in a certain order, you need
-to unreserve them in the opposite order.
+These calls and other pairs of calls that establish dynwind contexts
+need to be properly nested. If you begin a context prior to reserving
+an array, you need to unreserve the array before ending the context.
+Likewise, when reserving two or more arrays in a certain order, you
+need to unreserve them in the opposite order.
Once you have reserved an array and have retrieved the pointer to its
elements, you must figure out the layout of the elements in memory.
given indices from the start of the storage block of the array.
In Guile, this mapping function is restricted to be @dfn{affine}: all
-mapping function of Guile arrays can be written as @code{p = b +
+mapping functions of Guile arrays can be written as @code{p = b +
c[0]*i[0] + c[1]*i[1] + ... + c[n-1]*i[n-1]} where @code{i[k]} is the
-@nicode{k}th index and @code{n} is the rank of the array. For example,
-a matrix of size 3x3 would have @code{b == 0}, @code{c[0] == 3} and
-@code{c[1] == 1}. When you transpose this matrix (with
+@nicode{k}th index and @code{n} is the rank of the array. For
+example, a matrix of size 3x3 would have @code{b == 0}, @code{c[0] ==
+3} and @code{c[1] == 1}. When you transpose this matrix (with
@code{transpose-array}, say), you will get an array whose mapping
function has @code{b == 0}, @code{c[0] == 1} and @code{c[1] == 3}.
vtable is another structure used to hold type-specific data. Multiple
structures can share a common vtable.
+When applied to structures, the @code{equal?} predicate
+(@pxref{Equality}) returns @code{#t} if the two structures share a
+common vtable @emph{and} all their fields satisfy @code{equal?}.
+
Three concepts are key to understanding structures.
@itemize @bullet{}
@rnindex assv
@rnindex assoc
-@code{assq}, @code{assv} and @code{assoc} take an alist and a key as
-arguments and return the entry for that key if an entry exists, or
-@code{#f} if there is no entry for that key. Note that, in the cases
-where an entry exists, these procedures return the complete entry, that
-is @code{(KEY . VALUE)}, not just the value.
+@code{assq}, @code{assv} and @code{assoc} find the entry in an alist
+for a given key, and return the @code{(@var{key} . @var{value})} pair.
+@code{assq-ref}, @code{assv-ref} and @code{assoc-ref} do a similar
+lookup, but return just the @var{value}.
@deffn {Scheme Procedure} assq key alist
@deffnx {Scheme Procedure} assv key alist
@deffnx {C Function} scm_assq (key, alist)
@deffnx {C Function} scm_assv (key, alist)
@deffnx {C Function} scm_assoc (key, alist)
-Fetch the entry in @var{alist} that is associated with @var{key}. To
-decide whether the argument @var{key} matches a particular entry in
-@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
-uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
-cannot be found in @var{alist} (according to whichever equality
-predicate is in use), then return @code{#f}. These functions
-return the entire alist entry found (i.e. both the key and the value).
-@end deffn
-
-@code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
-hand, take an alist and a key and return @emph{just the value} for that
-key, if an entry exists. If there is no entry for the specified key,
-these procedures return @code{#f}.
-
-This creates an ambiguity: if the return value is @code{#f}, it means
-either that there is no entry with the specified key, or that there
-@emph{is} an entry for the specified key, with value @code{#f}.
-Consequently, @code{assq-ref} and friends should only be used where it
-is known that an entry exists, or where the ambiguity doesn't matter
-for some other reason.
+Return the first entry in @var{alist} with the given @var{key}. The
+return is the pair @code{(KEY . VALUE)} from @var{alist}. If there's
+no matching entry the return is @code{#f}.
+
+@code{assq} compares keys with @code{eq?}, @code{assv} uses
+@code{eqv?} and @code{assoc} uses @code{equal?}.
+@end deffn
@deffn {Scheme Procedure} assq-ref alist key
@deffnx {Scheme Procedure} assv-ref alist key
@deffnx {C Function} scm_assq_ref (alist, key)
@deffnx {C Function} scm_assv_ref (alist, key)
@deffnx {C Function} scm_assoc_ref (alist, key)
-Like @code{assq}, @code{assv} and @code{assoc}, except that only the
-value associated with @var{key} in @var{alist} is returned. These
-functions are equivalent to
+Return the value from the first entry in @var{alist} with the given
+@var{key}, or @code{#f} if there's no such entry.
-@lisp
-(let ((ent (@var{associator} @var{key} @var{alist})))
- (and ent (cdr ent)))
-@end lisp
+@code{assq-ref} compares keys with @code{eq?}, @code{assv-ref} uses
+@code{eqv?} and @code{assoc-ref} uses @code{equal?}.
+
+Notice these functions have the @var{key} argument last, like other
+@code{-ref} functions, but this is opposite to what what @code{assq}
+etc above use.
-where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
+When the return is @code{#f} it can be either @var{key} not found, or
+an entry which happens to have value @code{#f} in the @code{cdr}. Use
+@code{assq} etc above if you need to differentiate these cases.
@end deffn
+
@node Removing Alist Entries
@subsubsection Removing Alist Entries
HCoop / bpt / guile.git / blobdiff