@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, 2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Utility Functions
@section General Utility Functions
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 or array, @code{equal?} compares the
-contents, and does so using using the same @code{equal?} recursively,
+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
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?}.
+GOOPS object types (@pxref{GOOPS}), including foreign object types
+(@pxref{Defining New Foreign Object Types}), can have an @code{equal?}
+implementation specialized on two values of the same type. If
+@code{equal?} is called on two GOOPS objects of the same type,
+@code{equal?} will dispatch out to a generic function. 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
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
A single object property created by @code{make-object-property} can
associate distinct property values with all Scheme values that are
-distinguishable by @code{eq?} (including, for example, integers).
+distinguishable by @code{eq?} (ruling out numeric values).
Internally, object properties are implemented using a weak key hash
table. This means that, as long as a Scheme value with property values
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} 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
@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
@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
+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
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)
-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 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
HCoop / bpt / guile.git / blobdiff