GNU Info

(elisp)Creating Strings

---

Next: Modifying Strings Prev: Predicates for Strings Up: Strings and Characters

---

Enter node , (file) or (file)node

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: string &rest characters
     This returns a string containing the characters CHARACTERS.

          (string ?a ?b ?c)
               => "abc"

 - 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
     string `"abcdefg"'.  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 stands for the length of 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).

     If the characters copied from STRING have text properties, the
     properties are copied into the new string also.  Note: Text
     Properties.

     `substring' also accepts a vector for the first argument.  For
     example:

          (substring [a b (c) "d"] 1 3)
               => [b (c)]

     A `wrong-type-argument' error is signaled if either START or END
     is not an integer or `nil'.  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 (along with their text properties, if
     any).  The arguments may be strings, lists of numbers, or vectors
     of numbers; they are not themselves changed.  If `concat' receives
     no arguments, it returns an empty string.

          (concat "abc" "-def")
               => "abc-def"
          (concat "abc" (list 120 121) [122])
               => "abcxyz"
          ;; `nil' is an empty sequence.
          (concat "abc" nil "-def")
               => "abc-def"
          (concat "The " "quick brown " "fox.")
               => "The quick brown fox."
          (concat)
               => ""

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

     In Emacs versions before 21, when an argument was an integer (not a
     sequence of integers), it was converted to a string of digits
     making up the decimal printed representation of the integer.  This
     obsolete usage no longer works.  The proper way to convert an
     integer to its decimal printed form is with `format' (Note:
     Formatting Strings) or `number-to-string' (Note: String
     Conversion).

     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.

 - Function: split-string string separators
     This function splits STRING into substrings at matches for the
     regular expression SEPARATORS.  Each match for SEPARATORS defines a
     splitting point; the substrings between the splitting points are
     made into a list, which is the value returned by `split-string'.
     If SEPARATORS is `nil' (or omitted), the default is `"[
     \f\t\n\r\v]+"'.

     For example,

          (split-string "Soup is good food" "o")
          => ("S" "up is g" "" "d f" "" "d")
          (split-string "Soup is good food" "o+")
          => ("S" "up is g" "d f" "d")

     When there is a match adjacent to the beginning or end of the
     string, this does not cause a null string to appear at the
     beginning or end of the list:

          (split-string "out to moo" "o+")
          => ("ut t" " m")

     Empty matches do count, when not adjacent to another match:

          (split-string "Soup is good food" "o*")
          =>("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
          (split-string "Nice doggy!" "")
          =>("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")