@page
@node Utility Functions
@chapter General Utility Functions

@menu
* Equality::                    When are two values `the same'?
* Property Lists::              Managing metainformation about Scheme objects.
* Primitive Properties::        A modern low-level interface to object properties.
* Sorting::                     Sort utility procedures.
* Copying::                     Copying deep structures.
@end menu


@node Equality
@section Equality

@c docstring begin (texi-doc-string "guile" "eq?")
@deffn primitive eq? 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?}.
@end deffn

@c docstring begin (texi-doc-string "guile" "eqv?")
@deffn primitive eqv? 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.
@end deffn

@c docstring begin (texi-doc-string "guile" "equal?")
@deffn primitive equal? 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.
@end deffn


@node Property Lists
@section Property Lists

Every object in the system can have a @dfn{property list} that may
be used for information about that object.  For example, a
function may have a property list that includes information about
the source file in which it is defined.

Property lists are implemented as assq lists (@pxref{Association Lists}).

Currently, property lists are implemented differently for procedures and
closures than for other kinds of objects.  Therefore, when manipulating
a property list associated with a procedure object, use the
@code{procedure} functions; otherwise, use the @code{object} functions.

@c docstring begin (texi-doc-string "guile" "object-properties")
@deffn primitive object-properties obj
@deffnx primitive procedure-properties obj
Return @var{obj}'s property list.
@end deffn

@c ARGFIXME alist/plist
@c docstring begin (texi-doc-string "guile" "set-object-properties!")
@deffn primitive set-object-properties! obj plist
@deffnx primitive set-procedure-properties! obj alist
Set @var{obj}'s property list to @var{alist}.
@end deffn

@c docstring begin (texi-doc-string "guile" "object-property")
@deffn primitive object-property obj key
@deffnx primitive procedure-property obj key
Return the property of @var{obj} with name @var{key}.
@end deffn

@c ARGFIXME val/value
@c docstring begin (texi-doc-string "guile" "set-object-property!")
@deffn primitive set-object-property! obj key val
@deffnx primitive set-procedure-property! obj key value
In @var{obj}'s property list, set the property named @var{key} to
@var{value}.
@end deffn

[Interface bug:  there should be a second level of interface in which
the user provides a "property table" that is possibly private.]


@node Primitive Properties
@section Primitive Properties

@c docstring begin (texi-doc-string "guile" "primitive-make-property")
@deffn primitive 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

@c docstring begin (texi-doc-string "guile" "primitive-property-ref")
@deffn primitive 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}, call
@var{not-found-proc} instead (see @code{primitive-make-property})
and use its return value.  That value is also associated with
@var{obj} via @code{primitive-property-set!}.  When
@var{not-found-proc} is @code{#f}, use @code{#f} as the
default value of @var{prop}.
@end deffn

@c docstring begin (texi-doc-string "guile" "primitive-property-set!")
@deffn primitive primitive-property-set! prop obj val
Associate @var{code} with @var{prop} and @var{obj}.
@end deffn

@c docstring begin (texi-doc-string "guile" "primitive-property-del!")
@deffn primitive primitive-property-del! prop obj
Remove any value associated with @var{prop} and @var{obj}.
@end deffn


@node Sorting
@section Sorting

@c docstring begin (texi-doc-string "guile" "merge!")
@deffn primitive merge! alist blist less
@end deffn

@c docstring begin (texi-doc-string "guile" "merge")
@deffn primitive merge alist blist less
@end deffn

@c docstring begin (texi-doc-string "guile" "restricted-vector-sort!")
@deffn primitive restricted-vector-sort! vec less startpos endpos
@end deffn

@c docstring begin (texi-doc-string "guile" "sort!")
@deffn primitive sort! items less
@end deffn

@c docstring begin (texi-doc-string "guile" "sort")
@deffn primitive sort items less
@end deffn

@c docstring begin (texi-doc-string "guile" "sort-list!")
@deffn primitive sort-list! items less
@end deffn

@c docstring begin (texi-doc-string "guile" "sort-list")
@deffn primitive sort-list items less
@end deffn

@c docstring begin (texi-doc-string "guile" "sorted?")
@deffn primitive sorted? items less
@end deffn

@c docstring begin (texi-doc-string "guile" "stable-sort!")
@deffn primitive stable-sort! items less
@end deffn

@c docstring begin (texi-doc-string "guile" "stable-sort")
@deffn primitive stable-sort items less
@end deffn


@node Copying
@section Copying Deep Structures

@c docstring begin (texi-doc-string "guile" "copy-tree")
@deffn primitive 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
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.
@end deffn


@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
