GNU Info

(guile.info)String Fun

---

Next: Shared Substrings Up: Strings

---

Enter node , (file) or (file)node

String Fun
----------

 - primitive: string . chrs
 - primitive: list->string chrs
     Returns a newly allocated string composed of the arguments, CHRS.

 - primitive: make-string k [chr]
     Returns a newly allocated string of length K.  If CHR is given,
     then all elements of the string are initialized to CHR, otherwise
     the contents of the STRING are unspecified.

 - primitive: string-append . args
     Returns a newly allocated string whose characters form the
     concatenation of the given strings, ARGS.

 - primitive: string-length string
     Returns the number of characters in STRING

 - primitive: string-ref str k
     Returns character K of STR using zero-origin indexing.  K must be
     a valid index of STR.

 - primitive: string-set! str k chr
     Stores CHR in element K of STRING and returns an unspecified value.
     K must be a valid index of STR.

 - primitive: string? obj
     Returns #t iff OBJ is a string, else returns #f.

 - primitive: substring str start [end]
     Returns a newly allocated string formed from the characters of STR
     beginning with index START (inclusive) and ending with index END
     (exclusive).  STR must be a string, START and END must be exact
     integers satisfying:

     0 <= START <= END <= (string-length STR).

 - primitive: string-index str chr [frm [to]]
     Return the index of the first occurrence of CHR in STR.  The
     optional integer arguments FRM and TO limit the search to a
     portion of the string.  This procedure essentially implements the
     `index' or `strchr' functions from the C library.

     (qdocs:)  Returns the index of CHAR in STR, or `#f' if the CHAR
     isn't in STR. If FRM is given and not `#f', it is used as the
     starting index; if TO is given and not #F, it is used as the
     ending index (exclusive).

          (string-index "weiner" #\e)
          => 1
          
          (string-index "weiner" #\e 2)
          => 4
          
          (string-index "weiner" #\e 2 4)
          => #f

 - primitive: string-rindex str chr [frm [to]]
     Like `string-index', but search from the right of the string rather
     than from the left.  This procedure essentially implements the
     `rindex' or `strrchr' functions from the C library.

     (qdocs:) The same as `string-index', except it gives the rightmost
     occurance of CHAR in the range [FRM, TO-1], which defaults to the
     entire string.

          (string-rindex "weiner" #\e)
          => 4
          
          (string-rindex "weiner" #\e 2 4)
          => #f
          
          (string-rindex "weiner" #\e 2 5)
          => 4

 - primitive: substring-move! str1 start1 end1 str2 start2
 - primitive: substring-move-left! str1 start1 end1 str2 start2
 - primitive: substring-move-right! str1 start1 end1 str2 start2
     Copy the substring of STR1 bounded by START1 and END1 into STR2
     beginning at position END2.  `substring-move-right!' begins
     copying from the rightmost character and moves left, and
     `substring-move-left!' copies from the leftmost character moving
     right.

     It is useful to have two functions that copy in different
     directions so that substrings can be copied back and forth within
     a single string.  If you wish to copy text from the left-hand side
     of a string to the right-hand side of the same string, and the
     source and destination overlap, you must be careful to copy the
     rightmost characters of the text first, to avoid clobbering your
     data.  Hence, when STR1 and STR2 are the same string, you should
     use `substring-move-right!' when moving text from left to right,
     and `substring-move-left!'  otherwise.  If `str1' and `str2' are
     different strings, it does not matter which function you use.

 - primitive: substring-move-left! str1 start1 end1 str2 start2

 - C Function: SCM scm_substring_move_left_x (SCM STR1, SCM START1, SCM
          END1, SCM STR2, SCM START2)
     [*Note:* this is only valid if you've applied the strop patch].

     Moves a substring of STR1, from START1 to END1 (END1 is
     exclusive), into STR2, starting at START2. Allows overlapping
     strings.

          (define x (make-string 10 #\a))
          (define y "bcd")
          (substring-move-left! x 2 5 y 0)
          y
          => "aaa"
          
          x
          => "aaaaaaaaaa"
          
          (define y "bcdefg")
          (substring-move-left! x 2 5 y 0)
          y
          => "aaaefg"
          
          (define y "abcdefg")
          (substring-move-left! y 2 5 y 3)
          y
          => "abccccg"

 - substring-move-right!: str1 start1 end1 str2 start2

 - C Function: SCM scm_substring_move_right_x (SCM STR1, SCM START1,
          SCM END1, SCM STR2, SCM START2)
     [*Note:* this is only valid if you've applied the strop patch, if
     it hasn't made it into the guile tree].

     Does much the same thing as `substring-move-left!', except it
     starts moving at the end of the sequence, rather than the
     beginning.
          (define y "abcdefg")
          (substring-move-right! y 2 5 y 0)
          y
          => "ededefg"
          
          (define y "abcdefg")
          (substring-move-right! y 2 5 y 3)
          y
          => "abccdeg"

 - primitive: vector-move-left! vec1 start1 end1 vec2 start2
     Vector version of `substring-move-left!'.

 - primitive: vector-move-right! vec1 start1 end1 vec2 start2
     Vector version of `substring-move-right!'.

 - primitive: substring-fill! str start end fill
     Change every character in STR between START and END to FILL-CHAR.

     (qdocs:) Destructively fills STR, from START to END, with FILL.

          (define y "abcdefg")
          (substring-fill! y 1 3 #\r)
          y
          => "arrdefg"

 - primitive: string-null? str
     Return `#t' if STR's length is nonzero, and `#f' otherwise.

     (qdocs:) Returns `#t' if STR is empty, else returns `#f'.

          (string-null? "")
          => #t
          
          (string-null? y)
          => #f

 - primitive: string-upcase! v
     Destructively upcase every character in `str'.

     (qdocs:) Converts each element in STR to upper case.

          (string-upcase! y)
          => "ARRDEFG"
          
          y
          => "ARRDEFG"

 - primitive: string-upcase str
     Upcase every character in `str'.

 - primitive: string-downcase! v
     Destructively downcase every character in `str'.

     (qdocs:) Converts each element in STR to lower case.

          y
          => "ARRDEFG"
          
          (string-downcase! y)
          => "arrdefg"
          
          y
          => "arrdefg"

 - primitive: string-downcase str
     Downcase every character in `str'.

 - primitive: string-capitalize! str
     Destructively capitalize every character in `str'.

 - primitive: string-capitalize str
     Capitalize every character in `str'.

 - primitive: string-ci<=? s1 s2
     Case insensitive lexicographic ordering predicate; returns #t if
     S1 is lexicographically less than or equal to S2 regardless of
     case.  (r5rs)

 - primitive: string-ci<? s1 s2
     Case insensitive lexicographic ordering predicate; returns #t if
     S1 is lexicographically less than S2 regardless of case.  (r5rs)

 - primitive: string-ci=? s1 s2
     Case-insensitive string equality predicate; returns #t if the two
     strings are the same length and their component characters match
     (ignoring case) at each position; otherwise returns #f. (r5rs)

 - primitive: string-ci>=? s1 s2
     Case insensitive lexicographic ordering predicate; returns #t if
     S1 is lexicographically greater than or equal to S2 regardless of
     case.  (r5rs)

 - primitive: string-ci>? s1 s2
     Case insensitive lexicographic ordering predicate; returns #t if
     S1 is lexicographically greater than S2 regardless of case.  (r5rs)

 - primitive: string<=? s1 s2
     Lexicographic ordering predicate; returns #t if S1 is
     lexicographically less than or equal to S2.  (r5rs)

 - primitive: string<? s1 s2
     Lexicographic ordering predicate; returns #t if S1 is
     lexicographically less than S2.  (r5rs)

 - primitive: string=? s1 s2
     Lexicographic equality predicate; Returns #t if the two strings
     are the same length and contain the same characters in the same
     positions, otherwise returns #f. (r5rs)

     `String-ci=?' treats upper and lower case letters as though they
     were the same character, but `string=?' treats upper and lower
     case as distinct characters.

 - primitive: string>=? s1 s2
     Lexicographic ordering predicate; returns #t if S1 is
     lexicographically greater than or equal to S2.  (r5rs)

 - primitive: string>? s1 s2
     Lexicographic ordering predicate; returns #t if S1 is
     lexicographically greater than S2.  (r5rs)

 - primitive: string->list str
     `String->list' returns a newly allocated list of the characters
     that make up the given string.  `List->string' returns a newly
     allocated string formed from the characters in the list LIST,
     which must be a list of characters. `String->list' and
     `list->string' are inverses so far as `equal?' is concerned.
     (r5rs)

 - primitive: string-ci->symbol str
     Return the symbol whose name is STR, downcased in necessary(???).

 - primitive: string-copy str
     Returns a newly allocated copy of the given STRING. (r5rs)

 - primitive: string-fill! str chr
     Stores CHAR in every element of the given STRING and returns an
     unspecified value.  (r5rs)