(lispref.info)Creating Strings


Next: Text Comparison Prev: Predicates for Strings Up: Strings and Characters

Creating Strings
================

   The following functions create strings, either from scratch, or by
putting strings together, or by taking them apart.

 - Function: make-string COUNT CHARACTER
     This function returns a string made up of COUNT repetitions of
     CHARACTER.  If COUNT is negative, an error is signaled.

          (make-string 5 ?x)
               => "xxxxx"
          (make-string 0 ?x)
               => ""

     Other functions to compare with this one include `char-to-string'
     (Note: String Conversion.), `make-vector' (Note: Vectors.), and
     `make-list' (Note: Building Lists.).

 - Function: substring STRING START &optional END
     This function returns a new string which consists of those
     characters from STRING in the range from (and including) the
     character at the index START up to (but excluding) the character
     at the index END.  The first character is at index zero.

          (substring "abcdefg" 0 3)
               => "abc"

     Here the index for `a' is 0, the index for `b' is 1, and the index
     for `c' is 2.  Thus, three letters, `abc', are copied from the
     full string.  The index 3 marks the character position up to which
     the substring is copied.  The character whose index is 3 is
     actually the fourth character in the string.

     A negative number counts from the end of the string, so that -1
     signifies the index of the last character of the string.  For
     example:

          (substring "abcdefg" -3 -1)
               => "ef"

     In this example, the index for `e' is -3, the index for `f' is -2,
     and the index for `g' is -1.  Therefore, `e' and `f' are included,
     and `g' is excluded.

     When `nil' is used as an index, it falls after the last character
     in the string.  Thus:

          (substring "abcdefg" -3 nil)
               => "efg"

     Omitting the argument END is equivalent to specifying `nil'.  It
     follows that `(substring STRING 0)' returns a copy of all of
     STRING.

          (substring "abcdefg" 0)
               => "abcdefg"

     But we recommend `copy-sequence' for this purpose (Note: Sequence
     Functions.).

     A `wrong-type-argument' error is signaled if either START or END
     are non-integers.  An `args-out-of-range' error is signaled if
     START indicates a character following END, or if either integer is
     out of range for STRING.

     Contrast this function with `buffer-substring' (Note: Buffer
     Contents.), which returns a string containing a portion of the
     text in the current buffer.  The beginning of a string is at index
     0, but the beginning of a buffer is at index 1.

 - Function: concat &rest SEQUENCES
     This function returns a new string consisting of the characters in
     the arguments passed to it.  The arguments may be strings, lists
     of numbers, or vectors of numbers; they are not themselves
     changed.  If no arguments are passed to `concat', it returns an
     empty string.

          (concat "abc" "-def")
               => "abc-def"
          (concat "abc" (list 120 (+ 256 121)) [122])
               => "abcxyz"
          (concat "The " "quick brown " "fox.")
               => "The quick brown fox."
          (concat)
               => ""

     The second example above shows how characters stored in strings are
     taken modulo 256.  In other words, each character in the string is
     stored in one byte.

     The `concat' function always constructs a new string that is not
     `eq' to any existing string.

     When an argument is an integer (not a sequence of integers), it is
     converted to a string of digits making up the decimal printed
     representation of the integer.  This special case exists for
     compatibility with Mocklisp, and we don't recommend you take
     advantage of it.  If you want to convert an integer in this way,
     use `format' (Note: Formatting Strings.) or `int-to-string'
     (Note: String Conversion.).

          (concat 137)
               => "137"
          (concat 54 321)
               => "54321"

     For information about other concatenation functions, see the
     description of `mapconcat' in Note: Mapping Functions, `vconcat'
     in Note: Vectors, and `append' in Note: Building Lists.


automatically generated by info2www