25.2 Interface conventions

The following conventions hold:

• Procedures whose names end in -ci are case–insensitive variants.
• 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 ones 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:

• An S argument is a string view, which is expanded by a macro in a triplet of values: the string, the index of the first char in the selected substring, the index of the character past the last in the selected position. strings views for details.
• A str argument is a string.
• A char argument is a character.
• The start and past arguments are half–open string indices specifying a substring within a string argument; when unspecified, they default to zero and the length of the string, respectively. When specified, it must be the case that:

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

  for the corresponding argument str. They typically restrict a procedure’s action to the indicated substring; when start equals past the selected substring is the empty string.

• A pred argument is a unary character predicate procedure, returning a true/false value when applied to a character.
• A char/char-set/pred argument is a value used to select/search for a character in a string. If it is a character, it is used in an equality test; if it is a character set, it is used in a membership test; if it is a procedure, it is applied to the characters as a test predicate.
• An i or k argument is an exact non–negative integer specifying an index into a string.
• The len and nchars arguments are exact non–negative integers specifying a length of a string or some number of characters.
• 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.

Comparison is simply done on individual code–points of the string. Unless explicitly stated, for all the functions: Case–insensitive comparison is done using the functions:

char-ci=? char-ci<? char-ci>? char-ci<=? char-ci>=?

provided by the underlying implementation, or by case–folding characters with the operation:

(char-downcase (char-upcase c))

where the two case–mapping operations are assumed to be one–to–one, locale–insensitive and context–insensitive, and compatible with the one–to–one case mappings specified by Unicode’s UnicodeData.txt table: