Update vm.texi's "Instruction Set" section.

[bpt/guile.git] / doc / ref / api-utility.texi

diff --git a/doc/ref/api-utility.texi b/doc/ref/api-utility.texi
index 8cc662f..76c50b2 100644 (file)
--- a/doc/ref/api-utility.texi
+++ b/doc/ref/api-utility.texi
@@ -1,10 +1,9 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @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, 2011, 2012, 2013

 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 

-@page

 @node Utility Functions
 @section General Utility Functions
 
 @node Utility Functions
 @section General Utility Functions
 


@@ -26,65 +25,150 @@ applications, they are collected in a @dfn{utility} chapter.
 
 @node Equality
 @subsection Equality
 
 @node Equality
 @subsection Equality

-
-@c FIXME::martin: Review me!
-

 @cindex sameness
 @cindex equality
 
 @cindex sameness
 @cindex equality
 

-Three different kinds of @dfn{sameness} are defined in Scheme.
+There are three kinds of core equality predicates in Scheme, described
+below.  The same kinds of comparisons arise in other functions, like
+@code{memq} and friends (@pxref{List Searching}).
+
+For all three tests, objects of different types are never equal.  So
+for instance a list and a vector are not @code{equal?}, even if their
+contents are the same.  Exact and inexact numbers are considered
+different types too, and are hence not equal even if their values are
+the same.
+
+@code{eq?} tests just for the same object (essentially a pointer
+comparison).  This is fast, and can be used when searching for a
+particular object, or when working with symbols or keywords (which are
+always unique objects).
+
+@code{eqv?} extends @code{eq?} to look at the value of numbers and
+characters.  It can for instance be used somewhat like @code{=}
+(@pxref{Comparison}) but without an error if one operand isn't a
+number.
+
+@code{equal?} goes further, it looks (recursively) into the contents
+of lists, vectors, etc.  This is good for instance on lists that have
+been read or calculated in various places and are the same, just not
+made up of the same pairs.  Such lists look the same (when printed),
+and @code{equal?} will consider them the same.
+
+@sp 1
+@deffn {Scheme Procedure} eq? x y
+@deffnx {C Function} scm_eq_p (x, y)
+@rnindex eq?
+Return @code{#t} if @var{x} and @var{y} are the same object, except
+for numbers and characters.  For example,

 
 

-@itemize @bullet
-@item
-Two values can refer to exactly the same object.
+@example
+(define x (vector 1 2 3))
+(define y (vector 1 2 3))

 
 

-@item
-Two objects can have the same @dfn{value}.
+(eq? x x)  @result{} #t
+(eq? x y)  @result{} #f
+@end example

 
 

-@item
-Two objects can be structurally equivalent.
-@end itemize
+Numbers and characters are not equal to any other object, but the
+problem is they're not necessarily @code{eq?} to themselves either.
+This is even so when the number comes directly from a variable,

 
 

-The differentiation between these three kinds is important, because
-determining whether two values are the same objects is very efficient,
-while determining structural equivalence can be quite expensive
-(consider comparing two very long lists).  Therefore, three different
-procedures for testing for equality are provided, which correspond to
-the three kinds of @dfn{sameness} defined above.
+@example
+(let ((n (+ 2 3)))
+  (eq? n n))       @result{} *unspecified*
+@end example

 
 

-@rnindex eq?
-@deffn {Scheme Procedure} eq? x y
-@deffnx {C Function} scm_eq_p (x, y)
-Return @code{#t} iff @var{x} references the same object as @var{y}.
-@code{eq?} is similar to @code{eqv?} except that in some cases it is
-capable of discerning distinctions finer than those detectable by
-@code{eqv?}.
+Generally @code{eqv?} below should be used when comparing numbers or
+characters.  @code{=} (@pxref{Comparison}) or @code{char=?}
+(@pxref{Characters}) can be used too.
+
+It's worth noting that end-of-list @code{()}, @code{#t}, @code{#f}, a
+symbol of a given name, and a keyword of a given name, are unique
+objects.  There's just one of each, so for instance no matter how
+@code{()} arises in a program, it's the same object and can be
+compared with @code{eq?},
+
+@example
+(define x (cdr '(123)))
+(define y (cdr '(456)))
+(eq? x y) @result{} #t
+
+(define x (string->symbol "foo"))
+(eq? x 'foo) @result{} #t
+@end example

 @end deffn
 
 @deftypefn {C Function} int scm_is_eq (SCM x, SCM y)
 Return @code{1} when @var{x} and @var{y} are equal in the sense of
 @end deffn
 
 @deftypefn {C Function} int scm_is_eq (SCM x, SCM y)
 Return @code{1} when @var{x} and @var{y} are equal in the sense of

-@code{eq?}, else return @code{0}.
+@code{eq?}, otherwise return @code{0}.
+
+@findex ==
+The @code{==} operator should not be used on @code{SCM} values, an
+@code{SCM} is a C type which cannot necessarily be compared using
+@code{==} (@pxref{The SCM Type}).

 @end deftypefn
 
 @end deftypefn
 

-@rnindex eqv?
+@sp 1

 @deffn {Scheme Procedure} eqv? x y
 @deffnx {C Function} scm_eqv_p (x, y)
 @deffn {Scheme Procedure} eqv? x y
 @deffnx {C Function} scm_eqv_p (x, y)

-The @code{eqv?} procedure defines a useful equivalence relation on objects.
-Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
-regarded as the same object.  This relation is left slightly open to
-interpretation, but works for comparing immediate integers, characters,
-and inexact numbers.
+@rnindex eqv?
+Return @code{#t} if @var{x} and @var{y} are the same object, or for
+characters and numbers the same value.
+
+On objects except characters and numbers, @code{eqv?} is the same as
+@code{eq?} above, it's true if @var{x} and @var{y} are the same
+object.
+
+If @var{x} and @var{y} are numbers or characters, @code{eqv?} compares
+their type and value.  An exact number is not @code{eqv?} to an
+inexact number (even if their value is the same).
+
+@example
+(eqv? 3 (+ 1 2)) @result{} #t
+(eqv? 1 1.0)     @result{} #f
+@end example

 @end deffn
 
 @end deffn
 

-@rnindex equal?
+@sp 1

 @deffn {Scheme Procedure} equal? x y
 @deffnx {C Function} scm_equal_p (x, y)
 @deffn {Scheme Procedure} equal? x y
 @deffnx {C Function} scm_equal_p (x, y)

-Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?}
-equivalent.  @code{equal?} recursively compares the contents of pairs,
-vectors, and strings, applying @code{eqv?} on other objects such as
-numbers and symbols.  A rule of thumb is that objects are generally
-@code{equal?}  if they print the same.  @code{equal?} may fail to
-terminate if its arguments are circular data structures.
+@rnindex equal?
+Return @code{#t} if @var{x} and @var{y} are the same type, and their
+contents or value are equal.
+
+For a pair, string, vector, array or structure, @code{equal?} compares the
+contents, and does so using the same @code{equal?} recursively,
+so a deep structure can be traversed.
+
+@example
+(equal? (list 1 2 3) (list 1 2 3))   @result{} #t
+(equal? (list 1 2 3) (vector 1 2 3)) @result{} #f
+@end example
+
+For other objects, @code{equal?} compares as per @code{eqv?} above,
+which means characters and numbers are compared by type and value (and
+like @code{eqv?}, exact and inexact numbers are not @code{equal?},
+even if their value is the same).
+
+@example
+(equal? 3 (+ 1 2)) @result{} #t
+(equal? 1 1.0)     @result{} #f
+@end example
+
+Hash tables are currently only compared as per @code{eq?}, so two
+different tables are not @code{equal?}, even if their contents are the
+same.
+
+@code{equal?} does not support circular data structures, it may go
+into an infinite loop if asked to compare two circular lists or
+similar.
+
+New application-defined object types (@pxref{Defining New Types
+(Smobs)}) have an @code{equalp} handler which is called by
+@code{equal?}.  This lets an application traverse the contents or
+control what is considered @code{equal?} for two objects of such a
+type.  If there's no such handler, the default is to just compare as
+per @code{eq?}.

 @end deffn
 
 
 @end deffn
 
 


@@ -96,13 +180,6 @@ Scheme object even though that object does not have a dedicated slot
 available in which the additional information could be stored.  Object
 properties allow you to do just that.
 
 available in which the additional information could be stored.  Object
 properties allow you to do just that.
 

-An object property is most commonly used to associate one kind of
-additional information with each instance of a class of similar Scheme
-objects.  For example, all procedures have a `name' property, which
-stores the name of the variable in which the procedure was stored by a
-@code{define} expression, or @code{#f} if the procedure wasn't created
-by that kind of expression.
-

 Guile's representation of an object property is a procedure-with-setter
 (@pxref{Procedures with Setters}) that can be used with the generalized
 form of @code{set!} (REFFIXME) to set and retrieve that property for any
 Guile's representation of an object property is a procedure-with-setter
 (@pxref{Procedures with Setters}) that can be used with the generalized
 form of @code{set!} (REFFIXME) to set and retrieve that property for any


@@ -152,57 +229,10 @@ protected.  When the Scheme value is collected, its entry in the
 property table is removed and so the (ex-) property values are no longer
 protected by the table.
 
 property table is removed and so the (ex-) property values are no longer
 protected by the table.
 

-@menu
-* Property Primitives::         Low level property implementation.
-* Old-fashioned Properties::    An older approach to properties.
-@end menu
-
-
-@node Property Primitives
-@subsubsection Low Level Property Implementation.
-
-@deffn {Scheme Procedure} primitive-make-property not-found-proc
-@deffnx {C Function} scm_primitive_make_property (not_found_proc)
-Create a @dfn{property token} that can be used with
-@code{primitive-property-ref} and @code{primitive-property-set!}.
-See @code{primitive-property-ref} for the significance of
-@var{not-found-proc}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-ref prop obj
-@deffnx {C Function} scm_primitive_property_ref (prop, obj)
-Return the property @var{prop} of @var{obj}.
-
-When no value has yet been associated with @var{prop} and @var{obj},
-the @var{not-found-proc} from @var{prop} is used.  A call
-@code{(@var{not-found-proc} @var{prop} @var{obj})} is made and the
-result set as the property value.  If @var{not-found-proc} is
-@code{#f} then @code{#f} is the property value.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-set! prop obj val
-@deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
-Set the property @var{prop} of @var{obj} to @var{val}.
-@end deffn
-
-@deffn {Scheme Procedure} primitive-property-del! prop obj
-@deffnx {C Function} scm_primitive_property_del_x (prop, obj)
-Remove any value associated with @var{prop} and @var{obj}.
-@end deffn
-
-
-@node Old-fashioned Properties
-@subsubsection An Older Approach to Properties
-
-Traditionally, Lisp systems provide a different object property
-interface to that provided by @code{make-object-property}, in which the
-object property that is being set or retrieved is indicated by a symbol.
-
-Guile includes this older kind of interface as well, but it may well be
-removed in a future release, as it is less powerful than
-@code{make-object-property} and so increases the size of the Guile
-library for no benefit.  (And it is trivial to write a compatibility
-layer in Scheme.)
+Guile also implements a more traditional Lispy interface to properties,
+in which each object has an list of key-value pairs associated with it.
+Properties in that list are keyed by symbols.  This is a legacy
+interface; you should use weak hash tables or object properties instead.

 
 @deffn {Scheme Procedure} object-properties obj
 @deffnx {C Function} scm_object_properties (obj)
 
 @deffn {Scheme Procedure} object-properties obj
 @deffnx {C Function} scm_object_properties (obj)


@@ -278,9 +308,10 @@ input.
 
 @deffn {Scheme Procedure} sorted? items less
 @deffnx {C Function} scm_sorted_p (items, less)
 
 @deffn {Scheme Procedure} sorted? items less
 @deffnx {C Function} scm_sorted_p (items, less)

-Return @code{#t} iff @var{items} is a list or a vector such that
-for all 1 <= i <= m, the predicate @var{less} returns true when
-applied to all elements i - 1 and i
+Return @code{#t} if @var{items} is a list or vector such that,
+for each element @var{x} and the next element @var{y} of
+@var{items}, @code{(@var{less} @var{y} @var{x})} returns
+@code{#f}.  Otherwise return @code{#f}.

 @end deffn
 
 @deffn {Scheme Procedure} sort items less
 @end deffn
 
 @deffn {Scheme Procedure} sort items less


@@ -335,7 +366,8 @@ This is a stable sort.
 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
 Sort the vector @var{vec}, using @var{less} for comparing
 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
 Sort the vector @var{vec}, using @var{less} for comparing

-the vector elements.  @var{startpos} and @var{endpos} delimit
+the vector elements.  @var{startpos} (inclusively) and
+@var{endpos} (exclusively) delimit

 the range of the vector which gets sorted.  The return value
 is not specified.
 @end deffn
 the range of the vector which gets sorted.  The return value
 is not specified.
 @end deffn


@@ -354,8 +386,8 @@ copies any pairs in the cars of the input lists.
 
 @deffn {Scheme Procedure} copy-tree obj
 @deffnx {C Function} scm_copy_tree (obj)
 
 @deffn {Scheme Procedure} copy-tree obj
 @deffnx {C Function} scm_copy_tree (obj)

-Recursively copy the data tree that is bound to @var{obj}, and return a
-pointer to the new data structure.  @code{copy-tree} recurses down the
+Recursively copy the data tree that is bound to @var{obj}, and return
+the new data structure.  @code{copy-tree} recurses down the

 contents of both pairs and vectors (since both cons cells and vector
 cells may point to arbitrary objects), and stops recursing when it hits
 any other object.
 contents of both pairs and vectors (since both cons cells and vector
 cells may point to arbitrary objects), and stops recursing when it hits
 any other object.


@@ -552,11 +584,11 @@ value of this procedure is not specified.
 Convert the procedure list of @var{hook} to a list.
 @end deffn
 
 Convert the procedure list of @var{hook} to a list.
 @end deffn
 

-@deffn {Scheme Procedure} run-hook hook . args
+@deffn {Scheme Procedure} run-hook hook arg @dots{}

 @deffnx {C Function} scm_run_hook (hook, args)
 @deffnx {C Function} scm_run_hook (hook, args)

-Apply all procedures from the hook @var{hook} to the arguments
-@var{args}.  The order of the procedure application is first to
-last.  The return value of this procedure is not specified.
+Apply all procedures from the hook @var{hook} to the arguments @var{arg}
+@enddots{}.  The order of the procedure application is first to last.
+The return value of this procedure is not specified.

 @end deffn
 
 If, in C code, you are certain that you have a hook object and well
 @end deffn
 
 If, in C code, you are certain that you have a hook object and well


@@ -740,7 +772,7 @@ accessible from C with the name @code{scm_after_gc_hook}.)
 @end defvr
 
 All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
 @end defvr
 
 All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are

-initialized with hook closure data NULL, are are invoked by
+initialized with hook closure data NULL, are invoked by

 @code{scm_c_hook_run} with call closure data NULL.
 
 @cindex guardians, testing for GC'd objects
 @code{scm_c_hook_run} with call closure data NULL.
 
 @cindex guardians, testing for GC'd objects