diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 117abd23d..8d429ef91 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -1800,42 +1800,36 @@ Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the @deffn {Scheme Procedure} char-alphabetic? chr @deffnx {C Function} scm_char_alphabetic_p (chr) Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. -Alphabetic means the same thing as the @code{isalpha} C library function. @end deffn @rnindex char-numeric? @deffn {Scheme Procedure} char-numeric? chr @deffnx {C Function} scm_char_numeric_p (chr) Return @code{#t} iff @var{chr} is numeric, else @code{#f}. -Numeric means the same thing as the @code{isdigit} C library function. @end deffn @rnindex char-whitespace? @deffn {Scheme Procedure} char-whitespace? chr @deffnx {C Function} scm_char_whitespace_p (chr) Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. -Whitespace means the same thing as the @code{isspace} C library function. @end deffn @rnindex char-upper-case? @deffn {Scheme Procedure} char-upper-case? chr @deffnx {C Function} scm_char_upper_case_p (chr) Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. -Uppercase means the same thing as the @code{isupper} C library function. @end deffn @rnindex char-lower-case? @deffn {Scheme Procedure} char-lower-case? chr @deffnx {C Function} scm_char_lower_case_p (chr) Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. -Lowercase means the same thing as the @code{islower} C library function. @end deffn @deffn {Scheme Procedure} char-is-both? chr @deffnx {C Function} scm_char_is_both_p (chr) Return @code{#t} iff @var{chr} is either uppercase or lowercase, else -@code{#f}. Uppercase and lowercase are as defined by the -@code{isupper} and @code{islower} C library functions. +@code{#f}. @end deffn @rnindex char->integer @@ -2380,16 +2374,18 @@ substrings} since the substring and the original string share modifications to each other. @menu -* String Syntax:: Read syntax for strings. -* String Predicates:: Testing strings for certain properties. -* String Constructors:: Creating new string objects. -* List/String Conversion:: Converting from/to lists of characters. -* String Selection:: Select portions from strings. -* String Modification:: Modify parts or whole strings. -* String Comparison:: Lexicographic ordering predicates. -* String Searching:: Searching in strings. -* Alphabetic Case Mapping:: Convert the alphabetic case of strings. -* Appending Strings:: Appending strings to form a new string. +* String Syntax:: Read syntax for strings. +* String Predicates:: Testing strings for certain properties. +* String Constructors:: Creating new string objects. +* List/String Conversion:: Converting from/to lists of characters. +* String Selection:: Select portions from strings. +* String Modification:: Modify parts or whole strings. +* String Comparison:: Lexicographic ordering predicates. +* String Searching:: Searching in strings. +* Alphabetic Case Mapping:: Convert the alphabetic case of strings. +* Reversing and Appending Strings:: Appending strings to form a new string. +* Mapping Folding and Unfolding:: Iterating over strings. +* Miscellaneous String Operations:: Replicating, insertion, parsing, ... * Conversion to/from C:: @end menu @@ -2481,6 +2477,40 @@ y @result{} "foo" @end lisp @end deffn +@deffn {Scheme Procedure} string-any char_pred s [start [end]] +@deffnx {C Function} scm_string_any (char_pred, s, start, end) +Check if the predicate @var{pred} is true for any character in +the string @var{s}. + +Calls to @var{pred} are made from left to right across @var{s}. +When it returns true (ie.@: non-@code{#f}), that return value +is the return from @code{string-any}. + +The SRFI-13 specification requires that the call to @var{pred} +on the last character of @var{s} (assuming that point is +reached) be a tail call, but currently in Guile this is not the +case. +@end deffn + +@deffn {Scheme Procedure} string-every char_pred s [start [end]] +@deffnx {C Function} scm_string_every (char_pred, s, start, end) +Check if the predicate @var{pred} is true for every character +in the string @var{s}. + +Calls to @var{pred} are made from left to right across @var{s}. +If the predicate is true for every character then the return +value from the last @var{pred} call is the return from +@code{string-every}. + +If there are no characters in @var{s} (ie.@: @var{start} equals +@var{end}) then the return is @code{#t}. + +The SRFI-13 specification requires that the call to @var{pred} +on the last character of @var{s} (assuming that point is +reached) be a tail call, but currently in Guile this is not the +case. +@end deffn + @node String Constructors @subsubsection String Constructors @@ -2514,6 +2544,46 @@ Like @code{scm_make_string}, but expects the length as a @code{size_t}. @end deftypefn +@deffn {Scheme Procedure} string-tabulate proc len +@deffnx {C Function} scm_string_tabulate (proc, len) +@var{proc} is an integer->char procedure. Construct a string +of size @var{len} by applying @var{proc} to each index to +produce the corresponding string element. The order in which +@var{proc} is applied to the indices is not specified. +@end deffn + +@deffn {Scheme Procedure} reverse-list->string chrs +@deffnx {C Function} scm_reverse_list_to_string (chrs) +An efficient implementation of @code{(compose string->list +reverse)}: + +@smalllisp +(reverse-list->string '(#\a #\B #\c)) @result{} "cBa" +@end smalllisp +@end deffn + +@deffn {Scheme Procedure} string-join ls [delimiter [grammar]] +@deffnx {C Function} scm_string_join (ls, delimiter, grammar) +Append the string in the string list @var{ls}, using the string +@var{delim} as a delimiter between the elements of @var{ls}. +@var{grammar} is a symbol which specifies how the delimiter is +placed between the strings, and defaults to the symbol +@code{infix}. + +@table @code +@item infix +Insert the separator between list elements. An empty string +will produce an empty list. +@item string-infix +Like @code{infix}, but will raise an error if given the empty +list. +@item suffix +Insert the separator after every list element. +@item prefix +Insert the separator before each list element. +@end table +@end deffn + @node List/String Conversion @subsubsection List/String conversion @@ -2523,12 +2593,10 @@ work with the resulting list, and then convert it back into a string. These procedures are useful for similar tasks. @rnindex string->list -@deffn {Scheme Procedure} string->list str +@deffn {Scheme Procedure} string->list str [start [end]] +@deffnx {C Function} scm_substring_to_list (str, start, end) @deffnx {C Function} scm_string_to_list (str) -Return a newly allocated list of the characters that make up -the given string @var{str}. @code{string->list} and -@code{list->string} are inverses as far as @samp{equal?} is -concerned. +Convert the string @var{str} into a list of characters. @end deffn @deffn {Scheme Procedure} string-split str chr @@ -2584,9 +2652,10 @@ indexing. @var{k} must be a valid index of @var{str}. @end deftypefn @rnindex string-copy -@deffn {Scheme Procedure} string-copy str +@deffn {Scheme Procedure} string-copy str [start [end]] +@deffnx {C Function} scm_substring_copy (str, start, end) @deffnx {C Function} scm_string_copy (str) -Return a copy of the given @var{string}. +Return a copy of the given string @var{str}. The returned string shares storage with @var{str} initially, but it is copied as soon as one of the two strings is modified. @@ -2626,6 +2695,110 @@ immediately. Like @code{scm_substring}, etc. but the bounds are given as a @code{size_t}. @end deftypefn +@deffn {Scheme Procedure} string-take s n +@deffnx {C Function} scm_string_take (s, n) +Return the @var{n} first characters of @var{s}. +@end deffn + +@deffn {Scheme Procedure} string-drop s n +@deffnx {C Function} scm_string_drop (s, n) +Return all but the first @var{n} characters of @var{s}. +@end deffn + +@deffn {Scheme Procedure} string-take-right s n +@deffnx {C Function} scm_string_take_right (s, n) +Return the @var{n} last characters of @var{s}. +@end deffn + +@deffn {Scheme Procedure} string-drop-right s n +@deffnx {C Function} scm_string_drop_right (s, n) +Return all but the last @var{n} characters of @var{s}. +@end deffn + +@deffn {Scheme Procedure} string-pad s len [chr [start [end]]] +@deffnx {C Function} scm_string_pad (s, len, chr, start, end) +Take that characters from @var{start} to @var{end} from the +string @var{s} and return a new string, right-padded by the +character @var{chr} to length @var{len}. If the resulting +string is longer than @var{len}, it is truncated on the right. +@end deffn + +@deffn {Scheme Procedure} string-pad-right s len [chr [start [end]]] +@deffnx {C Function} scm_string_pad_right (s, len, chr, start, end) +Take that characters from @var{start} to @var{end} from the +string @var{s} and return a new string, left-padded by the +character @var{chr} to length @var{len}. If the resulting +string is longer than @var{len}, it is truncated on the left. +@end deffn + +@deffn {Scheme Procedure} string-trim s [char_pred [start [end]]] +@deffnx {C Function} scm_string_trim (s, char_pred, start, end) +Trim @var{s} by skipping over all characters on the left +that satisfy the parameter @var{char_pred}: + +@itemize @bullet +@item +if it is the character @var{ch}, characters equal to +@var{ch} are trimmed, + +@item +if it is a procedure @var{pred} characters that +satisfy @var{pred} are trimmed, + +@item +if it is a character set, characters in that set are trimmed. +@end itemize + +If called without a @var{char_pred} argument, all whitespace is +trimmed. +@end deffn + +@deffn {Scheme Procedure} string-trim-right s [char_pred [start [end]]] +@deffnx {C Function} scm_string_trim_right (s, char_pred, start, end) +Trim @var{s} by skipping over all characters on the rightt +that satisfy the parameter @var{char_pred}: + +@itemize @bullet +@item +if it is the character @var{ch}, characters equal to @var{ch} +are trimmed, + +@item +if it is a procedure @var{pred} characters that satisfy +@var{pred} are trimmed, + +@item +if it is a character sets, all characters in that set are +trimmed. +@end itemize + +If called without a @var{char_pred} argument, all whitespace is +trimmed. +@end deffn + +@deffn {Scheme Procedure} string-trim-both s [char_pred [start [end]]] +@deffnx {C Function} scm_string_trim_both (s, char_pred, start, end) +Trim @var{s} by skipping over all characters on both sides of +the string that satisfy the parameter @var{char_pred}: + +@itemize @bullet +@item +if it is the character @var{ch}, characters equal to @var{ch} +are trimmed, + +@item +if it is a procedure @var{pred} characters that satisfy +@var{pred} are trimmed, + +@item +if it is a character set, the characters in the set are +trimmed. +@end itemize + +If called without a @var{char_pred} argument, all whitespace is +trimmed. +@end deffn + @node String Modification @subsubsection String Modification @@ -2646,10 +2819,11 @@ Like @code{scm_string_set_x}, but the index is given as a @code{size_t}. @end deftypefn @rnindex string-fill! -@deffn {Scheme Procedure} string-fill! str chr +@deffn {Scheme Procedure} string-fill! str chr [start [end]] +@deffnx {C Function} scm_substring_fill_x (str, chr, start, end) @deffnx {C Function} scm_string_fill_x (str, chr) -Store @var{char} in every element of the given @var{string} and -return an unspecified value. +Stores @var{chr} in every element of the given @var{str} and +returns an unspecified value. @end deffn @deffn {Scheme Procedure} substring-fill! str start end fill @@ -2672,16 +2846,28 @@ into @var{str2} beginning at position @var{start2}. @var{str1} and @var{str2} can be the same string. @end deffn +@deffn {Scheme Procedure} string-copy! target tstart s [start [end]] +@deffnx {C Function} scm_string_copy_x (target, tstart, s, start, end) +Copy the sequence of characters from index range [@var{start}, +@var{end}) in string @var{s} to string @var{target}, beginning +at index @var{tstart}. The characters are copied left-to-right +or right-to-left as needed -- the copy is guaranteed to work, +even if @var{target} and @var{s} are the same string. It is an +error if the copy operation runs off the end of the target +string. +@end deffn + @node String Comparison @subsubsection String Comparison The procedures in this section are similar to the character ordering predicates (@pxref{Characters}), but are defined on character sequences. -They all return @code{#t} on success and @code{#f} on failure. The -predicates ending in @code{-ci} ignore the character case when comparing -strings. +The first set is specified in R5RS and has names that end in @code{?}. +The second set is specified in SRFI-13 and the names have no ending +@code{?}. The predicates ending in @code{-ci} ignore the character case +when comparing strings. @rnindex string=? @deffn {Scheme Procedure} string=? s1 s2 @@ -2727,7 +2913,7 @@ characters match (ignoring case) at each position; otherwise return @code{#f}. @end deffn -@rnindex string-ci< +@rnindex string-ci s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_neq (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} and @var{s2} are equal, a true +value otherwise. +@end deffn + +@deffn {Scheme Procedure} string< s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_lt (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a +true value otherwise. +@end deffn + +@deffn {Scheme Procedure} string> s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_gt (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is less or equal to @var{s2}, a +true value otherwise. +@end deffn + +@deffn {Scheme Procedure} string<= s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_le (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is greater to @var{s2}, a true +value otherwise. +@end deffn + +@deffn {Scheme Procedure} string>= s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ge (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is less to @var{s2}, a true value +otherwise. +@end deffn + +@deffn {Scheme Procedure} string-ci= s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ci_eq (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} and @var{s2} are not equal, a true +value otherwise. The character comparison is done +case-insensitively. +@end deffn + +@deffn {Scheme Procedure} string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ci_neq (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} and @var{s2} are equal, a true +value otherwise. The character comparison is done +case-insensitively. +@end deffn + +@deffn {Scheme Procedure} string-ci< s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ci_lt (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is greater or equal to @var{s2}, a +true value otherwise. The character comparison is done +case-insensitively. +@end deffn + +@deffn {Scheme Procedure} string-ci> s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ci_gt (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is less or equal to @var{s2}, a +true value otherwise. The character comparison is done +case-insensitively. +@end deffn + +@deffn {Scheme Procedure} string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ci_le (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is greater to @var{s2}, a true +value otherwise. The character comparison is done +case-insensitively. +@end deffn + +@deffn {Scheme Procedure} string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_ci_ge (s1, s2, start1, end1, start2, end2) +Return @code{#f} if @var{s1} is less to @var{s2}, a true value +otherwise. The character comparison is done +case-insensitively. +@end deffn + +@deffn {Scheme Procedure} string-hash s [bound [start [end]]] +@deffnx {C Function} scm_substring_hash (s, bound, start, end) +Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound). +@end deffn + +@deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]] +@deffnx {C Function} scm_substring_hash_ci (s, bound, start, end) +Compute a hash value for @var{S}. the optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound). +@end deffn @node String Searching @subsubsection String Searching -When searching for the index of a character in a string, these -procedures can be used. +@deffn {Scheme Procedure} string-index s char_pred [start [end]] +@deffnx {C Function} scm_string_index (s, char_pred, start, end) +Search through the string @var{s} from left to right, returning +the index of the first occurence of a character which -@deffn {Scheme Procedure} string-index str chr [frm [to]] -@deffnx {C Function} scm_string_index (str, chr, frm, to) -Return the index of the first occurrence of @var{chr} in -@var{str}. The optional integer arguments @var{frm} and -@var{to} limit the search to a portion of the string. This -procedure essentially implements the @code{index} or -@code{strchr} functions from the C library. +@itemize @bullet +@item +equals @var{char_pred}, if it is character, -@lisp -(string-index "weiner" #\e) -@result{} 1 +@item +satisifies the predicate @var{char_pred}, if it is a procedure, -(string-index "weiner" #\e 2) -@result{} 4 - -(string-index "weiner" #\e 2 4) -@result{} #f -@end lisp +@item +is in the set @var{char_pred}, if it is a character set. +@end itemize @end deffn -@deffn {Scheme Procedure} string-rindex str chr [frm [to]] -@deffnx {C Function} scm_string_rindex (str, chr, frm, to) -Like @code{string-index}, but search from the right of the -string rather than from the left. This procedure essentially -implements the @code{rindex} or @code{strrchr} functions from -the C library. +@deffn {Scheme Procedure} string-rindex s char_pred [start [end]] +@deffnx {C Function} scm_string_rindex (s, char_pred, start, end) +Search through the string @var{s} from right to left, returning +the index of the last occurence of a character which -@lisp -(string-rindex "weiner" #\e) -@result{} 4 +@itemize @bullet +@item +equals @var{char_pred}, if it is character, -(string-rindex "weiner" #\e 2 4) -@result{} #f +@item +satisifies the predicate @var{char_pred}, if it is a procedure, -(string-rindex "weiner" #\e 2 5) -@result{} 4 -@end lisp +@item +is in the set if @var{char_pred} is a character set. +@end itemize +@end deffn + +@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_prefix_length (s1, s2, start1, end1, start2, end2) +Return the length of the longest common prefix of the two +strings. +@end deffn + +@deffn {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_prefix_length_ci (s1, s2, start1, end1, start2, end2) +Return the length of the longest common prefix of the two +strings, ignoring character case. +@end deffn + +@deffn {Scheme Procedure} string-suffix-length s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_suffix_length (s1, s2, start1, end1, start2, end2) +Return the length of the longest common suffix of the two +strings. +@end deffn + +@deffn {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_suffix_length_ci (s1, s2, start1, end1, start2, end2) +Return the length of the longest common suffix of the two +strings, ignoring character case. +@end deffn + +@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_prefix_p (s1, s2, start1, end1, start2, end2) +Is @var{s1} a prefix of @var{s2}? +@end deffn + +@deffn {Scheme Procedure} string-prefix-ci? s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_prefix_ci_p (s1, s2, start1, end1, start2, end2) +Is @var{s1} a prefix of @var{s2}, ignoring character case? +@end deffn + +@deffn {Scheme Procedure} string-suffix? s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_suffix_p (s1, s2, start1, end1, start2, end2) +Is @var{s1} a suffix of @var{s2}? +@end deffn + +@deffn {Scheme Procedure} string-suffix-ci? s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_suffix_ci_p (s1, s2, start1, end1, start2, end2) +Is @var{s1} a suffix of @var{s2}, ignoring character case? +@end deffn + +@deffn {Scheme Procedure} string-index-right s char_pred [start [end]] +@deffnx {C Function} scm_string_index_right (s, char_pred, start, end) +Search through the string @var{s} from right to left, returning +the index of the last occurence of a character which + +@itemize @bullet +@item +equals @var{char_pred}, if it is character, + +@item +satisifies the predicate @var{char_pred}, if it is a procedure, + +@item +is in the set if @var{char_pred} is a character set. +@end itemize +@end deffn + +@deffn {Scheme Procedure} string-skip s char_pred [start [end]] +@deffnx {C Function} scm_string_skip (s, char_pred, start, end) +Search through the string @var{s} from left to right, returning +the index of the first occurence of a character which + +@itemize @bullet +@item +does not equal @var{char_pred}, if it is character, + +@item +does not satisify the predicate @var{char_pred}, if it is a +procedure, + +@item +is not in the set if @var{char_pred} is a character set. +@end itemize +@end deffn + +@deffn {Scheme Procedure} string-skip-right s char_pred [start [end]] +@deffnx {C Function} scm_string_skip_right (s, char_pred, start, end) +Search through the string @var{s} from right to left, returning +the index of the last occurence of a character which + +@itemize @bullet +@item +does not equal @var{char_pred}, if it is character, + +@item +does not satisfy the predicate @var{char_pred}, if it is a +procedure, + +@item +is not in the set if @var{char_pred} is a character set. +@end itemize +@end deffn + +@deffn {Scheme Procedure} string-count s char_pred [start [end]] +@deffnx {C Function} scm_string_count (s, char_pred, start, end) +Return the count of the number of characters in the string +@var{s} which + +@itemize @bullet +@item +equals @var{char_pred}, if it is character, + +@item +satisifies the predicate @var{char_pred}, if it is a procedure. + +@item +is in the set @var{char_pred}, if it is a character set. +@end itemize +@end deffn + +@deffn {Scheme Procedure} string-contains s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_contains (s1, s2, start1, end1, start2, end2) +Does string @var{s1} contain string @var{s2}? Return the index +in @var{s1} where @var{s2} occurs as a substring, or false. +The optional start/end indices restrict the operation to the +indicated substrings. +@end deffn + +@deffn {Scheme Procedure} string-contains-ci s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_contains_ci (s1, s2, start1, end1, start2, end2) +Does string @var{s1} contain string @var{s2}? Return the index +in @var{s1} where @var{s2} occurs as a substring, or false. +The optional start/end indices restrict the operation to the +indicated substrings. Character comparison is done +case-insensitively. @end deffn @node Alphabetic Case Mapping @@ -2807,37 +3224,43 @@ the C library. These are procedures for mapping strings to their upper- or lower-case equivalents, respectively, or for capitalizing strings. -@deffn {Scheme Procedure} string-upcase str +@deffn {Scheme Procedure} string-upcase str [start [end]] +@deffnx {C Function} scm_substring_upcase (str, start, end) @deffnx {C Function} scm_string_upcase (str) -Return a freshly allocated string containing the characters of -@var{str} in upper case. +Upcase every character in @code{str}. @end deffn -@deffn {Scheme Procedure} string-upcase! str +@deffn {Scheme Procedure} string-upcase! str [start [end]] +@deffnx {C Function} scm_substring_upcase_x (str, start, end) @deffnx {C Function} scm_string_upcase_x (str) -Destructively upcase every character in @var{str} and return -@var{str}. +Destructively upcase every character in @code{str}. + @lisp -y @result{} "arrdefg" -(string-upcase! y) @result{} "ARRDEFG" -y @result{} "ARRDEFG" +(string-upcase! y) +@result{} "ARRDEFG" +y +@result{} "ARRDEFG" @end lisp @end deffn -@deffn {Scheme Procedure} string-downcase str +@deffn {Scheme Procedure} string-downcase str [start [end]] +@deffnx {C Function} scm_substring_downcase (str, start, end) @deffnx {C Function} scm_string_downcase (str) -Return a freshly allocation string containing the characters in -@var{str} in lower case. +Downcase every character in @var{str}. @end deffn -@deffn {Scheme Procedure} string-downcase! str +@deffn {Scheme Procedure} string-downcase! str [start [end]] +@deffnx {C Function} scm_substring_downcase_x (str, start, end) @deffnx {C Function} scm_string_downcase_x (str) -Destructively downcase every character in @var{str} and return -@var{str}. +Destructively downcase every character in @var{str}. + @lisp -y @result{} "ARRDEFG" -(string-downcase! y) @result{} "arrdefg" -y @result{} "arrdefg" +y +@result{} "ARRDEFG" +(string-downcase! y) +@result{} "arrdefg" +y +@result{} "arrdefg" @end lisp @end deffn @@ -2860,12 +3283,33 @@ y @result{} "Hello World" @end lisp @end deffn +@deffn {Scheme Procedure} string-titlecase str [start [end]] +@deffnx {C Function} scm_string_titlecase (str, start, end) +Titlecase every first character in a word in @var{str}. +@end deffn -@node Appending Strings -@subsubsection Appending Strings +@deffn {Scheme Procedure} string-titlecase! str [start [end]] +@deffnx {C Function} scm_string_titlecase_x (str, start, end) +Destructively titlecase every first character in a word in +@var{str}. +@end deffn -The procedure @code{string-append} appends several strings together to -form a longer result string. +@node Reversing and Appending Strings +@subsubsection Reversing and Appending Strings + +@deffn {Scheme Procedure} string-reverse str [start [end]] +@deffnx {C Function} scm_string_reverse (str, start, end) +Reverse the string @var{str}. The optional arguments +@var{start} and @var{end} delimit the region of @var{str} to +operate on. +@end deffn + +@deffn {Scheme Procedure} string-reverse! str [start [end]] +@deffnx {C Function} scm_string_reverse_x (str, start, end) +Reverse the string @var{str} in-place. The optional arguments +@var{start} and @var{end} delimit the region of @var{str} to +operate on. The return value is unspecified. +@end deffn @rnindex string-append @deffn {Scheme Procedure} string-append . args @@ -2880,6 +3324,200 @@ concatenation of the given strings, @var{args}. @end example @end deffn +@deffn {Scheme Procedure} string-append/shared . ls +@deffnx {C Function} scm_string_append_shared (ls) +Like @code{string-append}, but the result may share memory +with the argument strings. +@end deffn + +@deffn {Scheme Procedure} string-concatenate ls +@deffnx {C Function} scm_string_concatenate (ls) +Append the elements of @var{ls} (which must be strings) +together into a single string. Guaranteed to return a freshly +allocated string. +@end deffn + +@deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]] +@deffnx {C Function} scm_string_concatenate_reverse (ls, final_string, end) +Without optional arguments, this procedure is equivalent to + +@smalllisp +(string-concatenate (reverse ls)) +@end smalllisp + +If the optional argument @var{final_string} is specified, it is +consed onto the beginning to @var{ls} before performing the +list-reverse and string-concatenate operations. If @var{end} +is given, only the characters of @var{final_string} up to index +@var{end} are used. + +Guaranteed to return a freshly allocated string. +@end deffn + +@deffn {Scheme Procedure} string-concatenate/shared ls +@deffnx {C Function} scm_string_concatenate_shared (ls) +Like @code{string-concatenate}, but the result may share memory +with the strings in the list @var{ls}. +@end deffn + +@deffn {Scheme Procedure} string-concatenate-reverse/shared ls [final_string [end]] +@deffnx {C Function} scm_string_concatenate_reverse_shared (ls, final_string, end) +Like @code{string-concatenate-reverse}, but the result may +share memory with the the strings in the @var{ls} arguments. +@end deffn + +@node Mapping Folding and Unfolding +@subsubsection Mapping, Folding, and Unfolding + +@deffn {Scheme Procedure} string-map proc s [start [end]] +@deffnx {C Function} scm_string_map (proc, s, start, end) +@var{proc} is a char->char procedure, it is mapped over +@var{s}. The order in which the procedure is applied to the +string elements is not specified. +@end deffn + +@deffn {Scheme Procedure} string-map! proc s [start [end]] +@deffnx {C Function} scm_string_map_x (proc, s, start, end) +@var{proc} is a char->char procedure, it is mapped over +@var{s}. The order in which the procedure is applied to the +string elements is not specified. The string @var{s} is +modified in-place, the return value is not specified. +@end deffn + +@deffn {Scheme Procedure} string-for-each proc s [start [end]] +@deffnx {C Function} scm_string_for_each (proc, s, start, end) +@var{proc} is mapped over @var{s} in left-to-right order. The +return value is not specified. +@end deffn + +@deffn {Scheme Procedure} string-for-each-index proc s [start [end]] +@deffnx {C Function} scm_string_for_each_index (proc, s, start, end) +@var{proc} is mapped over @var{s} in left-to-right order. The +return value is not specified. +@end deffn + +@deffn {Scheme Procedure} string-fold kons knil s [start [end]] +@deffnx {C Function} scm_string_fold (kons, knil, s, start, end) +Fold @var{kons} over the characters of @var{s}, with @var{knil} +as the terminating element, from left to right. @var{kons} +must expect two arguments: The actual character and the last +result of @var{kons}' application. +@end deffn + +@deffn {Scheme Procedure} string-fold-right kons knil s [start [end]] +@deffnx {C Function} scm_string_fold_right (kons, knil, s, start, end) +Fold @var{kons} over the characters of @var{s}, with @var{knil} +as the terminating element, from right to left. @var{kons} +must expect two arguments: The actual character and the last +result of @var{kons}' application. +@end deffn + +@deffn {Scheme Procedure} string-unfold p f g seed [base [make_final]] +@deffnx {C Function} scm_string_unfold (p, f, g, seed, base, make_final) +@itemize @bullet +@item @var{g} is used to generate a series of @emph{seed} +values from the initial @var{seed}: @var{seed}, (@var{g} +@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), +@dots{} +@item @var{p} tells us when to stop -- when it returns true +when applied to one of these seed values. +@item @var{f} maps each seed value to the corresponding +character in the result string. These chars are assembled +into the string in a left-to-right order. +@item @var{base} is the optional initial/leftmost portion +of the constructed string; it default to the empty +string. +@item @var{make_final} is applied to the terminal seed +value (on which @var{p} returns true) to produce +the final/rightmost portion of the constructed string. +It defaults to @code{(lambda (x) )}. +@end itemize +@end deffn + +@deffn {Scheme Procedure} string-unfold-right p f g seed [base [make_final]] +@deffnx {C Function} scm_string_unfold_right (p, f, g, seed, base, make_final) +@itemize @bullet +@item @var{g} is used to generate a series of @emph{seed} +values from the initial @var{seed}: @var{seed}, (@var{g} +@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), +@dots{} +@item @var{p} tells us when to stop -- when it returns true +when applied to one of these seed values. +@item @var{f} maps each seed value to the corresponding +character in the result string. These chars are assembled +into the string in a right-to-left order. +@item @var{base} is the optional initial/rightmost portion +of the constructed string; it default to the empty +string. +@item @var{make_final} is applied to the terminal seed +value (on which @var{p} returns true) to produce +the final/leftmost portion of the constructed string. +It defaults to @code{(lambda (x) )}. +@end itemize +@end deffn + +@node Miscellaneous String Operations +@subsubsection Miscellaneous String Operations + +@deffn {Scheme Procedure} xsubstring s from [to [start [end]]] +@deffnx {C Function} scm_xsubstring (s, from, to, start, end) +This is the @emph{extended substring} procedure that implements +replicated copying of a substring of some string. + +@var{s} is a string, @var{start} and @var{end} are optional +arguments that demarcate a substring of @var{s}, defaulting to +0 and the length of @var{s}. Replicate this substring up and +down index space, in both the positive and negative directions. +@code{xsubstring} returns the substring of this string +beginning at index @var{from}, and ending at @var{to}, which +defaults to @var{from} + (@var{end} - @var{start}). +@end deffn + +@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto [start [end]]] +@deffnx {C Function} scm_string_xcopy_x (target, tstart, s, sfrom, sto, start, end) +Exactly the same as @code{xsubstring}, but the extracted text +is written into the string @var{target} starting at index +@var{tstart}. The operation is not defined if @code{(eq? +@var{target} @var{s})} or these arguments share storage -- you +cannot copy a string on top of itself. +@end deffn + +@deffn {Scheme Procedure} string-replace s1 s2 [start1 [end1 [start2 [end2]]]] +@deffnx {C Function} scm_string_replace (s1, s2, start1, end1, start2, end2) +Return the string @var{s1}, but with the characters +@var{start1} @dots{} @var{end1} replaced by the characters +@var{start2} @dots{} @var{end2} from @var{s2}. +@end deffn + +@deffn {Scheme Procedure} string-tokenize s [token_set [start [end]]] +@deffnx {C Function} scm_string_tokenize (s, token_set, start, end) +Split the string @var{s} into a list of substrings, where each +substring is a maximal non-empty contiguous sequence of +characters from the character set @var{token_set}, which +defaults to @code{char-set:graphic}. +If @var{start} or @var{end} indices are provided, they restrict +@code{string-tokenize} to operating on the indicated substring +of @var{s}. +@end deffn + +@deffn {Scheme Procedure} string-filter s char_pred [start [end]] +@deffnx {C Function} scm_string_filter (s, char_pred, start, end) +Filter the string @var{s}, retaining only those characters that +satisfy the @var{char_pred} argument. If the argument is a +procedure, it is applied to each character as a predicate, if +it is a character, it is tested for equality and if it is a +character set, it is tested for membership. +@end deffn + +@deffn {Scheme Procedure} string-delete s char_pred [start [end]] +@deffnx {C Function} scm_string_delete (s, char_pred, start, end) +Filter the string @var{s}, retaining only those characters that +do not satisfy the @var{char_pred} argument. If the argument +is a procedure, it is applied to each character as a predicate, +if it is a character, it is tested for equality and if it is a +character set, it is tested for membership. +@end deffn + @node Conversion to/from C @subsubsection Conversion to/from C diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 9a6659a05..0aadb36d5 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -1275,692 +1275,7 @@ expressions. @subsection SRFI-13 - String Library @cindex SRFI-13 -In this section, we will describe all procedures defined in SRFI-13 -(string library) and implemented by the module @code{(srfi srfi-13)}. - -Note that only the procedures from SRFI-13 are documented here which are -not already contained in Guile. For procedures not documented here -please refer to the relevant chapters in the Guile Reference Manual, for -example the documentation of strings and string procedures -(@pxref{Strings}). - -All of the procedures defined in SRFI-13, which are not already -included in the Guile core library, are implemented in the module -@code{(srfi srfi-13)}. The procedures which are both in Guile and in -SRFI-13 are slightly extended in this module. Their bindings -overwrite those in the Guile core. - -The procedures which are defined in the section @emph{Low-level -procedures} of SRFI-13 for parsing optional string indices, substring -specification checking and Knuth-Morris-Pratt-Searching are not -implemented. - -The procedures @code{string-contains} and @code{string-contains-ci} are -not implemented very efficiently at the moment. This will be changed as -soon as possible. - -@menu -* Loading SRFI-13:: How to load SRFI-13 support. -* SRFI-13 Predicates:: String predicates. -* SRFI-13 Constructors:: String constructing procedures. -* SRFI-13 List/String Conversion:: Conversion from/to lists. -* SRFI-13 Selection:: Selection portions of strings. -* SRFI-13 Modification:: Modify strings in-place. -* SRFI-13 Comparison:: Compare strings. -* SRFI-13 Prefixes/Suffixes:: Detect common pre-/suffixes. -* SRFI-13 Searching:: Searching for substrings. -* SRFI-13 Case Mapping:: Mapping to lower-/upper-case. -* SRFI-13 Reverse/Append:: Reverse and append strings. -* SRFI-13 Fold/Unfold/Map:: Construct/deconstruct strings. -* SRFI-13 Replicate/Rotate:: Replicate and rotate portions of strings. -* SRFI-13 Miscellaneous:: Left-over string procedures. -* SRFI-13 Filtering/Deleting:: Filter and delete characters from strings. -@end menu - - -@node Loading SRFI-13 -@subsubsection Loading SRFI-13 - -When Guile is properly installed, SRFI-13 support can be loaded into a -running Guile by using the @code{(srfi srfi-13)} module. - -@example -$ guile -guile> (use-modules (srfi srfi-13)) -guile> -@end example - -When this step causes any errors, Guile is not properly installed. - -One possible reason is that Guile cannot find either the Scheme module -file @file{srfi-13.scm}, or it cannot find the shared object file -@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the -Guile load path and that the latter is either installed in some default -location like @file{/usr/local/lib} or that the directory it was -installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to -@file{srfi-14.scm}. - -Now you can test whether the SRFI-13 procedures are working by calling -the @code{string-concatenate} procedure. - -@example -guile> (string-concatenate '("Hello" " " "World!")) -"Hello World!" -@end example - -@node SRFI-13 Predicates -@subsubsection Predicates - -In addition to the primitives @code{string?} and @code{string-null?}, -which are already in the Guile core, the string predicates -@code{string-any} and @code{string-every} are defined by SRFI-13. - -@deffn {Scheme Procedure} string-any char_pred s [start end] -Return true if @code{char_pred} is satisfied for any character in the -string @var{s}. @var{char_pred} can be - -@itemize @bullet -@item -A character, to to test for any in @var{s} equal to that. -@item -A character set (@pxref{SRFI-14}), to test for any character in -@var{s} in that character set. -@item -A predicate function, called as @code{(@var{char_pred} c)} for each -character in @var{s}, from left to right, to test for any on which -@var{char_pred} returns true. - -When @var{char_pred} does return true (ie.@: non-@code{#f}), that -value is the value returned by @code{string-any}. -@end itemize - -If there are no characters in @var{s} (ie.@: @var{start} equals -@var{end}) then the return is @code{#f}. - -SRFI-13 specifies that when @var{char_pred} is a predicate function, -the call on the last character of @var{s} (assuming that point is -reached) is a tail call, but currently in Guile this is not the case. -@end deffn - -@deffn {Scheme Procedure} string-every char_pred s [start end] -Return true if @var{char_pred} is satisifed for every character in the -string @var{s}. @var{char_pred} can be - -@itemize @bullet -@item -A character, to to test for every character in @var{s} equal to that. -@item -A character set (@pxref{SRFI-14}), to test for every character in -@var{s} being in that character set. -@item -A predicate function, called as @code{(@var{char_pred} c)} for each -character in @var{s}, from left to right, to test that it returns true -for every character in @var{s}. - -When @var{char_pred} does return true (ie.@: non-@code{#f}) for every -character, the return from the last call is the value returned by -@code{string-every}. -@end itemize - -If there are no characters in @var{s} (ie.@: @var{start} equals -@var{end}) then the return is @code{#t}. - -SRFI-13 specifies that when @var{char_pred} is a predicate function, -the call on the last character of @var{s} (assuming that point is -reached) is a tail call, but currently in Guile this is not the case. -@end deffn - -@c =================================================================== - -@node SRFI-13 Constructors -@subsubsection Constructors - -SRFI-13 defines several procedures for constructing new strings. In -addition to @code{make-string} and @code{string} (available in the Guile -core library), the procedure @code{string-tabulate} does exist. - -@deffn {Scheme Procedure} string-tabulate proc len -@var{proc} is an integer->char procedure. Construct a string -of size @var{len} by applying @var{proc} to each index to -produce the corresponding string element. The order in which -@var{proc} is applied to the indices is not specified. -@end deffn - - -@c =================================================================== - -@node SRFI-13 List/String Conversion -@subsubsection List/String Conversion - -The procedure @code{string->list} is extended by SRFI-13, that is why it -is included in @code{(srfi srfi-13)}. The other procedures are new. -The Guile core already contains the procedure @code{list->string} for -converting a list of characters into a string (@pxref{List/String -Conversion}). - -@deffn {Scheme Procedure} string->list str [start end] -Convert the string @var{str} into a list of characters. -@end deffn - -@deffn {Scheme Procedure} reverse-list->string chrs -An efficient implementation of @code{(compose string->list -reverse)}: - -@smalllisp -(reverse-list->string '(#\a #\B #\c)) @result{} "cBa" -@end smalllisp -@end deffn - -@deffn {Scheme Procedure} string-join ls [delimiter grammar] -Append the string in the string list @var{ls}, using the string -@var{delim} as a delimiter between the elements of @var{ls}. -@var{grammar} is a symbol which specifies how the delimiter is -placed between the strings, and defaults to the symbol -@code{infix}. - -@table @code -@item infix -Insert the separator between list elements. An empty string -will produce an empty list. - -@item string-infix -Like @code{infix}, but will raise an error if given the empty -list. - -@item suffix -Insert the separator after every list element. - -@item prefix -Insert the separator before each list element. -@end table -@end deffn - - -@c =================================================================== - -@node SRFI-13 Selection -@subsubsection Selection - -These procedures are called @dfn{selectors}, because they access -information about the string or select pieces of a given string. - -Additional selector procedures are documented in the Strings section -(@pxref{String Selection}), like @code{string-length} or -@code{string-ref}. - -@code{string-copy} is also available in core Guile, but this version -accepts additional start/end indices. - -@deffn {Scheme Procedure} string-copy str [start end] -Return a freshly allocated copy of the string @var{str}. If -given, @var{start} and @var{end} delimit the portion of -@var{str} which is copied. -@end deffn - -@deffn {Scheme Procedure} substring/shared str start [end] -Like @code{substring}, but the result may share memory with the -argument @var{str}. -@end deffn - -@deffn {Scheme Procedure} string-copy! target tstart s [start end] -Copy the sequence of characters from index range [@var{start}, -@var{end}) in string @var{s} to string @var{target}, beginning -at index @var{tstart}. The characters are copied left-to-right -or right-to-left as needed - the copy is guaranteed to work, -even if @var{target} and @var{s} are the same string. It is an -error if the copy operation runs off the end of the target -string. -@end deffn - -@deffn {Scheme Procedure} string-take s n -@deffnx {Scheme Procedure} string-take-right s n -Return the @var{n} first/last characters of @var{s}. -@end deffn - -@deffn {Scheme Procedure} string-drop s n -@deffnx {Scheme Procedure} string-drop-right s n -Return all but the first/last @var{n} characters of @var{s}. -@end deffn - -@deffn {Scheme Procedure} string-pad s len [chr start end] -@deffnx {Scheme Procedure} string-pad-right s len [chr start end] -Take that characters from @var{start} to @var{end} from the -string @var{s} and return a new string, right(left)-padded by the -character @var{chr} to length @var{len}. If the resulting -string is longer than @var{len}, it is truncated on the right (left). -@end deffn - -@deffn {Scheme Procedure} string-trim s [char_pred start end] -@deffnx {Scheme Procedure} string-trim-right s [char_pred start end] -@deffnx {Scheme Procedure} string-trim-both s [char_pred start end] -Trim @var{s} by skipping over all characters on the left/right/both -sides of the string that satisfy the parameter @var{char_pred}: - -@itemize @bullet -@item -if it is the character @var{ch}, characters equal to -@var{ch} are trimmed, - -@item -if it is a procedure @var{pred} characters that -satisfy @var{pred} are trimmed, - -@item -if it is a character set, characters in that set are trimmed. -@end itemize - -If called without a @var{char_pred} argument, all whitespace is -trimmed. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Modification -@subsubsection Modification - -The procedure @code{string-fill!} is extended from R5RS because it -accepts optional start/end indices. This bindings shadows the procedure -of the same name in the Guile core. The second modification procedure -@code{string-set!} is documented in the Strings section (@pxref{String -Modification}). - -@deffn {Scheme Procedure} string-fill! str chr [start end] -Stores @var{chr} in every element of the given @var{str} and -returns an unspecified value. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Comparison -@subsubsection Comparison - -The procedures in this section are used for comparing strings in -different ways. The comparison predicates differ from those in R5RS in -that they do not only return @code{#t} or @code{#f}, but the mismatch -index in the case of a true return value. - -@code{string-hash} and @code{string-hash-ci} are for calculating hash -values for strings, useful for implementing fast lookup mechanisms. - -@deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] -Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the -mismatch index, depending upon whether @var{s1} is less than, -equal to, or greater than @var{s2}. The mismatch index is the -largest index @var{i} such that for every 0 <= @var{j} < -@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] - that is, -@var{i} is the first position that does not match. The -character comparison is done case-insensitively. -@end deffn - -@deffn {Scheme Procedure} string= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string<> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string< s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string<= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string>= s1 s2 [start1 end1 start2 end2] -Compare @var{s1} and @var{s2} and return @code{#f} if the predicate -fails. Otherwise, the mismatch index is returned (or @var{end1} in the -case of @code{string=}. -@end deffn - -@deffn {Scheme Procedure} string-ci= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci<> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci< s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci> s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci<= s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-ci>= s1 s2 [start1 end1 start2 end2] -Compare @var{s1} and @var{s2} and return @code{#f} if the predicate -fails. Otherwise, the mismatch index is returned (or @var{end1} in the -case of @code{string=}. These are the case-insensitive variants. -@end deffn - -@deffn {Scheme Procedure} string-hash s [bound start end] -@deffnx {Scheme Procedure} string-hash-ci s [bound start end] -Return a hash value of the string @var{s} in the range 0 @dots{} -@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Prefixes/Suffixes -@subsubsection Prefixes/Suffixes - -Using these procedures you can determine whether a given string is a -prefix or suffix of another string or how long a common prefix/suffix -is. - -@deffn {Scheme Procedure} string-prefix-length s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix-length s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2] -Return the length of the longest common prefix/suffix of the two -strings. @code{string-prefix-length-ci} and -@code{string-suffix-length-ci} are the case-insensitive variants. -@end deffn - -@deffn {Scheme Procedure} string-prefix? s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix? s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2] -Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and -@code{string-suffix-ci?} are the case-insensitive variants. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Searching -@subsubsection Searching - -Use these procedures to find out whether a string contains a given -character or a given substring, or a character from a set of characters. - -@deffn {Scheme Procedure} string-index s char_pred [start end] -@deffnx {Scheme Procedure} string-index-right s char_pred [start end] -Search through the string @var{s} from left to right (right to left), -returning the index of the first (last) occurrence of a character which - -@itemize @bullet -@item -equals @var{char_pred}, if it is character, - -@item -satisfies the predicate @var{char_pred}, if it is a -procedure, - -@item -is in the set @var{char_pred}, if it is a character set. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-skip s char_pred [start end] -@deffnx {Scheme Procedure} string-skip-right s char_pred [start end] -Search through the string @var{s} from left to right (right to left), -returning the index of the first (last) occurrence of a character which - -@itemize @bullet -@item -does not equal @var{char_pred}, if it is character, - -@item -does not satisfy the predicate @var{char_pred}, if it is -a procedure. - -@item -is not in the set if @var{char_pred} is a character set. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-count s char_pred [start end] -Return the count of the number of characters in the string -@var{s} which - -@itemize @bullet -@item -equals @var{char_pred}, if it is character, - -@item -satisfies the predicate @var{char_pred}, if it is a procedure. - -@item -is in the set @var{char_pred}, if it is a character set. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-contains s1 s2 [start1 end1 start2 end2] -@deffnx {Scheme Procedure} string-contains-ci s1 s2 [start1 end1 start2 end2] -Does string @var{s1} contain string @var{s2}? Return the index -in @var{s1} where @var{s2} occurs as a substring, or false. -The optional start/end indices restrict the operation to the -indicated substrings. - -@code{string-contains-ci} is the case-insensitive variant. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Case Mapping -@subsubsection Alphabetic Case Mapping - -These procedures convert the alphabetic case of strings. They are -similar to the procedures in the Guile core, but are extended to handle -optional start/end indices. - -@deffn {Scheme Procedure} string-upcase s [start end] -@deffnx {Scheme Procedure} string-upcase! s [start end] -Upcase every character in @var{s}. @code{string-upcase!} is the -side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} string-downcase s [start end] -@deffnx {Scheme Procedure} string-downcase! s [start end] -Downcase every character in @var{s}. @code{string-downcase!} is the -side-effecting variant. -@end deffn - -@deffn {Scheme Procedure} string-titlecase s [start end] -@deffnx {Scheme Procedure} string-titlecase! s [start end] -Upcase every first character in every word in @var{s}, downcase the -other characters. @code{string-titlecase!} is the side-effecting -variant. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Reverse/Append -@subsubsection Reverse/Append - -One appending procedure, @code{string-append} is the same in R5RS and in -SRFI-13, so it is not redefined. - -@deffn {Scheme Procedure} string-reverse str [start end] -@deffnx {Scheme Procedure} string-reverse! str [start end] -Reverse the string @var{str}. The optional arguments -@var{start} and @var{end} delimit the region of @var{str} to -operate on. - -@code{string-reverse!} modifies the argument string and returns an -unspecified value. -@end deffn - -@deffn {Scheme Procedure} string-append/shared ls @dots{} -Like @code{string-append}, but the result may share memory -with the argument strings. -@end deffn - -@deffn {Scheme Procedure} string-concatenate ls -Append the elements of @var{ls} (which must be strings) -together into a single string. Guaranteed to return a freshly -allocated string. -@end deffn - -@deffn {Scheme Procedure} string-concatenate/shared ls -Like @code{string-concatenate}, but the result may share memory -with the strings in the list @var{ls}. -@end deffn - -@deffn {Scheme Procedure} string-concatenate-reverse ls final_string end -Without optional arguments, this procedure is equivalent to - -@smalllisp -(string-concatenate (reverse ls)) -@end smalllisp - -If the optional argument @var{final_string} is specified, it is -consed onto the beginning to @var{ls} before performing the -list-reverse and string-concatenate operations. If @var{end} -is given, only the characters of @var{final_string} up to index -@var{end} are used. - -Guaranteed to return a freshly allocated string. -@end deffn - -@deffn {Scheme Procedure} string-concatenate-reverse/shared ls final_string end -Like @code{string-concatenate-reverse}, but the result may -share memory with the the strings in the @var{ls} arguments. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Fold/Unfold/Map -@subsubsection Fold/Unfold/Map - -@code{string-map}, @code{string-for-each} etc. are for iterating over -the characters a string is composed of. The fold and unfold procedures -are list iterators and constructors. - -@deffn {Scheme Procedure} string-map proc s [start end] -@var{proc} is a char->char procedure, it is mapped over -@var{s}. The order in which the procedure is applied to the -string elements is not specified. -@end deffn - -@deffn {Scheme Procedure} string-map! proc s [start end] -@var{proc} is a char->char procedure, it is mapped over -@var{s}. The order in which the procedure is applied to the -string elements is not specified. The string @var{s} is -modified in-place, the return value is not specified. -@end deffn - -@deffn {Scheme Procedure} string-fold kons knil s [start end] -@deffnx {Scheme Procedure} string-fold-right kons knil s [start end] -Fold @var{kons} over the characters of @var{s}, with @var{knil} as the -terminating element, from left to right (or right to left, for -@code{string-fold-right}). @var{kons} must expect two arguments: The -actual character and the last result of @var{kons}' application. -@end deffn - -@deffn {Scheme Procedure} string-unfold p f g seed [base make_final] -@deffnx {Scheme Procedure} string-unfold-right p f g seed [base make_final] -These are the fundamental string constructors. -@itemize @bullet -@item @var{g} is used to generate a series of @emph{seed} -values from the initial @var{seed}: @var{seed}, (@var{g} -@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), -@dots{} -@item @var{p} tells us when to stop - when it returns true -when applied to one of these seed values. -@item @var{f} maps each seed value to the corresponding -character in the result string. These chars are assembled into the -string in a left-to-right (right-to-left) order. -@item @var{base} is the optional initial/leftmost (rightmost) - portion of the constructed string; it default to the empty string. -@item @var{make_final} is applied to the terminal seed -value (on which @var{p} returns true) to produce the final/rightmost -(leftmost) portion of the constructed string. It defaults to -@code{(lambda (x) "")}. -@end itemize -@end deffn - -@deffn {Scheme Procedure} string-for-each proc s [start end] -@var{proc} is mapped over @var{s} in left-to-right order. The -return value is not specified. -@end deffn - -@deffn {Scheme Procedure} string-for-each-index proc s [start [end]] -@deffnx {C Function} scm_string_for_each_index (proc, s, start, end) -@var{proc} is mapped over @var{s} in left-to-right order. The -return value is not specified. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Replicate/Rotate -@subsubsection Replicate/Rotate - -These procedures are special substring procedures, which can also be -used for replicating strings. They are a bit tricky to use, but -consider this code fragment, which replicates the input string -@code{"foo"} so often that the resulting string has a length of six. - -@lisp -(xsubstring "foo" 0 6) -@result{} -"foofoo" -@end lisp - -@deffn {Scheme Procedure} xsubstring s from [to start end] -This is the @emph{extended substring} procedure that implements -replicated copying of a substring of some string. - -@var{s} is a string, @var{start} and @var{end} are optional -arguments that demarcate a substring of @var{s}, defaulting to -0 and the length of @var{s}. Replicate this substring up and -down index space, in both the positive and negative directions. -@code{xsubstring} returns the substring of this string -beginning at index @var{from}, and ending at @var{to}, which -defaults to @var{from} + (@var{end} - @var{start}). -@end deffn - -@deffn {Scheme Procedure} string-xcopy! target tstart s sfrom [sto start end] -Exactly the same as @code{xsubstring}, but the extracted text -is written into the string @var{target} starting at index -@var{tstart}. The operation is not defined if @code{(eq? -@var{target} @var{s})} or these arguments share storage - you -cannot copy a string on top of itself. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Miscellaneous -@subsubsection Miscellaneous - -@code{string-replace} is for replacing a portion of a string with -another string and @code{string-tokenize} splits a string into a list of -strings, breaking it up at a specified character. - -@deffn {Scheme Procedure} string-replace s1 s2 [start1 end1 start2 end2] -Return the string @var{s1}, but with the characters -@var{start1} @dots{} @var{end1} replaced by the characters -@var{start2} @dots{} @var{end2} from @var{s2}. - -For reference, note that SRFI-13 specifies @var{start1} and @var{end1} -as mandatory, but in Guile they are optional. -@end deffn - -@deffn {Scheme Procedure} string-tokenize s [token-set start end] -Split the string @var{s} into a list of substrings, where each -substring is a maximal non-empty contiguous sequence of characters -from the character set @var{token_set}, which defaults to an -equivalent of @code{char-set:graphic}. If @var{start} or @var{end} -indices are provided, they restrict @code{string-tokenize} to -operating on the indicated substring of @var{s}. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Filtering/Deleting -@subsubsection Filtering/Deleting - -@dfn{Filtering} means to remove all characters from a string which do -not match a given criteria, @dfn{deleting} means the opposite. - -@deffn {Scheme Procedure} string-filter s char_pred [start end] -Filter the string @var{s}, retaining only those characters that -satisfy the @var{char_pred} argument. If the argument is a -procedure, it is applied to each character as a predicate, if -it is a character, it is tested for equality and if it is a -character set, it is tested for membership. -@end deffn - -@deffn {Scheme Procedure} string-delete s char_pred [start end] -Filter the string @var{s}, retaining only those characters that -do not satisfy the @var{char_pred} argument. If the argument -is a procedure, it is applied to each character as a predicate, -if it is a character, it is tested for equality and if it is a -character set, it is tested for membership. -@end deffn - +The SRFI-13 procedures are always available, @xref{Strings}. @node SRFI-14 @subsection SRFI-14 - Character-set Library