User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:string-equal [2019/11/11 05:00]
cl:functions:string-equal [2019/11/13 17:00] (current)
Line 1: Line 1:
 +====== Function STRING=, STRING/=, STRING<, STRING>, STRING<​=,​ STRING>​=,​ STRING-EQUAL,​ STRING-NOT-EQUAL,​ STRING-LESSP,​ STRING-GREATERP,​ STRING-NOT-GREATERP,​ STRING-NOT-LESSP ======
 +
 +====Syntax====
 +  * **string=** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → generalized-boolean
 +  * **string/​=** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string<​** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string>​** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string<​=** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string>​=** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string-equal** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​generalized-boolean//​
 +  * **string-not-equal** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string-lessp** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string-greaterp** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string-not-greaterp** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +  * **string-not-lessp** //string1// //string2// ''&​key''​ //start1// //end1// //start2// //end2// → //​mismatch-index//​
 +
 +====Arguments and Values====
 +  * //string1// - a //​[[CL:​Glossary:​string designator]]//​.
 +  * //string2// - a //​[[CL:​Glossary:​string designator]]//​.
 +  * //start1//, //end1// - //​[[CL:​Glossary:​bounding index designator|bounding index designators]]//​ of //​string1//​. The defaults for //start// and //end// are ''​0''​ and **[[CL:​Constant Variables:​nil]]**,​ respectively.
 +  * //start2//, //end2// - //​[[CL:​Glossary:​bounding index designator|bounding index designators]]//​ of //​string2//​. The defaults for //start// and //end// are ''​0''​ and **[[CL:​Constant Variables:​nil]]**,​ respectively.
 +  * //​generalized-boolean//​ - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​mismatch-index//​ - a //​[[CL:​Glossary:​bounding index]]// of //​string1//,​ or **[[CL:​Constant Variables:​nil]]**.
 +
 +====Description====
 +These functions perform lexicographic comparisons on //string1// and //​string2//​. **string=** and **string-equal** are called equality functions; the others are called inequality functions. The comparison operations these //​[[CL:​Glossary:​functions]]//​ perform are restricted to the subsequence of //string1// //​[[CL:​Glossary:​bounded]]//​ by //​[[CL:​Glossary:​start1]]//​ and //end1// and to the subsequence of //string2// //​[[CL:​Glossary:​bounded]]//​ by //​[[CL:​Glossary:​start2]]//​ and //end2//.
 +
 +A string ''​a''​ is equal to a string ''​b''​ if it contains the same number of characters, and the corresponding characters are the //​[[CL:​Glossary:​same]]//​ under **[[CL:​Functions:​char=]]** or **[[CL:​Functions:​char-equal]]**,​ as appropriate.
 +
 +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 **[[CL:​Functions:​char-lessp|char<​]]** or **[[CL:​Functions:​char-lessp]]** as appropriate,​ or if string ''​a''​ is a proper prefix of string ''​b''​ (of shorter length and matching in all the characters of ''​a''​).
 +
 +The equality functions return a //​generalized boolean// that is //​[[CL:​Glossary:​true]]//​ if the strings are equal, or //​[[CL:​Glossary:​false]]//​ otherwise.
 +
 +The inequality functions return a //​mismatch-index//​ that is //​[[CL:​Glossary:​true]]//​ if the strings are not equal, or //​[[CL:​Glossary:​false]]//​ otherwise. When the //​mismatch-index//​ is //​[[CL:​Glossary:​true]]//,​ it is an //​[[CL:​Glossary:​integer]]//​ representing the first character position at which the two substrings differ, as an offset from the beginning of //​string1//​.
 +
 +The comparison has one of the following results:
 +
 +  * **string=** is //​[[CL:​Glossary:​true]]//​ if the supplied substrings are of the same length and contain the //​[[CL:​Glossary:​same]]//​ characters in corresponding positions; otherwise it is //​[[CL:​Glossary:​false]]//​.
 +  * **string/​=** is //​[[CL:​Glossary:​true]]//​ if the supplied substrings are different; otherwise it is //​[[CL:​Glossary:​false]]//​.
 +  * **string-equal** is just like **string=** except that differences in case are ignored; two characters are considered to be the same if **[[CL:​Functions:​char-equal]]** is //​[[CL:​Glossary:​true]]//​ of them.
 +  * **string-not-equal** is just like **string/​=** except that differences in case are ignored; two characters are considered to be the same if **[[CL:​Functions:​char-equal]]** is //​[[CL:​Glossary:​true]]//​ of them.
 +  * **string<​** is //​[[CL:​Glossary:​true]]//​ if //​substring1//​ is less than //​substring2//;​ otherwise it is //​[[CL:​Glossary:​false]]//​.
 +  * **string>​** is //​[[CL:​Glossary:​true]]//​ if //​substring1//​ is greater than //​substring2//;​ otherwise it is //​[[CL:​Glossary:​false]]//​.
 +  * **string-lessp** and **string-greaterp** are exactly like **string<​** and **string>​**,​ respectively,​ except that distinctions between uppercase and lowercase letters are ignored. It is as if **[[CL:​Functions:​char-lessp]]** were used instead of **[[CL:​Functions:​char<​]]** for comparing characters.
 +  * **string<​=** is //​[[CL:​Glossary:​true]]//​ if //​substring1//​ is less than or equal to //​substring2//;​ otherwise it is //​[[CL:​Glossary:​false]]//​.
 +  * **string>​=** is //​[[CL:​Glossary:​true]]//​ if //​substring1//​ is greater than or equal to //​substring2//;​ otherwise it is //​[[CL:​Glossary:​false]]//​.
 +  * **string-not-greaterp** and **string-not-lessp** are exactly like **string<​=** and **string>​=**,​ respectively,​ except that distinctions between uppercase and lowercase letters are ignored. It is as if **[[CL:​Functions:​char-lessp]]** were used instead of **[[CL:​Functions:​char-lessp|char<​]]** for comparing characters.
 +
 +====Examples====
 +<​blockquote> ​
 +(string= "​foo"​ "​foo"​) → //​[[CL:​Glossary:​true]]//​
 +(string= "​foo"​ "​Foo"​) → //​[[CL:​Glossary:​false]]//​
 +(string= "​foo"​ "​bar"​) → //​[[CL:​Glossary:​false]]//​
 +(string-equal "​foo"​ "​Foo"​) → //​[[CL:​Glossary:​true]]//​
 +(string= "​together"​ "​frog"​ :start1 1 :end1 3 :start2 2) → //​[[CL:​Glossary:​true]]//​
 +(string= "​abcd"​ "​01234abcd9012"​ :start2 5 :end2 9) → //​[[CL:​Glossary:​true]]//​
 +(string< "​aaaa"​ "​aaab"​) → 3
 +(string>​= "​aaaaa"​ "​aaaa"​) → 4
 +(string-not-greaterp "​Abcde"​ "​abcdE"​) → 5
 +(string-lessp "​012AAAA789"​ "​01aaab6"​ :start1 3 :end1 7 :start2 2 :end2 6) → 6 
 +(string-not-equal "​AAAA"​ "​aaaA"​) → //​[[CL:​Glossary:​false]]//​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​char-equal|Function char=]]**
 +
 +====Notes====
 +**[[CL:​Functions:​equal]]** calls **string=** if applied to two //​[[CL:​Glossary:​strings]]//​.
 +
 +\issue{STRING-COERCION:​MAKE-CONSISTENT} \issue{SUBSEQ-OUT-OF-BOUNDS} \issue{RANGE-OF-START-AND-END-PARAMETERS:​INTEGER-AND-INTEGER-NIL}