General Utility Functions
*************************

This chapter contains information about procedures which are not cleanly tied to a specific data type.  Because of their wide range of applications, they are collected in a utlity chapter.

Equality
========

Three different kinds of sameness are defined in Scheme.

  * Two values can refer to exactly the same object.

  * Two objects can have the same value.

  * Two objects can be structurally equivalent.

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 sameness defined above.

 -- primitive: eq? x y
     Return #t iff X references the same object as Y. eq? is similar to eqv? except that in some cases it is capable of discerning distinctions finer than those detectable by eqv?.

 -- primitive: eqv? x y
     The eqv? procedure defines a useful equivalence relation on objects. Briefly, it returns #t if X and 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.

 -- primitive: equal? x y
     Return #t iff X and Y are recursively eqv? equivalent. equal? recursively compares the contents of pairs, vectors, and strings, applying eqv? on other objects such as numbers and symbols.  A rule of thumb is that objects are generally equal?  if they print the same.  equal? may fail to terminate if its arguments are circular data structures.

Property Lists
==============

Every object in the system can have a 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 (see 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 procedure functions; otherwise, use the object functions.

 -- primitive: object-properties obj
 -- primitive: procedure-properties obj
     Return OBJ's property list.

 -- primitive: set-object-properties! obj alist
 -- primitive: set-procedure-properties! obj alist
     Set OBJ's property list to ALIST.

 -- primitive: object-property obj key
 -- primitive: procedure-property obj key
     Return the property of OBJ with name KEY.

 -- primitive: set-object-property! obj key value
 -- primitive: set-procedure-property! obj key value
     In OBJ's property list, set the property named KEY to VALUE.

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

Primitive Properties
====================

 -- primitive: primitive-make-property not_found_proc
     Create a property token that can be used with primitive-property-ref and primitive-property-set!. See primitive-property-ref for the significance of NOT_FOUND_PROC.

 -- primitive: primitive-property-ref prop obj
     Return the property PROP of OBJ.  When no value has yet been associated with PROP and OBJ, call NOT-FOUND-PROC instead (see primitive-make-property) and use its return value.  That value is also associated with OBJ via primitive-property-set!.  When NOT-FOUND-PROC is #f, use #f as the default value of PROP.

 -- primitive: primitive-property-set! prop obj val
     Associate CODE with PROP and OBJ.

 -- primitive: primitive-property-del! prop obj
     Remove any value associated with PROP and OBJ.

Sorting
=======

Sorting is very important in computer programs.  Therefore, Guile comes with several sorting procedures built--in.  As always, procedures with names ending in ! are side--effecting, that means that they may modify their parameters in order to produce their results.

The first group of procedures can be used to merge two lists (which must be already sorted on their own) and produce sorted lists containing all elements of the input lists.

 -- primitive: merge alist blist less
     Take two lists ALIST and BLIST such that (sorted? alist less?) and (sorted? blist less?) and returns a new list in which the elements of ALIST and BLIST have been stably interleaved so that (sorted? (merge alist blist less?) less?).

 -- primitive: merge! alist blist less
     Takes two lists ALIST and BLIST such that (sorted? alist less?) and (sorted? blist less?) and returns a new list in which the elements of ALIST and BLIST have been stably interleaved so that (sorted? (merge alist blist less?) less?). This is the destructive variant of merge Note:  this does _not_ accept vectors.

The following procedures can operate on sequences which are either vectors or list.  According to the given arguments, they return sorted vectors or lists, respectively.  The first of the following procedures determines whether a sequence is already sorted, the other sort a given sequence.  The variants with names starting with stable- are special in that they maintain a special property of the input sequences: If two or more elements are the same according to the comparison predicate, they are left in the same order as they appeared in the input.

 -- primitive: sorted? items less
     Return #t iff ITEMS is a list or a vector such that for all 1 <= i <= m, the predicate LESS returns true when applied to all elements i - 1 and i

 -- primitive: sort items less
     Sort the sequence ITEMS, which may be a list or a vector.  LESS is used for comparing the sequence elements.  This is not a stable sort.

 -- primitive: sort! items less
     Sort the sequence ITEMS, which may be a list or a vector.  LESS is used for comparing the sequence elements.  The sorting is destructive, that means that the input sequence is modified to produce the sorted result. This is not a stable sort.

 -- primitive: stable-sort items less
     Sort the sequence ITEMS, which may be a list or a vector. LESS is used for comparing the sequence elements. This is a stable sort.

 -- primitive: stable-sort! items less
     Sort the sequence ITEMS, which may be a list or a vector. LESS is used for comparing the sequence elements. The sorting is destructive, that means that the input sequence is modified to produce the sorted result. This is a stable sort.

The procedures in the last group only accept lists or vectors as input, as their names indicate.

 -- primitive: sort-list items less
     Sort the list ITEMS, using LESS for comparing the list elements. This is a stable sort.

 -- primitive: sort-list! items less
     Sort the list ITEMS, using LESS for comparing the list elements. The sorting is destructive, that means that the input list is modified to produce the sorted result. This is a stable sort.

 -- primitive: restricted-vector-sort! vec less startpos endpos
     Sort the vector VEC, using LESS for comparing the vector elements.  STARTPOS and ENDPOS delimit the range of the vector which gets sorted.  The return value is not specified.

Copying Deep Structures
=======================

The procedures for copying lists (see Lists) only produce a flat copy of the input list, and currently Guile does not even contain procedures for copying vectors.  copy-tree can be used for these application, as it does not only copy the spine of a list, but also copies any pairs in the cars of the input lists.

 -- primitive: copy-tree obj
     Recursively copy the data tree that is bound to OBJ, and return a pointer to the new data structure.  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.

General String Conversion
=========================

When debugging Scheme programs, but also for providing a human--friendly interface, a procedure for converting any Scheme object into string format is very useful.  Conversion from/to strings can of course be done with specialized procedures when the data type of the object to convert is known, but with this procedure, it is often more comfortable.

object->string converts an object by using a print procedure for writing to a string port, and then returning the resulting string. Converting an object back from the string is only possible if the object type has a read syntax and the read syntax is preserved by the printing procedure.

 -- primitive: object->string obj [printer]
     Return a Scheme string obtained by printing OBJ. Printing function can be specified by the optional second argument PRINTER (default: write).