;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Conversion to Upper or Lower Case =Text: 3CONVERSION TO UPPER OR LOWER CASE upper-case-p* 1char* 2t* if 1char* is an upper case letter with zero modifier bits. 3lower-case-p* 1char* 2t* if 1char* is an lower case letter with zero modifier bits. 3both-case-p* 1char* This Common Lisp function is defined to return 2t* if 1char* is a character which has distinct upper and lower case forms. On the Lisp Machine it returns 2t* if 1char* is a letter with zero modifier bits. 3char-upcase* 1char* If 1char*, is a lower-case alphabetic character its upper-case form is returned; otherwise, 1char* itself is returned. If font information or modifier bits are present, they are preserved. If 1char* is a fixnum, the value is a fixnum. If 1char* is a character object, the value is a character object. 3char-downcase* 1char* Similar, but converts to lower case. 3string-upcase* 1string* &key 1(start* 10)* 1end* Returns a string like 1string*, with all lower-case alphabetic characters replaced by the corresponding upper-case characters. If 1start* or 1end* is specified, only the specified portion of the string is converted, but in any case the entire string is returned. The result is a copy of 1string* unless no change is necessary. 1string* itself is never modified. 3string-downcase* 1string* &key 1(start* 10)* 1end* Similar, but converts to lower case. 3string-capitalize* 1string* &key 1(start* 10)* 1end* Returns a string like 1string* in which all, or the specified portion, has been processed by capitalizing each word. For this function, a word is any maximal sequence of letters or digits. It is capitalized by putting the first character (if it is a letter) in upper case and any letters in the rest of the word in lower case. The result is a copy of 1string* unless no change is necessary. 1string* itself is never modified. 3nstring-upcase* 1string* &key 1(start* 10)* 1end* 3nstring-downcase* 1string* &key 1(start* 10)* 1end* 3nstring-capitalize* 1string* &key 1(start* 10)* 1end* Like the previous functions except that they modify 1string* itself and return it. 3string-capitalize-words* 1string* &optional 1(copy-p* 1t)* 1(spaces* 1t)* Puts each word in 1string* into lower-case with an upper case initial, and if 1spaces* is non-2nil* replaces each hyphen character with a space. If 1copy-p* is 2t*, the value is a copy of 1string*, and 1string* itself is unchanged. Otherwise, 1string* itself is returned, with its contents changed. This function is somewhat obsolete. One can use 2string-capitalize* followed optionally by 2string-subst-char*. See also the 2format* operation 2~(*...2~)* on 4(IOSYSTEM-3)The Format Function*. =Node: Basic String Operations =Text: 3BASIC STRING OPERATIONS make-string* 1size* &key 1(initial-element* 10)* Creates and returns a string of length 1size*, with each element initialized to 1initial-element*, which may be a fixnum or a character. 3string* 1x* Coerces 1x* into a string. Most of the string functions apply this to their string arguments. If 1x* is a string (or any array), it is returned. If 1x* is a symbol, its pname is returned. If 1x* is a non-negative fixnum less than 400 octal, a one-character-long string containing it is created and returned. If 1x* is an instance that supports the 2:string-for-printing* operation (such as, a pathname) then the result of that operation is returned. Otherwise, an error is signaled. If you want to get the printed representation of an object into the form of a string, this function is 1not* what you should use. You can use 2format*, passing a first argument of 2nil* (see 4(IOSYSTEM-3)The Format Function*). You might also want to use 2with-output-to-string* (see 4(IOSYSTEM-2)String I/O Streams*). 3string-length* 1string* Returns the number of characters in 1string*. This is 1 if 1string* is a number or character object, the 2array-active-length* (see 4(ARRAYS-2)Getting Information About an Array*) if 1string* is an array, or the 2array-active-length* of the pname if 1string* is a symbol. 3string-equal* 1string1* 1string2* &key 1(start1* 10)* 1(start2* 10)* 1end1* 1end2* Compares two strings, returning 2t* if they are equal and 2nil* if they are not. The comparison ignores the font and case of the characters. 2equal* calls 2string-equal* if applied to two strings. The keyword arguments 1start1* and 1start2* are the starting indices into the strings. 1end1* and 1end2* are the final indices; the comparison stops just 1before* the final index. 2nil* for 1end1* or 1end2* means stop at the end of the string. Examples: 3(string-equal "Foo" "foo") => t* 3(string-equal "foo" "bar") => nil* 3(string-equal "element" "select" 0 1 3 4) => t* An older calling sequence in which the 1start* and 1end* arguments are positional rather than keyword is still supported. The arguments come in the order 1start1* 1start2* 1end1* 1end2*. This calling sequence is obsolete and should be changed whenever found. 3string-not-equal* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 2(not (string-equal ...))* 3string=* 1string1* 1string2* &key 1(start1* 10)* 1(start2* 10)* 1end1* 1end2* is like 2string-equal* except that case is significant. 3(string= "A" "a") => nil string* 1* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string//=* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 2(not (string= ...))*. Note that in Common Lisp syntax you would write 2string/=*, not 2string//=*. 3string-lessp* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string-greaterp* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string-not-greaterp* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string-not-lessp* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* Compare all or the specified portions of 1string1* and 1string2* using dictionary order. Characters are compared using 2char-lessp* and 2char-equal* so that font and alphabetic case are ignored. You can use these functions as predicates, but they do more. If the strings fit the condition (e.g. 1string1* is strictly less in 2string-lessp*) then the value is a number, the index in 1string1* of the first point of difference between the strings. This equals the length of 1string1* if the strings match. If the condition is not met, the value is 2nil*. 3(string-lessp "aa" "Ab") => 1* 3(string-lessp "aa" "Ab" :end1 1 :end2 1) => nil* 3(string-not-greaterp "Aa" "Ab" :end1 1 :end2 1) => 1 string<* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string>* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string>=* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string<=* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string* 1* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* 3string* 1* 1string1* 1string2* &key 1(start1* 10)* 1end1* 1(start2* 10)* 1end2* Like 2string-lessp*, etc., but treat case and font as significant when comparing characters. 3(string< "AA" "aa") => 0* 3(string-lessp "AA" "aa") => nil string-compare* 1string1* 1string2* &optional 1(start1* 10)* 1(start2* 10)* 1end1* 1end2* Compares two strings using dictionary order (as defined by 2char-lessp*). The arguments are interpreted as in 2string-equal*. The result is 20* if the strings are equal, a negative number if 1string1* is less than 1string2*, or a positive number if 1string1* is greater than 1string2*. If the strings are not equal, the absolute value of the number returned is one greater than the index (in 1string1*) where the first difference occurred. 3substring* 1string* 1start* &optional 1end* 1area* Extracts a substring of 1string*, starting at the character specified by 1start* and going up to but not including the character specified by 1end*. 1start* and 1end* are 0-origin indices. The length of the returned string is 1end* minus 1start*. If 1end* is not specified it defaults to the length of 1string*. The area in which the result is to be consed may be optionally specified. Example: 3(substring "Nebuchadnezzar" 4 8) => "chad" nsubstring* 1string* 1start* &optional 1end* 1area* Is like 2substring* except that the substring is not copied; instead an indirect array (see 4(ARRAYS-1)Displaced Arrays*) is created which shares part of the argument 1string*. Modifying one string will modify the other. Note that 2nsubstring* does not necessarily use less storage than 2substring*; an 2nsubstring* of any length uses at least as much storage as a 2substring* 12 characters long. So you shouldn't use this for efficiency; it is intended for uses in which it is important to have a substring which, if modified, will cause the original string to be modified too. 3string-append* &rest 1strings* Copies and concatenates any number of strings into a single string. With a single argument, 2string-append* simply copies it. If there are no arguments, the value is an empty string. In fact, vectors of any type may be used as arguments, and the value is a vector capable of holding all the elements of all the arguments. Thus 2string-append* can be used to copy and concatenate any type of vector. If the first argument is not an array (for example, if it is a character), the value is a string. Example: 3(string-append #\! "foo" #\!) => "!foo!" string-nconc* 1modified-string* &rest 1strings* Is like 2string-append* except that instead of making a new string containing the concatenation of its arguments, 2string-nconc* modifies its first argument. 1modified-string* must have a fill-pointer so that additional characters can be tacked onto it. Compare this with 2array-push-extend* (4(ARRAYS-2)Adding to the End of an Array*). The value of 2string-nconc* is 1modified-string* or a new, longer copy of it; in the latter case the original copy is forwarded to the new copy (see 2adjust-array-size*, 4(ARRAYS-2)Changing the Size of an Array*). Unlike 2nconc*, 2string-nconc* with more than two arguments modifies only its first argument, not every argument but the last. 3string-trim* 1char-set* 1string* Returns a 2substring* of 1string*, with all characters in 1char-set* stripped off the beginning and end. 1char-set* is a set of characters, which can be represented as a list of characters, a string of characters or a single character. Example: 3(string-trim '(#\sp) " Dr. No ") => "Dr. No"* 3(string-trim "ab" "abbafooabb") => "foo" string-left-trim* 1char-set* 1string* Returns a 2substring* of 1string*, with all characters in 1char-set* stripped off the beginning. 1char-set* is a set of characters, which can be represented as a list of characters, a string of characters or a single character. 3string-right-trim* 1char-set* 1string* Returns a 2substring* of 1string*, with all characters in 1char-set* stripped off the end. 1char-set* is a set of characters, which can be represented as a list of characters, a string of characters or a single character. 3string-remove-fonts* 1string* Returns a copy of 1string* with each character truncated to 8 bits; that is, changed to font zero. If 1string* is an ordinary string of array type 2art-string*, this does not change anything, but it makes a difference if 1string* is an 2art-fat-string*. 3string-reverse* 1string* 3string-nreverse* 1string* Like 2reverse* and 2nreverse*, but on strings only (see 4(GENERIC-1)Simple Sequence Operations*). There is no longer any reason to use these functions except that they coerce numbers and symbols into strings like the other string functions. 3string-pluralize* 1string* Returns a string containing the plural of the word in the argument 1string*. Any added characters go in the same case as the last character of 1string*. Example: 3(string-pluralize "event") => "events"* 3(string-pluralize "trufan") => "trufen"* 3(string-pluralize "Can") => "Cans"* 3(string-pluralize "key") => "keys"* 3(string-pluralize "TRY") => "TRIES"* For words with multiple plural forms depending on the meaning, 2string-pluralize* cannot always do the right thing. 3string-select-a-or-an* 1word* Returns 2"a"* or 2"an"* according to the string 1word*; whichever one appears to be correct to use before 1word* in English. 3string-append-a-or-an* 1word* Returns the result of appending 2"a "* or 2"an "*, whichever is appropriate, to the front of 1word*. 3%string-equal* 1string1* 1start1* 1string2* 1start2* 1count* 2%string-equal* is the microcode primitive used by 2string-equal*. It returns 2t* if the 1count* characters of 1string1* starting at 1start1* are 2char-equal* to the 1count* characters of 1string2* starting at 1start2*, or 2nil* if the characters are not equal or if 1count* runs off the length of either array. Instead of a fixnum, 1count* may also be 2nil*. In this case, 2%string-equal* compares the substring from 1start1* to 2(string-length 1string1*)* against the substring from 1start2* to 2(string-length 1string2*)*. If the lengths of these substrings differ, then they are not equal and 2nil* is returned. Note that 1string1* and 1string2* must really be strings; the usual coercion of symbols and fixnums to strings is not performed. This function is documented because certain programs which require high efficiency and are willing to pay the price of less generality may want to use 2%string-equal* in place of 2string-equal*. Examples: 2To compare the two strings 1foo* and 1bar*:* 3(%string-equal 1foo* 0 1bar* 0 nil)* 2To see if the string 1foo* starts with the characters "bar":* 3(%string-equal 1foo* 0 "bar" 0 3) alphabetic-case-affects-string-comparison* 1Variable* If this variable is 2t*, the functions 2%string-equal* and 2%string-search* consider case (and font) significant in comparing characters. Normally this variable is 2nil* and those primitives ignore differences of case. This variable may be bound by user programs around calls to 2%string-equal* and 2%string-search-char*, but do not set it globally, for that may cause system malfunctions. =Node: String Searching =Text: 3STRING SEARCHING string-search-char* 1char* 1string* &optional 1(from* 10)* 1to* 1consider-case* Searches through 1string* starting at the index 1from*, which defaults to the beginning, and returns the index of the first character that is 2char-equal* to 1char*, or 2nil* if none is found. If 1to* is non-2nil*, it is used in place of 2(string-length 1string*)* to limit the extent of the search. Example: 3(string-search-char #\a "banana") => 1* Case (and font) is significant in comparison of characters if 1consider-case* is non-2nil*. In other words, characters are compared using 2char=* rather than 2char-equal*. 3(string-search-char #\a "BAnana" 0 nil t) => 3 %string-search-char* 1char* 1string* 1from* 1to* 2%string-search-char* is the microcode primitive called by 2string-search-char* and other functions. 1string* must be an array and 1char*, 1from*, and 1to* must be fixnums. The arguments are all required. Case-sensitivity is controlled by the value of the variable 2alphabetic-case-affects-string-comparison* rather than by an argument. Except for these these differences, 2%string-search-char* is the same as 2string-search-char*. This function is documented for the benefit of those who require the maximum possible efficiency in string searching. 3string-search-not-char* 1char* 1string* &optional 1(from* 10)* 1to* 1consider-case* Like 2string-search-char* but searches 1string* for a character different from 1char*. Example: 3(string-search-not-char #\B "banana") => 1* 3(string-search-not-char #\B "banana" 0 nil t) => 0 string-search* 1key* 1string* &optional 1(from* 10)* 1to* 1(key-from* 10)* 1key-to* 1consider-case* Searches for the string 1key* in the string 1string*. The search begins at 1from*, which defaults to the beginning of 1string*. The value returned is the index of the first character of the first instance of 1key*, or 2nil* if none is found. If 1to* is non-2nil*, it is used in place of 2(string-length* 1string2)** to limit the extent of the search. The arguments 1key-from* and 1key-to* can be used to specify the portion of 1key* to be searched for, rather than all of 1key*. Case and font are significant in character comparison if 1consider-case* is non-2nil*. Example: 3(string-search "an" "banana") => 1* 3(string-search "an" "banana" 2) => 3* 3(string-search "tank" "banana" 2 nil 1 3) => 3* 3(string-search "an" "BAnaNA" 0 nil 0 nil t) => nil string-search-set* 1char-set* 1string* &optional 1(from* 10)* 1to* 1consider-case* Searches through 1string* looking for a character that is in 1char-set*. 1char-set* is a set of characters, which can be represented as a sequence of characters or a single character. The search begins at the index 1from*, which defaults to the beginning. It returns the index of the first character that is 2char-equal* to some element of 1char-set*, or 2nil* if none is found. If 1to* is non-2nil*, it is used in place of 2(string-length 1string*)* to limit the extent of the search. Case and font are significant in character comparison if 1consider-case* is non-2nil*. Example: 3(string-search-set '(#\n #\o) "banana") => 2* 3(string-search-set "no" "banana") => 2 string-search-not-set* 1char-set* 1string* &optional 1(from* 10)* 1to* 1consider-case* Like 2string-search-set* but searches for a character that is 1not* in 1char-set*. Example: 3(string-search-not-set '(#\a #\b) "banana") => 2 string-reverse-search-char* 1char* 1string* &optional 1from* 1(to* 10)* 1consider-case* Searches through 1string* in reverse order, starting from the index one less than 1from* (2nil* for 1from* starts at the end of 1string*), and returns the index of the first character which is 2char-equal* to 1char*, or 2nil* if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. The last (leftmost) character of 1string* examined is the one at index 1to*. Case and font are significant in character comparison if 1consider-case* is non-2nil*. In this case, 2char=* is used for the comparison rather than 2char-equal*. Example: 3(string-reverse-search-char #\n "banana") => 4 string-reverse-search-not-char* 1char* 1string* &optional 1from* 1(to* 10)* 1consider-case* Like 2string-reverse-search-char* but searches for a character in 1string* that is different from 1char*. Example: 3(string-reverse-search-not-char #\a "banana") => 4* 3;24 is the index of the second "n"* string-reverse-search* 1key* 1string* &optional 1from* 1(to* 10)* 1(key-from* 10)* 1key-to* 1consider-case* Searches for the string 1key* in the string 1string*. The search proceeds in reverse order, starting from the index one less than 1from*, and returns the index of the first (leftmost) character of the first instance found, or 2nil* if none is found. Note that the index returned is from the beginning of the string, although the search starts from the end. The 1from* condition, restated, is that the instance of 1key* found is the rightmost one whose rightmost character is before the 1from*'th character of 1string*. 2nil* for 1from* means the search starts at the end of 1string*. The last (leftmost) character of 1string* examined is the one at index 1to*. Example: 3(string-reverse-search "na" "banana") => 4* The arguments 1key-from* and 1key-to* can be used to specify the portion of 1key* to be searched for, rather than all of 1key*. Case and font are significant in character comparison if 1consider-case* is non-2nil*. 3string-reverse-search-set* 1char-set* 1string* &optional 1from* 1(to* 10)* 1consider-case* Searches through 1string* in reverse order for a character which is 2char-equal* to some element of 1char-set*. 1char-set* is a set of characters, which can be represented as a list of characters, a string of characters or a single character. The search starts from an index one less than 1from*, and returns the index of the first suitable character found, or 2nil* if none is found. 2nil* for 1from* means the search starts at the end of 1string*. Note that the index returned is from the beginning of the string, although the search starts from the end. The last (leftmost) character of 1string* examined is the one at index 1to*. Case and font are significant in character comparison if 1consider-case* is non-2nil*. In this case, 2char=* is used for the comparison rather than 2char-equal*. 3(string-reverse-search-set "ab" "banana") => 5 string-reverse-search-not-set* 1char-set* 1string* &optional 1from* 1(to* 10)* 1consider-case* Like 2string-reverse-search-set* but searches for a character which is 1not* in 1char-set*. 3(string-reverse-search-not-set '(#\a #\n) "banana") => 0 string-subst-char* 1new-char* 1old-char* 1string* 1(copy-p* 1t)* 1(retain-font-p* 1t)* Returns a copy of 1string* in which all occurrences of 1old-char* have been replaced by 1new-char*. Case and font are ignored in comparing 1old-char* against characters of 1string*. Normally the font information of the character replaced is preserved, so that an 1old-char* in font 3 is replaced by a 1new-char* in font 3. If 1retain-font-p* is 2nil*, the font specified in 1new-char* is stored whenever a character is replaced. If 1copy-p* is 2nil*, 1string* is modified destructively and returned. No copy is made. 3substring-after-char* 1char* 1string* &optional 1start* 1end* 1area* Returns a copy of the portion of 1string* that follows the next occurrence of 1char* after index 1start*. The portion copied ends at index 1end*. If 1char* is not found before 1end*, a null string is returned. The value is consed in area 1area*, or in 2default-cons-area*, unless it is a null string. 1start* defaults to zero, and 1end* to the length of 1string*. See also 2make-symbol* (4(SYMBOLS-1)Creating Symbols*), which given a string makes a new uninterned symbol with that print name, and 2intern* (4(PACKAGES-2)Packages and Interning*), which given a string returns the one and only symbol (in the current package) with that print name. =Node: Maclisp-Compatible Functions =Text: 3MACLISP-COMPATIBLE FUNCTIONS* The following functions are provided primarily for Maclisp compatibility. 3alphalessp* 1string1* 1string2* 2(alphalessp 1string1 string2*)* is equivalent to 2(string-lessp 1string1 string2*)*. 3samepnamep* 1sym1* 1sym2* This predicate is equivalent to 2string=*. 3getchar* 1string* 1index* Returns the 1index*'th character of 1string* as a symbol. Note that 1-origin indexing is used. This function is mainly for Maclisp compatibility; 2aref* should be used to index into strings (but 2aref* does not coerce symbols or numbers into strings). 3getcharn* 1string* 1index* Returns the 1index*'th character of 1string* as a fixnum. Note that 1-origin indexing is used. This function is mainly for Maclisp compatibility; 2aref* should be used to index into strings (but 2aref* does not coerce symbols or numbers into strings). 3ascii* 1x* Like 2character*, but returns a symbol whose printname is the character instead of returning a fixnum. Examples: 3(ascii #o101) => A* 3(ascii #o56) => /.* The symbol returned is interned in the current package (see 4(PACKAGES-0)Packages*). 3maknam* 1char-list* Returns an uninterned symbol whose print-name is a string made up of the characters in 1char-list*. Example: 3(maknam '(a b #\0 d)) => ab0d implode* 1char-list* 2implode* is like 2maknam* except that the returned symbol is interned in the current package.