27.2.2 Interface conventions

The following conventions hold:

• Procedures whose names end in -ci are case–insensitive variants; they interpret bytevectors as strings of characters in ASCII encoding: when doing comparisons they use char-ci=? and char-ci<? and the like.
• 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:

• A B argument is a bytevector view, which is expanded by a macro in a triplet of values: the bytevector, the index of the first byte in the selected subvector, the index of the byte past the last in the selected position; bytevectors 8 views for details.
• A bv argument is a bytevector.
• A byte argument is an exact integer representing an unsigned byte, that is in the range [0, 256).
• A char argument is a character.
• The start and past arguments are half–open bytevector indices specifying a subvector within a bytevector argument; when unspecified, they default to zero and the length of the bytevector, respectively. When specified, it must be the case that:

  0 <= start <= past <= (bytevector-length bv)
  

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

• A pred argument is a unary predicate procedure, returning a true/false value when applied to an exact integer representing a byte.
• A criterion orn byte/char/char-set/pred argument is a value used to select/search for a byte in a bytevector:
  • - If it is a byte, it is used in an equality test with =.
  • - If it is a character, it is used in an equality test with = after having been converted to an exact integer with char->integer.
  • - If it is a character set, it is used in a membership test after the byte has been converted to a character with integer->char.
  • - If it is a procedure, it is applied to the bytes as a test predicate.
• An i or k argument is an exact non–negative integer specifying an index into a bytevector.
• The len and nbytes arguments are exact non–negative integers specifying a length of a bytevector or some number of bytes.
• 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.

Unless explicitly stated: comparison is simply done on individual bytes of the bytevector, case–insensitive comparison is done converting the bytes to characters with integer->char and then 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 (integer->char byte)))

where the two case–mapping operations are assumed to work for characters in the range allowed by ASCII encoding.