24.2 Interface conventions

In order to simplify text in this documentation section, the values of a vector are called items.

The following naming convention holds:

• Procedures whose names end in ! are side–effecting variants. What values these procedures return is usually not specified.
• The order of common arguments is consistent across the different procedures in the high level library, and consistent across the different procedures in the low level library. Arguments to some functions in the high level library have different order from the one of the homologous low level functions.
• Procedures that have left/right directional variants use the following convention:

  Direction	Suffix
  left-to-right	?none
  right-to-left	–right
  both	–both

In the procedure specifications:

• A V argument is a vector view, which is expanded by a macro in a triplet of values: the vector, the index of the first value in the selected subvector, the index of the value past the last in the selected position. vectors views for details.
• A vec argument is a vector.
• The start and past arguments are half–open vector indices specifying a subvector within a vector argument; when unspecified, they default to zero and the length of the vector, respectively. When specified, it must be the case that:

  0 <= start <= past <= (vector-length s)
  

  for the corresponding argument vec. They typically restrict a procedure’s action to the indicated subvector; when start equals past the selected subvector is the empty vector.

• A pred argument is a unary value predicate procedure, returning a true/false value when applied to a value.
• A item= argument is a binary function applied to two items, it must return true when they are equal, false otherwise.
• A item< argument is a binary function applied to two items, it must return true when the first is less than the second, false otherwise.
• An i or k argument is an exact non–negative integer specifying an index into a vector.
• The len and nvalues arguments are exact non–negative integers specifying a length of a vector or some number of values.
• An obj argument can be any value.

An argument followed by ... means zero–or–more elements. So the procedure with the signature:

sum-squares x ...

takes zero or more arguments (x, …), while the procedure with signature:

spell-check doc dict1 dict2 ...

takes two mandatory arguments (doc and dict1) and zero or more optional arguments (dict2 ...).

If a procedure is said to return “unspecified”, this means that nothing at all is known about what the procedure returns. Such a procedure is not even required to be consistent from call to call. It is simply required to return a value (or values) that may be passed to a command continuation, e.g. as the value of an expression appearing as a non–terminal subform of a begin expression.