6.1 Searching and Matching Strings

This section describes procedures for searching a string, either for a character or a substring, and matching two strings to one another.

procedure: string-search-forward pattern string [start [end]]

The arguments pattern and string must satisfy string-in-nfc?.

Searches string for the leftmost occurrence of the substring pattern. If successful, the index of the first character of the matched substring is returned; otherwise, #f is returned.

(string-search-forward "rat" "pirate")
    ⇒ 2
(string-search-forward "rat" "pirate rating")
    ⇒ 2
(string-search-forward "rat" "pirate rating" 4 13)
    ⇒ 7
(string-search-forward "rat" "pirate rating" 9 13)
    ⇒ #f

procedure: string-search-backward pattern string [start [end]]

The arguments pattern and string must satisfy string-in-nfc?.

Searches string for the rightmost occurrence of the substring pattern. If successful, the index to the right of the last character of the matched substring is returned; otherwise, #f is returned.

(string-search-backward "rat" "pirate")
    ⇒ 5
(string-search-backward "rat" "pirate rating")
    ⇒ 10
(string-search-backward "rat" "pirate rating" 1 8)
    ⇒ 5
(string-search-backward "rat" "pirate rating" 9 13)
    ⇒ #f

procedure: string-search-all pattern string [start [end]]

The arguments pattern and string must satisfy string-in-nfc?.

Searches string to find all occurrences of the substring pattern. Returns a list of the occurrences; each element of the list is an index pointing to the first character of an occurrence.

(string-search-all "rat" "pirate")
    ⇒ (2)
(string-search-all "rat" "pirate rating")
    ⇒ (2 7)
(string-search-all "rat" "pirate rating" 4 13)
    ⇒ (7)
(string-search-all "rat" "pirate rating" 9 13)
    ⇒ ()

procedure: substring? pattern string

Searches string to see if it contains the substring pattern. Returns #t if pattern is a substring of string, otherwise returns #f.

(substring? "rat" "pirate")             ⇒  #t
(substring? "rat" "outrage")            ⇒  #f
(substring? "" any-string)              ⇒  #t
(if (substring? "moon" text)
    (process-lunar text)
    'no-moon)

procedure: string-find-first-index proc string string …

procedure: string-find-last-index proc string string …

Each string must satisfy string-in-nfc?, and proc must accept as many arguments as there are strings.

These procedures apply proc element-wise to the elements of the strings and return the first or last index for which proc returns a true value. If there is no such index, then #f is returned.

If more than one string is given and not all strings have the same length, then only the indexes of the shortest string are tested.

procedure: string-find-next-char string char [start [end]]

procedure: string-find-next-char-ci string char [start [end]]

procedure: string-find-next-char-in-set string char-set [start [end]]

The argument string must satisfy string-in-nfc?.

These procedures search string for a matching character, starting from start and moving forwards to end. If there is a matching character, the procedures stop the search and return the index of that character. If there is no matching character, the procedures return #f.

The procedures differ only in how they match characters: string-find-next-char matches a character that is char=? to char; string-find-next-char-ci matches a character that is char-ci=? to char; and string-find-next-char-in-set matches a character that’s a member of char-set.

(string-find-next-char "Adam" #\A)           ⇒  0 
(string-find-next-char "Adam" #\A 1 4)       ⇒  #f
(string-find-next-char-ci "Adam" #\A 1 4)    ⇒  2 
(string-find-next-char-in-set my-string char-set:alphabetic)
    ⇒  start position of the first word in my-string
; Can be used as a predicate:
(if (string-find-next-char-in-set my-string
                                  (char-set #\( #\) ))
    'contains-parentheses
    'no-parentheses)

procedure: string-find-previous-char string char [start [end]]

procedure: string-find-previous-char-ci string char [start [end]]

procedure: string-find-previous-char-in-set string char-set [start [end]]

The argument string must satisfy string-in-nfc?.

These procedures search string for a matching character, starting from end and moving backwards to start. If there is a matching character, the procedures stop the search and return the index of that character. If there is no matching character, the procedures return #f.

The procedures differ only in how they match characters: string-find-previous-char matches a character that is char=? to char; string-find-previous-char-ci matches a character that is char-ci=? to char; and string-find-previous-char-in-set matches a character that’s a member of char-set.

procedure: string-match-forward string1 string2

The arguments string1 and string2 must satisfy string-in-nfc?.

Compares the two strings, starting from the beginning, and returns the number of characters that are the same. If the two strings start differently, returns 0.

(string-match-forward "mirror" "micro") ⇒  2  ; matches "mi"
(string-match-forward "a" "b")          ⇒  0  ; no match

procedure: string-match-backward string1 string2

The arguments string1 and string2 must satisfy string-in-nfc?.

Compares the two strings, starting from the end and matching toward the front, returning the number of characters that are the same. If the two strings end differently, returns 0.

(string-match-backward "bulbous" "fractious")
                                        ⇒  3  ; matches "ous"

procedure: string-prefix? string1 string2

procedure: string-prefix-ci? string1 string2

These procedures return #t if the first string forms the prefix of the second; otherwise returns #f. The -ci procedures don’t distinguish uppercase and lowercase letters.

(string-prefix? "abc" "abcdef")         ⇒  #t
(string-prefix? "" any-string)          ⇒  #t

procedure: string-suffix? string1 string2

procedure: string-suffix-ci? string1 string2

These procedures return #t if the first string forms the suffix of the second; otherwise returns #f. The -ci procedures don’t distinguish uppercase and lowercase letters.

(string-suffix? "ous" "bulbous")        ⇒  #t
(string-suffix? "" any-string)          ⇒  #t