From: Chris Hanson Date: Wed, 22 Feb 2017 01:52:06 +0000 (-0800) Subject: First round of changes to Strings chapter. X-Git-Tag: mit-scheme-pucked-9.2.12~220^2~34 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=3949455e91554855e4904620a535f74c551846a4;p=mit-scheme.git First round of changes to Strings chapter. --- diff --git a/doc/ref-manual/scheme.texinfo b/doc/ref-manual/scheme.texinfo index 6e8fdc15a..f46e8a40c 100644 --- a/doc/ref-manual/scheme.texinfo +++ b/doc/ref-manual/scheme.texinfo @@ -216,17 +216,9 @@ Characters Strings -* Construction of Strings:: -* Selecting String Components:: -* Comparison of Strings:: -* Alphabetic Case in Strings:: -* Cutting and Pasting Strings:: * Searching Strings:: * Matching Strings:: * Regular Expressions:: -* Modification of Strings:: -* Variable-Length Strings:: -* Byte Vectors:: Regular Expressions diff --git a/doc/ref-manual/strings.texi b/doc/ref-manual/strings.texi index ff98e5d1e..882a07015 100644 --- a/doc/ref-manual/strings.texi +++ b/doc/ref-manual/strings.texi @@ -1,14 +1,13 @@ @node Strings, Lists, Characters, Top @chapter Strings -@cindex string, character (defn) -@findex char-ascii? -A @dfn{string} is a mutable sequence of characters. In the current -implementation of MIT/GNU Scheme, the elements of a string must all -satisfy the predicate @code{char-ascii?}; if someone ports MIT/GNU -Scheme to a non-@acronym{ASCII} operating system this requirement will -change. +@menu +* Searching Strings:: +* Matching Strings:: +* Regular Expressions:: +@end menu +@cindex string, character (defn) @cindex external representation, for string @cindex " as external representation @cindex double quote, as external representation @@ -16,305 +15,191 @@ change. @cindex backslash, as escape character in string @cindex escape character, for string @findex " -@findex \ -A string is written as a sequence of characters enclosed within double -quotes @code{" "}. To include a double quote inside a string, precede -the double quote with a backslash @code{\} (escape it), as in - -@example -"The word \"recursion\" has many meanings." -@end example - -@noindent -The printed representation of this string is +Strings are sequences of characters. Strings are written as sequences +of characters enclosed within quotation marks (@code{"}). Within a +string literal, various escape sequences represent characters other +than themselves. Escape sequences always start with a backslash +(@code{\}): -@example -The word "recursion" has many meanings. -@end example +@display +@group +@code{\a} : alarm, U+0007 +@code{\b} : backspace, U+0008 +@code{\t} : character tabulation, U+0009 +@code{\n} : linefeed, U+000A +@code{\r} : return, U+000D +@code{\"} : double quote, U+0022 +@code{\\} : backslash, U+005C +@code{\|} : vertical line, U+007C +@code{\}@var{intraline-whitespace}* @var{line-ending} @var{intraline-whitespace}* + : nothing +@code{\x}@var{hex-scalar-value}@code{;} + : specified character (note the terminating semi-colon). +@end group +@end display +@findex \a +@findex \b +@findex \t +@findex \n +@findex \r +@findex \" +@findex \\ +@findex \| +@findex \x -@noindent -To include a backslash inside a string, precede it with another -backslash; for example, +The result is unspecified if any other character in a string occurs +after a backslash. -@example -"Use #\\Control-q to quit." -@end example +Except for a line ending, any character outside of an escape sequence +stands for itself in the string literal. A line ending which is +preceded by @code{\}@var{intraline-whitespace} expands to nothing +(along with any trailing intraline whitespace), and can be used to +indent strings for improved legibility. Any other line ending has the +same effect as inserting a @code{\n} character into the string. -@noindent -The printed representation of this string is +Examples: @example -Use #\Control-q to quit. +@group +"The word \"recursion\" has many meanings." +"Another example:\ntwo lines of text" +"Here's text \ + containing just one line" +"\x03B1; is named GREEK SMALL LETTER ALPHA." +@end group @end example -@findex \t -@findex \n -@findex \f -@findex #\tab -@findex #\newline -@findex #\page -The effect of a backslash that doesn't precede a double quote or -backslash is unspecified in standard Scheme, but MIT/GNU Scheme specifies -the effect for three other characters: @code{\t}, @code{\n}, and -@code{\f}. These escape sequences are respectively translated into the -following characters: @code{#\tab}, @code{#\newline}, and @code{#\page}. -Finally, a backslash followed by exactly three octal digits is -translated into the character whose @acronym{ISO-8859-1} code is those -digits. - -If a string literal is continued from one line to another, the string -will contain the newline character (@code{#\newline}) at the line break. -Standard Scheme does not specify what appears in a string literal at a -line break. - @cindex length, of string (defn) @cindex index, of string (defn) @cindex valid index, of string (defn) @cindex string length (defn) @cindex string index (defn) -The @dfn{length} of a string is the number of characters that it -contains. This number is an exact non-negative integer that is -established when the string is created -(but @pxref{Variable-Length Strings}). -Each character in a string has an @dfn{index}, which is a -number that indicates the character's position in the string. The index -of the first (leftmost) character in a string is 0, and the index of the -last character is one less than the length of the string. The -@dfn{valid indexes} of a string are the exact non-negative integers less -than the length of the string. - -@cindex substring (defn) -@cindex start, of substring (defn) -@cindex end, of substring (defn) -A number of the string procedures operate on substrings. A -@dfn{substring} is a segment of a @var{string}, which is specified by -two integers @var{start} and @var{end} satisfying these relationships: - -@example -0 <= @var{start} <= @var{end} <= (string-length @var{string}) -@end example - -@noindent -@var{Start} is the index of the first character in the substring, and -@var{end} is one greater than the index of the last character in the -substring. Thus if @var{start} and @var{end} are equal, they refer to -an empty substring, and if @var{start} is zero and @var{end} is the -length of @var{string}, they refer to all of @var{string}. +The @emph{length} of a string is the number of characters that it +contains. This number is an exact, non-negative integer that is fixed +when the string is created. The @dfn{valid indexes} of a string are +the exact non-negative integers less than the length of the string. +The first character of a string has index 0, the second has index 1, +and so on. @cindex case sensitivity, of string operations @cindex -ci, in string procedure name Some of the procedures that operate on strings ignore the difference -between uppercase and lowercase. The versions that ignore case include -@samp{-ci} (for ``case insensitive'') in their names. - -@menu -* Construction of Strings:: -* Selecting String Components:: -* Comparison of Strings:: -* Alphabetic Case in Strings:: -* Cutting and Pasting Strings:: -* Searching Strings:: -* Matching Strings:: -* Regular Expressions:: -* Modification of Strings:: -* Variable-Length Strings:: -* Byte Vectors:: -@end menu +between upper and lower case. The names of the versions that ignore +case end with @samp{-ci} (for ``case insensitive''). -@node Construction of Strings, Selecting String Components, Strings, Strings -@section Construction of Strings -@cindex construction, of string +Implementations may forbid certain characters from appearing in +strings. However, with the exception of @code{#\null}, ASCII +characters must not be forbidden. For example, an implementation +might support the entire Unicode repertoire, but only allow characters +U+0001 to U+00FF (the Latin-1 repertoire without @code{#\null}) in +strings. -@deffn {procedure} make-string k [char] -Returns a newly allocated string of length @var{k}. If you specify -@var{char}, all elements of the string are initialized to @var{char}, -otherwise the contents of the string are unspecified. @var{Char} must -satisfy the predicate @code{char-ascii?}. - -@example -(make-string 10 #\x) @result{} "xxxxxxxxxx" -@end example -@end deffn - -@deffn procedure string char @dots{} -Returns a newly allocated string consisting of the specified characters. -The arguments must all satisfy @code{char-ascii?}. - -@example -@group -(string #\a) @result{} "a" -(string #\a #\b #\c) @result{} "abc" -(string #\a #\space #\b #\space #\c) @result{} "a b c" -(string) @result{} "" -@end group -@end example -@end deffn +Implementation note: MIT/GNU Scheme allows any ``bitless'' character +to be stored in a string. In effect this means any character with a +Unicode code point, including surrogates. -@deffn procedure list->string char-list -@cindex list, converting to string -@findex string->list -@var{Char-list} must be a list of @acronym{ISO-8859-1} characters. -@code{list->string} returns a newly allocated string formed from the -elements of @var{char-list}. This is equivalent to @code{(apply string -@var{char-list})}. The inverse of this operation is -@code{string->list}. +It is an error to pass such a forbidden character to +@code{make-string}, @code{string}, @code{string-set!}, or +@code{string-fill!}, as part of the list passed to +@code{list->string}, or as part of the vector passed to +@code{vector->string}, or in UTF-8 encoded form within a bytevector +passed to @code{utf8->string}. It is also an error for a procedure +passed to @code{string-map} to return a forbidden character, or for +@code{read-string} to attempt to read one. -@example -@group -(list->string '(#\a #\b)) @result{} "ab" -(string->list "Hello") @result{} (#\H #\e #\l #\l #\o) -@end group -@end example +@deffn {standard procedure} string? obj +Returns @code{#t} if @var{obj} is a string, otherwise returns @code{#f}. @end deffn -@deffn {procedure} string-copy string -@cindex copying, of string -Returns a newly allocated copy of @var{string}. - -Note regarding variable-length strings: the maximum length of the result -depends only on the length of @var{string}, not its maximum length. If -you wish to copy a string and preserve its maximum length, do the -following: - -@example -@group -(define (string-copy-preserving-max-length string) - (let ((length)) - (dynamic-wind - (lambda () - (set! length (string-length string)) - (set-string-length! string - (string-maximum-length string))) - (lambda () - (string-copy string)) - (lambda () - (set-string-length! string length))))) -@end group -@end example +@deffn {standard procedure} make-string k [char] +The @code{make-string} procedure returns a newly allocated string of +length @var{k}. If @var{char} is given, then all the characters of the string +are initialized to @var{char}, otherwise the contents of the +string are unspecified. @end deffn -@node Selecting String Components, Comparison of Strings, Construction of Strings, Strings -@section Selecting String Components -@cindex selection, of string component -@cindex component selection, of string - -@deffn procedure string? object -@cindex type predicate, for string -Returns @code{#t} if @var{object} is a string; otherwise returns -@code{#f}. - -@example -@group -(string? "Hi") @result{} #t -(string? 'Hi) @result{} #f -@end group -@end example +@deffn {standard procedure} string char @dots +Returns a newly allocated string composed of the arguments. It is +analogous to @code{list}. @end deffn -@deffn procedure string-length string -Returns the length of @var{string} as an exact non-negative integer. - -@example -@group -(string-length "") @result{} 0 -(string-length "The length") @result{} 10 -@end group -@end example +@deffn {standard procedure} string-length string +Returns the number of characters in the given @var{string}. @end deffn -@deffn procedure string-null? string -@cindex empty string, predicate for -@cindex null string, predicate for -Returns @code{#t} if @var{string} has zero length; otherwise returns -@code{#f}. +@deffn {standard procedure} string-ref string k +It is an error if @var{k} is not a valid index of @var{string}. -@example -@group -(string-null? "") @result{} #t -(string-null? "Hi") @result{} #f -@end group -@end example +The @code{string-ref} procedure returns character @var{k} of +@var{string} using zero-origin indexing. There is no requirement for +this procedure to execute in constant time. @end deffn -@deffn procedure string-ref string k -Returns character @var{k} of @var{string}. @var{K} must be a valid index -of @var{string}. - -@example -@group -(string-ref "Hello" 1) @result{} #\e -(string-ref "Hello" 5) @error{} 5 not in correct range -@end group -@end example -@end deffn +@deffn {standard procedure} string-set! string k char +It is an error if @var{k} is not a valid index of @var{string}. -@deffn {procedure} string-set! string k char -Stores @var{char} in element @var{k} of @var{string} and returns an -unspecified value. @var{K} must be a valid index of @var{string}, and -@var{char} must satisfy the predicate @code{char-ascii?}. +The @code{string-set!} procedure stores @var{char} in element @var{k} of @var{string}. +There is no requirement for this procedure to execute in constant time. @example @group -(define str "Dog") @result{} @r{unspecified} -(string-set! str 0 #\L) @result{} @r{unspecified} -str @result{} "Log" -(string-set! str 3 #\t) @error{} 3 not in correct range +(define (f) (make-string 3 #\*)) +(define (g) "***") +(string-set! (f) 0 #\?) @result{} @r{@i{unspecified}} +(string-set! (g) 0 #\?) @result{} @r{@i{error}} +(string-set! (symbol->string 'immutable) 0 #\?) @result{} @r{@i{error}} @end group @end example @end deffn -@need 1000 -@node Comparison of Strings, Alphabetic Case in Strings, Selecting String Components, Strings -@section Comparison of Strings -@cindex ordering, of strings -@cindex comparison, of strings - -@deffn procedure string=? string1 string2 -@deffnx procedure substring=? string1 start end string2 start end -@deffnx {procedure} string-ci=? string1 string2 -@deffnx procedure substring-ci=? string1 start end string2 start end -@cindex equivalence predicate, for strings -Returns @code{#t} if the two strings (substrings) are the same length -and contain the same characters in the same (relative) positions; -otherwise returns @code{#f}. @code{string-ci=?} and -@code{substring-ci=?} don't distinguish uppercase and lowercase letters, -but @code{string=?} and @code{substring=?} do. - -@example -@group -(string=? "PIE" "PIE") @result{} #t -(string=? "PIE" "pie") @result{} #f -(string-ci=? "PIE" "pie") @result{} #t -(substring=? "Alamo" 1 3 "cola" 2 4) @result{} #t @r{; compares "la"} -@end group -@end example +@deffn {standard procedure} string=? string1 string2 string @dots +Returns @code{#t} if all the strings are the same length and contain +exactly the same characters in the same positions, otherwise returns +@code{#f}. @end deffn -@deffn procedure string? string1 string2 -@deffnx procedure string<=? string1 string2 -@deffnx procedure string>=? string1 string2 -@deffnx {procedure} string-ci? string1 string2 -@deffnx {procedure} string-ci<=? string1 string2 -@deffnx {procedure} string-ci>=? string1 string2 -These procedures compare strings (substrings) according to the order of -the characters they contain (also @pxref{Characters}). -The arguments are compared using a lexicographic (or dictionary) order. -If two strings differ in length but are the same up to the length of the -shorter string, the shorter string is considered to be less than the -longer string. - -@example -@group -(string? "catkin" "cat") @result{} #t @r{; shorter is lesser} -@end group -@end example +@deffn {standard procedure} string-ci=? string1 string2 string @dots +Returns @code{#t} if, after case-folding, all the strings are the same +length and contain the same characters in the same positions, +otherwise returns @code{#f}. Specifically, these procedures behave as +if @code{string-foldcase} were applied to their arguments before +comparing them. +@end deffn + +@deffn {standard procedure} string? string1 string2 string @dots +@deffnx {standard procedure} string-ci>? string1 string2 string @dots +@deffnx {standard procedure} string<=? string1 string2 string @dots +@deffnx {standard procedure} string-ci<=? string1 string2 string @dots +@deffnx {standard procedure} string>=? string1 string2 string @dots +@deffnx {standard procedure} string-ci>=? string1 string2 string @dots +These procedures return @code{#t} if their arguments are (respectively): +monotonically increasing, monotonically decreasing, +monotonically non-decreasing, or monotonically non-increasing. + +These predicates are required to be transitive. + +These procedures compare strings in an implementation-defined way. +One approach is to make them the lexicographic extensions to strings +of the corresponding orderings on characters. In that case, +@code{string?}, and must satisfy +@code{string<=?} if and only if they do not satisfy @code{string>?} and +@code{string>=?} if and only if they do not satisfy @code{stringlist string [start [end]] +@deffnx {standard procedure} list->string list +It is an error if any element of @var{list} is not a character. -@example -@group -(define str "ABCDEFG") @result{} @r{unspecified} -(substring-downcase! str 3 5) @result{} @r{unspecified} -str @result{} "ABCdeFG" -@end group -@end example +The @code{string->list} procedure returns a newly allocated list of +the characters of @var{string} between @var{start} and @var{end}. +@code{list->string} returns a newly allocated string formed from the +elements in the list @var{list}. In both procedures, order is +preserved. @code{string->list} and @code{list->string} are inverses +so far as @code{equal?} is concerned. @end deffn -@deffn procedure string-upcase string -@deffnx procedure string-upcase! string -@deffnx procedure substring-upcase! string start end -@code{string-upcase} returns a newly allocated copy of @var{string} in -which all lowercase letters are changed to uppercase. -@code{string-upcase!} is the destructive version of -@code{string-upcase}: it alters @var{string} and returns an unspecified -value. @code{substring-upcase!} destructively changes the case of the -specified part of @var{string}. +@deffn {standard procedure} string-copy string [start [end]] +Returns a newly allocated copy of the part of the given @var{string} +between @var{start} and @var{end}. @end deffn -@node Cutting and Pasting Strings, Searching Strings, Alphabetic Case in Strings, Strings -@section Cutting and Pasting Strings -@cindex cutting, of string -@cindex pasting, of strings +@deffn {standard procedure} string-copy! to at from [start [end]] +It is an error if @var{at} is less than zero or greater than the +length of @var{to}. It is also an error if @code{(- (string-length +@var{to}) @var{at})} is less than @code{(- @var{end} @var{start})}. -@deffn {procedure} string-append string @dots{} -@cindex appending, of strings -Returns a newly allocated string made from the concatenation of the given -strings. With no arguments, @code{string-append} returns the empty -string (@code{""}). +Copies the characters of string @var{from} between @var{start} and +@var{end} to string @var{to}, starting at @var{at}. The order in +which characters are copied is unspecified, except that if the source +and destination overlap, copying takes place as if the source is first +copied into a temporary string and then into the destination. This +can be achieved without allocating storage by making sure to copy in +the correct direction in such circumstances. @example @group -(string-append) @result{} "" -(string-append "*" "ace" "*") @result{} "*ace*" -(string-append "" "" "") @result{} "" -(eq? str (string-append str)) @result{} #f @r{; newly allocated} +(define a "12345") +(define b (string-copy "abcde")) +(string-copy! b 1 a 0 2) +b @result{} "a12de"% @end group @end example @end deffn -@deffn procedure substring string start end -Returns a newly allocated string formed from the characters of -@var{string} beginning with index @var{start} (inclusive) and ending -with @var{end} (exclusive). +@deffn {standard procedure} string-fill! string fill [start [end]] +It is an error if @var{fill} is not a character. + +The @code{string-fill!} procedure stores @var{fill} in the elements of +@var{string} between @var{start} and @var{end}. +@end deffn + +@deffn procedure string-slice string [start [end]] +@cindex slice, of string +@cindex string slice +Returns a @dfn{slice} of @var{string}, restricted to the range of +characters specified by @var{start} and @var{end}. + +A slice is a kind of string that provides a view into another string. +The slice behaves like any other string, but changes to a slice are +reflected in the original string and vice versa. @example @group -(substring "" 0 0) @result{} "" -(substring "arduous" 2 5) @result{} "duo" -(substring "arduous" 2 8) @error{} 8 not in correct range +(define foo (string #\a #\b #\c #\d #\e)) +foo @result{} "abcde" + +(define bar (string-slice foo 1 4)) +bar @result{} "bcd" -(define (string-copy s) - (substring s 0 (string-length s))) +(string-set! foo 2 #\z) +foo @result{} "abzde" +bar @result{} "bzd" + +(string-set! bar 1 #\y) +bar @result{} "byd" +foo @result{} "abyde" @end group @end example @end deffn -@deffn procedure string-head string end -Returns a newly allocated copy of the initial substring of @var{string}, -up to but excluding @var{end}. It could have been defined by: +@ignore + +@deffn string object @dots{} +@deffn string* objects +@deffn string->vector string [start [end]] +@deffn vector->string vector [start [end]] + +@deffn string-joiner infix [prefix [suffix]] +@deffn string-joiner* infix [prefix [suffix]] +@deffn string-splitter delimiter [allow-runs?] + +@deffn string-any proc string1 string @dots{} +@deffn string-count proc string1 string @dots{} +@deffn string-every proc string1 string @dots{} +@deffn string-find-first-index proc string1 string @dots{} +@deffn string-find-last-index proc string1 string @dots{} +@deffn string-for-each proc string1 string @dots{} +@deffn string-map proc string1 string @dots{} + +@end ignore + +@deffn procedure string-null? string +@cindex empty string, predicate for +@cindex null string, predicate for +Returns @code{#t} if @var{string} has zero length; otherwise returns +@code{#f}. @example @group -(define (string-head string end) - (substring string 0 end)) +(string-null? "") @result{} #t +(string-null? "Hi") @result{} #f @end group @end example @end deffn -@deffn procedure string-tail string start -Returns a newly allocated copy of the final substring of @var{string}, -starting at index @var{start} and going to the end of @var{string}. It -could have been defined by: +@deffn procedure string-hash string [modulus] +@cindex hashing, of string +@findex string=? +@findex = +@code{string-hash} returns an exact non-negative integer that can be used +for storing the specified @var{string} in a hash table. Equal strings +(in the sense of @code{string=?}) return equal (@code{=}) hash codes, +and non-equal but similar strings are usually mapped to distinct hash +codes. -@example -@group -(define (string-tail string start) - (substring string start (string-length string))) +If the optional argument @var{modulus} is specified, it must be an +exact positive integer, and the result of @code{string-hash} is +restricted to be less than that value. This is equivalent to calling +@code{modulo} on the result, but may be faster. +@end deffn -(string-tail "uncommon" 2) @result{} "common" -@end group -@end example +@deffn procedure string-head string end +Equivalent to @code{(string-copy @var{string} 0 @var{end})}. +@end deffn + +@deffn procedure string-tail string start +Equivalent to @code{(string-copy @var{string} @var{start})}. @end deffn @deffn procedure string-pad-left string k [char] @@ -561,6 +461,24 @@ defaults to @code{char-set:not-whitespace}. @end example @end deffn +@deffn procedure string-replace string char1 char2 +Returns a newly allocated string containing the same characters as +@var{string} except that all instances of @var{char1} have been +replaced by @var{char2}. +@end deffn + +@deffn procedure reverse-string string +Returns a newly allocated string with the same characters as +@var{string} but in the reverse order. + +@example +@group +(reverse-string "foo bar baz") @result{} "zab rab oof" +(reverse-string (string-slice "foo bar baz" 4 7)) @result{} "rab" +@end group +@end example +@end deffn + @node Searching Strings, Matching Strings, Cutting and Pasting Strings, Strings @section Searching Strings @cindex searching, of string @@ -575,75 +493,61 @@ short patterns of less than 4 characters, the naive string-search algorithm is used. For longer patterns, the Boyer-Moore string-search algorithm is used. -@deffn procedure string-search-forward pattern string -@deffnx procedure substring-search-forward pattern string start end +@deffn procedure string-search-forward pattern string [start [end]] @var{Pattern} must be a string. Searches @var{string} for the leftmost occurrence of the substring @var{pattern}. If successful, the index of the first character of the matched substring is returned; otherwise, @code{#f} is returned. -@code{substring-search-forward} limits its search to the specified -substring of @var{string}; @code{string-search-forward} searches all of -@var{string}. - @example @group (string-search-forward "rat" "pirate") @result{} 2 (string-search-forward "rat" "pirate rating") @result{} 2 -(substring-search-forward "rat" "pirate rating" 4 13) +(string-search-forward "rat" "pirate rating" 4 13) @result{} 7 -(substring-search-forward "rat" "pirate rating" 9 13) +(string-search-forward "rat" "pirate rating" 9 13) @result{} #f @end group @end example @end deffn -@deffn procedure string-search-backward pattern string -@deffnx procedure substring-search-backward pattern string start end +@deffn procedure string-search-backward pattern string [start [end]] @var{Pattern} must be a string. Searches @var{string} for the rightmost occurrence of the substring @var{pattern}. If successful, the index to the right of the last character of the matched substring is returned; otherwise, @code{#f} is returned. -@code{substring-search-backward} limits its search to the specified -substring of @var{string}; @code{string-search-backward} searches all of -@var{string}. - @example @group (string-search-backward "rat" "pirate") @result{} 5 (string-search-backward "rat" "pirate rating") @result{} 10 -(substring-search-backward "rat" "pirate rating" 1 8) +(string-search-backward "rat" "pirate rating" 1 8) @result{} 5 -(substring-search-backward "rat" "pirate rating" 9 13) +(string-search-backward "rat" "pirate rating" 9 13) @result{} #f @end group @end example @end deffn -@deffn procedure string-search-all pattern string -@deffnx procedure substring-search-all pattern string start end +@deffn procedure string-search-all pattern string [start [end]] @var{Pattern} must be a string. Searches @var{string} to find all occurrences of the substring @var{pattern}. Returns a list of the occurrences; each element of the list is an index pointing to the first character of an occurrence. -@code{substring-search-all} limits its search to the specified substring -of @var{string}; @code{string-search-all} searches all of @var{string}. - @example @group (string-search-all "rat" "pirate") @result{} (2) (string-search-all "rat" "pirate rating") @result{} (2 7) -(substring-search-all "rat" "pirate rating" 4 13) +(string-search-all "rat" "pirate rating" 4 13) @result{} (7) -(substring-search-all "rat" "pirate rating" 9 13) +(string-search-all "rat" "pirate rating" 9 13) @result{} () @end group @end example @@ -730,13 +634,11 @@ returned is relative to the entire string, not just the substring. @cindex matching, of strings @deffn procedure string-match-forward string1 string2 -@deffnx procedure substring-match-forward string1 start end string2 start end @deffnx procedure string-match-forward-ci string1 string2 -@deffnx procedure substring-match-forward-ci string1 start end string2 start end -Compares the two strings (substrings), starting from the beginning, and -returns the number of characters that are the same. If the two strings -(substrings) start differently, returns 0. The @code{-ci} procedures -don't distinguish uppercase and lowercase letters. +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. The @code{-ci} procedures don't distinguish +uppercase and lowercase letters. @example @group @@ -747,14 +649,11 @@ don't distinguish uppercase and lowercase letters. @end deffn @deffn procedure string-match-backward string1 string2 -@deffnx procedure substring-match-backward string1 start end string2 start end @deffnx procedure string-match-backward-ci string1 string2 -@deffnx procedure substring-match-backward-ci string1 start end string2 start end -Compares the two strings (substrings), starting from the end and -matching toward the front, returning the number of characters that are -the same. If the two strings (substrings) end differently, returns 0. -The @code{-ci} procedures don't distinguish uppercase and lowercase -letters. +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. The @code{-ci} procedures +don't distinguish uppercase and lowercase letters. @example @group @@ -765,13 +664,11 @@ letters. @end deffn @deffn procedure string-prefix? string1 string2 -@deffnx procedure substring-prefix? string1 start1 end1 string2 start2 end2 @deffnx procedure string-prefix-ci? string1 string2 -@deffnx procedure substring-prefix-ci? string1 start1 end1 string2 start2 end2 @cindex prefix, of string -These procedures return @code{#t} if the first string (substring) forms -the prefix of the second; otherwise returns @code{#f}. The @code{-ci} -procedures don't distinguish uppercase and lowercase letters. +These procedures return @code{#t} if the first string forms the prefix +of the second; otherwise returns @code{#f}. The @code{-ci} procedures +don't distinguish uppercase and lowercase letters. @example @group @@ -782,13 +679,11 @@ procedures don't distinguish uppercase and lowercase letters. @end deffn @deffn procedure string-suffix? string1 string2 -@deffnx procedure substring-suffix? string1 start1 end1 string2 start2 end2 @deffnx procedure string-suffix-ci? string1 string2 -@deffnx procedure substring-suffix-ci? string1 start1 end1 string2 start2 end2 @cindex suffix, of string -These procedures return @code{#t} if the first string (substring) forms -the suffix of the second; otherwise returns @code{#f}. The @code{-ci} -procedures don't distinguish uppercase and lowercase letters. +These procedures return @code{#t} if the first string forms the suffix +of the second; otherwise returns @code{#f}. The @code{-ci} procedures +don't distinguish uppercase and lowercase letters. @example @group @@ -1136,203 +1031,3 @@ Returns a @acronym{REXP} that matches the same pattern as @var{rexp}, but is insensitive to character case. This has no equivalent in standard regular-expression notation. @end deffn - -@node Modification of Strings, Variable-Length Strings, Regular Expressions, Strings -@section Modification of Strings -@cindex modification, of string -@cindex replacement, of string component -@cindex filling, of string -@cindex moving, of string elements - -@deffn procedure string-replace string char1 char2 -@deffnx procedure substring-replace string start end char1 char2 -@deffnx procedure string-replace! string char1 char2 -@deffnx procedure substring-replace! string start end char1 char2 -These procedures replace all occurrences of @var{char1} with @var{char2} -in the original string (substring). @code{string-replace} and -@code{substring-replace} return a newly allocated string containing the -result. @code{string-replace!} and @code{substring-replace!} -destructively modify @var{string} and return an unspecified value. - -@example -@group -(define str "a few words") @result{} @r{unspecified} -(string-replace str #\space #\-) @result{} "a-few-words" -(substring-replace str 2 9 #\space #\-) @result{} "a few-words" -str @result{} "a few words" -(string-replace! str #\space #\-) @result{} @r{unspecified} -str @result{} "a-few-words" -@end group -@end example -@end deffn - -@deffn {procedure} string-fill! string char -Stores @var{char} in every element of @var{string} and returns an -unspecified value. -@end deffn - -@deffn procedure substring-fill! string start end char -Stores @var{char} in elements @var{start} (inclusive) to @var{end} -(exclusive) of @var{string} and returns an unspecified value. - -@example -@group -(define s (make-string 10 #\space)) @result{} @r{unspecified} -(substring-fill! s 2 8 #\*) @result{} @r{unspecified} -s @result{} " ****** " -@end group -@end example -@end deffn - -@deffn procedure substring-move-left! string1 start1 end1 string2 start2 -@deffnx procedure substring-move-right! string1 start1 end1 string2 start2 -@findex eqv? -Copies the characters from @var{start1} to @var{end1} of @var{string1} -into @var{string2} at the @var{start2}-th position. The characters are -copied as follows (note that this is only important when @var{string1} -and @var{string2} are @code{eqv?}): - -@table @code -@item substring-move-left! -The copy starts at the left end and moves toward the right (from smaller -indices to larger). Thus if @var{string1} and @var{string2} are the -same, this procedure moves the characters toward the left inside the -string. - -@item substring-move-right! -The copy starts at the right end and moves toward the left (from larger -indices to smaller). Thus if @var{string1} and @var{string2} are the -same, this procedure moves the characters toward the right inside the -string. -@end table - -The following example shows how these procedures can be used to build up -a string (it would have been easier to use @code{string-append}): -@example -@group -(define answer (make-string 9 #\*)) @result{} @r{unspecified} -answer @result{} "*********" -(substring-move-left! "start" 0 5 answer 0) @result{} @r{unspecified} -answer @result{} "start****" -(substring-move-left! "-end" 0 4 answer 5) @result{} @r{unspecified} -answer @result{} "start-end" -@end group -@end example -@end deffn - -@deffn procedure reverse-string string -@deffnx procedure reverse-substring string start end -@deffnx procedure reverse-string! string -@deffnx procedure reverse-substring! string start end -Reverses the order of the characters in the given string or substring. -@code{reverse-string} and @code{reverse-substring} return newly -allocated strings; @code{reverse-string!} and @code{reverse-substring!} -modify their argument strings and return an unspecified value. - -@example -@group -(reverse-string "foo bar baz") @result{} "zab rab oof" -(reverse-substring "foo bar baz" 4 7) @result{} "rab" -(let ((foo "foo bar baz")) - (reverse-string! foo) - foo) @result{} "zab rab oof" -(let ((foo "foo bar baz")) - (reverse-substring! foo 4 7) - foo) @result{} "foo rab baz" -@end group -@end example -@end deffn - -@node Variable-Length Strings, Byte Vectors, Modification of Strings, Strings -@section Variable-Length Strings - -@cindex length, of string -@cindex maximum length, of string (defn) -MIT/GNU Scheme allows the length of a string to be dynamically adjusted in a -limited way. When a new string is allocated, by whatever method, it has -a specific length. At the time of allocation, it is also given a -@dfn{maximum length}, which is guaranteed to be at least as large as the -string's length. (Sometimes the maximum length will be slightly larger -than the length, but it is a bad idea to count on this. Programs should -assume that the maximum length is the same as the length at the time of -the string's allocation.) After the string is allocated, the operation -@code{set-string-length!} can be used to alter the string's length to -any value between 0 and the string's maximum length, inclusive. - -@deffn procedure string-maximum-length string -Returns the maximum length of @var{string}. The following is -guaranteed: - -@example -@group -(<= (string-length string) - (string-maximum-length string)) @result{} #t -@end group -@end example -@findex string-length - -The maximum length of a string never changes. -@end deffn - -@deffn procedure set-string-length! string k -Alters the length of @var{string} to be @var{k}, and returns an -unspecified value. @var{K} must be less than or equal to the maximum -length of @var{string}. @code{set-string-length!} does not change the -maximum length of @var{string}. -@end deffn - -@node Byte Vectors, , Variable-Length Strings, Strings -@section Byte Vectors -@cindex byte vector -@cindex vector, byte - -@findex string-ref -MIT/GNU Scheme implements strings as packed vectors of 8-bit -@acronym{ISO-8859-1} bytes. Most of the string operations, such as -@code{string-ref}, coerce these 8-bit codes into character objects. -However, some lower-level operations are made available for use. - -@deffn procedure vector-8b-ref string k -Returns character @var{k} of @var{string} as an @acronym{ISO-8859-1} -code. @var{K} must be a valid index of @var{string}. - -@example -@group -(vector-8b-ref "abcde" 2) @result{} 99 @r{;c} -@end group -@end example -@end deffn - -@deffn procedure vector-8b-set! string k code -Stores @var{code} in element @var{k} of @var{string} and returns an -unspecified value. @var{K} must be a valid index of @var{string}, and -@var{code} must be a valid @acronym{ISO-8859-1} code. -@end deffn - -@deffn procedure vector-8b-fill! string start end code -Stores @var{code} in elements @var{start} (inclusive) to @var{end} -(exclusive) of @var{string} and returns an unspecified value. -@var{Code} must be a valid @acronym{ISO-8859-1} code. -@end deffn - -@deffn procedure vector-8b-find-next-char string start end code -@deffnx procedure vector-8b-find-next-char-ci string start end code -Returns the index of the first occurrence of @var{code} in the given -substring; returns @code{#f} if @var{code} does not appear. The index -returned is relative to the entire string, not just the substring. -@var{Code} must be a valid @acronym{ISO-8859-1} code. - -@code{vector-8b-find-next-char-ci} doesn't distinguish uppercase and -lowercase letters. -@end deffn - -@deffn procedure vector-8b-find-previous-char string start end code -@deffnx procedure vector-8b-find-previous-char-ci string start end code -Returns the index of the last occurrence of @var{code} in the given -substring; returns @code{#f} if @var{code} does not appear. The index -returned is relative to the entire string, not just the substring. -@var{Code} must be a valid @acronym{ISO-8859-1} code. - -@code{vector-8b-find-previous-char-ci} doesn't distinguish uppercase and -lowercase letters. -@end deffn