Common Lisp the Language, 2nd Edition

Next: String Construction and Up: Strings Previous: String Access

# 18.2. String Comparison

The naming conventions for these functions and for their keyword arguments generally follow the conventions for the generic sequence functions (see chapter 14).

Note that this remark, predating the design of the Common Lisp Object System, uses the term ``generic'' in a generic sense and not necessarily in the technical sense used by CLOS (see chapter 2).

[Function]
`string= string1 string2 &key :start1 :end1 :start2 :end2`

`string=` compares two strings and is true if they are the same (corresponding characters are identical) but is false if they are not. The function `equal` calls `string=` if applied to two strings.

The keyword arguments `:start1` and `:start2` are the places in the strings to start the comparison. The arguments `:end1` and `:end2` are the places in the strings to stop comparing; comparison stops just before the position specified by a limit. The ``start'' arguments default to zero (beginning of string), and the ``end'' arguments (if either omitted or `nil`) default to the lengths of the strings (end of string), so that by default the entirety of each string is examined. These arguments are provided so that substrings can be compared efficiently.

`string=` is necessarily false if the (sub)strings being compared are of unequal length; that is, if

    (not (= (- end1 start1) (- end2 start2)))

is true, then `string=` is false.

    (string= "foo" "foo") is true
    (string= "foo" "Foo") is false
    (string= "foo" "bar") is false
    (string= "together" "frog" :start1 1 :end1 3 :start2 2)
       is true

X3J13 voted in June 1989 (STRING-COERCION) to clarify string coercion (see `string`).

Compatibility note: `string=` is called `strequal` in Interlisp.

[Function]
`string-equal string1 string2 &key :start1 :end1 :start2 :end2`

`string-equal` is just like `string=` except that differences in case are ignored; two characters are considered to be the same if `char-equal` is true of them. For example:

    (string-equal "foo" "Foo") is true

X3J13 voted in June 1989 (STRING-COERCION) to clarify string coercion (see `string`).

[Function]

    string< string1 string2 &key :start1 :end1 :start2 :end2
    string> string1 string2 &key :start1 :end1 :start2 :end2
    string<= string1 string2 &key :start1 :end1 :start2 :end2
    string>= string1 string2 &key :start1 :end1 :start2 :end2
    string/= string1 string2 &key :start1 :end1 :start2 :end2

These functions compare the two string arguments lexicographically, and the result is `nil` unless string1 is respectively less than, greater than, less than or equal to, greater than or equal to, or not equal to string2. If the condition is satisfied, however, then the result is the index within the strings of the first character position at which the strings fail to match; put another way, the result is the length of the longest common prefix of the strings.

A string a is less than a string b if in the first position in which they differ the character of a is less than the corresponding character of b according to the function `char<`, or if string a is a proper prefix of string b (of shorter length and matching in all the characters of a).

The keyword arguments `:start1` and `:start2` are the places in the strings to start the comparison. The keyword arguments `:end1` and `:end2` are the places in the strings to stop comparing; comparison stops just before the position specified by a limit. The ``start'' arguments default to zero (beginning of string), and the ``end'' arguments (if either omitted or `nil`) default to the lengths of the strings (end of string), so that by default the entirety of each string is examined. These arguments are provided so that substrings can be compared efficiently. The index returned in case of a mismatch is an index into string1.

X3J13 voted in June 1989 (STRING-COERCION) to clarify string coercion (see `string`).

[Function]

    string-lessp string1 string2 &key :start1 :end1 :start2 :end2
    string-greaterp string1 string2 &key :start1 :end1 :start2 :end2
    string-not-greaterp string1 string2 &key :start1 :end1 :start2 :end2
    string-not-lessp string1 string2 &key :start1 :end1 :start2 :end2
    string-not-equal string1 string2 &key :start1 :end1 :start2 :end2

These are exactly like `string<`, `string>`, `string<=`, `string>=`, and `string/=`, respectively, except that distinctions between uppercase and lowercase letters are ignored. It is as if `char-lessp` were used instead of `char<` for comparing characters.

X3J13 voted in June 1989 (STRING-COERCION) to clarify string coercion (see `string`).

Next: String Construction and Up: Strings Previous: String Access