diff options
Diffstat (limited to 'devdocs/elisp/creating-strings.html')
| -rw-r--r-- | devdocs/elisp/creating-strings.html | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/devdocs/elisp/creating-strings.html b/devdocs/elisp/creating-strings.html new file mode 100644 index 00000000..367fb7b4 --- /dev/null +++ b/devdocs/elisp/creating-strings.html @@ -0,0 +1,116 @@ + <h3 class="section">Creating Strings</h3> <p>The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. (For functions that create strings based on the modified contents of other strings, like <code>string-replace</code> and <code>replace-regexp-in-string</code>, see <a href="search-and-replace">Search and Replace</a>.) </p> <dl> <dt id="make-string">Function: <strong>make-string</strong> <em>count character &optional multibyte</em> +</dt> <dd> +<p>This function returns a string made up of <var>count</var> repetitions of <var>character</var>. If <var>count</var> is negative, an error is signaled. </p> <div class="example"> <pre class="example">(make-string 5 ?x) + ⇒ "xxxxx" +(make-string 0 ?x) + ⇒ "" +</pre> +</div> <p>Normally, if <var>character</var> is an <acronym>ASCII</acronym> character, the result is a unibyte string. But if the optional argument <var>multibyte</var> is non-<code>nil</code>, the function will produce a multibyte string instead. This is useful when you later need to concatenate the result with non-<acronym>ASCII</acronym> strings or replace some of its characters with non-<acronym>ASCII</acronym> characters. </p> <p>Other functions to compare with this one include <code>make-vector</code> (see <a href="vectors">Vectors</a>) and <code>make-list</code> (see <a href="building-lists">Building Lists</a>). </p> +</dd> +</dl> <dl> <dt id="string">Function: <strong>string</strong> <em>&rest characters</em> +</dt> <dd> +<p>This returns a string containing the characters <var>characters</var>. </p> <div class="example"> <pre class="example">(string ?a ?b ?c) + ⇒ "abc" +</pre> +</div> </dd> +</dl> <dl> <dt id="substring">Function: <strong>substring</strong> <em>string &optional start end</em> +</dt> <dd> +<p>This function returns a new string which consists of those characters from <var>string</var> in the range from (and including) the character at the index <var>start</var> up to (but excluding) the character at the index <var>end</var>. The first character is at index zero. With one argument, this function just copies <var>string</var>. </p> <div class="example"> <pre class="example">(substring "abcdefg" 0 3) + ⇒ "abc" +</pre> +</div> <p>In the above example, the index for ‘<samp>a</samp>’ is 0, the index for ‘<samp>b</samp>’ is 1, and the index for ‘<samp>c</samp>’ is 2. The index 3—which is the fourth character in the string—marks the character position up to which the substring is copied. Thus, ‘<samp>abc</samp>’ is copied from the string <code>"abcdefg"</code>. </p> <p>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: </p> <div class="example"> <pre class="example">(substring "abcdefg" -3 -1) + ⇒ "ef" +</pre> +</div> <p>In this example, the index for ‘<samp>e</samp>’ is -3, the index for ‘<samp>f</samp>’ is -2, and the index for ‘<samp>g</samp>’ is -1. Therefore, ‘<samp>e</samp>’ and ‘<samp>f</samp>’ are included, and ‘<samp>g</samp>’ is excluded. </p> <p>When <code>nil</code> is used for <var>end</var>, it stands for the length of the string. Thus, </p> <div class="example"> <pre class="example">(substring "abcdefg" -3 nil) + ⇒ "efg" +</pre> +</div> <p>Omitting the argument <var>end</var> is equivalent to specifying <code>nil</code>. It follows that <code>(substring <var>string</var> 0)</code> returns a copy of all of <var>string</var>. </p> <div class="example"> <pre class="example">(substring "abcdefg" 0) + ⇒ "abcdefg" +</pre> +</div> <p>But we recommend <code>copy-sequence</code> for this purpose (see <a href="sequence-functions">Sequence Functions</a>). </p> <p>If the characters copied from <var>string</var> have text properties, the properties are copied into the new string also. See <a href="text-properties">Text Properties</a>. </p> <p><code>substring</code> also accepts a vector for the first argument. For example: </p> <div class="example"> <pre class="example">(substring [a b (c) "d"] 1 3) + ⇒ [b (c)] +</pre> +</div> <p>A <code>wrong-type-argument</code> error is signaled if <var>start</var> is not an integer or if <var>end</var> is neither an integer nor <code>nil</code>. An <code>args-out-of-range</code> error is signaled if <var>start</var> indicates a character following <var>end</var>, or if either integer is out of range for <var>string</var>. </p> <p>Contrast this function with <code>buffer-substring</code> (see <a href="buffer-contents">Buffer Contents</a>), 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. </p> +</dd> +</dl> <dl> <dt id="substring-no-properties">Function: <strong>substring-no-properties</strong> <em>string &optional start end</em> +</dt> <dd><p>This works like <code>substring</code> but discards all text properties from the value. Also, <var>start</var> may be omitted or <code>nil</code>, which is equivalent to 0. Thus, <code><span class="nolinebreak">(substring-no-properties</span> <var>string</var>)</code> returns a copy of <var>string</var>, with all text properties removed. </p></dd> +</dl> <dl> <dt id="concat">Function: <strong>concat</strong> <em>&rest sequences</em> +</dt> <dd> + <p>This function returns a 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 <code>concat</code> receives no arguments, it returns an empty string. </p> <div class="example"> <pre class="example">(concat "abc" "-def") + ⇒ "abc-def" +(concat "abc" (list 120 121) [122]) + ⇒ "abcxyz" +;; <span class="roman"><code>nil</code> is an empty sequence.</span> +(concat "abc" nil "-def") + ⇒ "abc-def" +(concat "The " "quick brown " "fox.") + ⇒ "The quick brown fox." +(concat) + ⇒ "" +</pre> +</div> <p>This function does not always allocate a new string. Callers are advised not rely on the result being a new string nor on it being <code>eq</code> to an existing string. </p> <p>In particular, mutating the returned value may inadvertently change another string, alter a constant string in the program, or even raise an error. To obtain a string that you can safely mutate, use <code>copy-sequence</code> on the result. </p> <p>For information about other concatenation functions, see the description of <code>mapconcat</code> in <a href="mapping-functions">Mapping Functions</a>, <code>vconcat</code> in <a href="vector-functions">Vector Functions</a>, and <code>append</code> in <a href="building-lists">Building Lists</a>. For concatenating individual command-line arguments into a string to be used as a shell command, see <a href="shell-arguments">combine-and-quote-strings</a>. </p> +</dd> +</dl> <dl> <dt id="split-string">Function: <strong>split-string</strong> <em>string &optional separators omit-nulls trim</em> +</dt> <dd> +<p>This function splits <var>string</var> into substrings based on the regular expression <var>separators</var> (see <a href="regular-expressions">Regular Expressions</a>). Each match for <var>separators</var> defines a splitting point; the substrings between splitting points are made into a list, which is returned. </p> <p>If <var>separators</var> is <code>nil</code> (or omitted), the default is the value of <code>split-string-default-separators</code> and the function behaves as if <var>omit-nulls</var> were <code>t</code>. </p> <p>If <var>omit-nulls</var> is <code>nil</code> (or omitted), the result contains null strings whenever there are two consecutive matches for <var>separators</var>, or a match is adjacent to the beginning or end of <var>string</var>. If <var>omit-nulls</var> is <code>t</code>, these null strings are omitted from the result. </p> <p>If the optional argument <var>trim</var> is non-<code>nil</code>, it should be a regular expression to match text to trim from the beginning and end of each substring. If trimming makes the substring empty, it is treated as null. </p> <p>If you need to split a string into a list of individual command-line arguments suitable for <code>call-process</code> or <code>start-process</code>, see <a href="shell-arguments">split-string-and-unquote</a>. </p> <p>Examples: </p> <div class="example"> <pre class="example">(split-string " two words ") + ⇒ ("two" "words") +</pre> +</div> <p>The result is not <code>("" "two" "words" "")</code>, which would rarely be useful. If you need such a result, use an explicit value for <var>separators</var>: </p> <div class="example"> <pre class="example">(split-string " two words " + split-string-default-separators) + ⇒ ("" "two" "words" "") +</pre> +</div> <div class="example"> <pre class="example">(split-string "Soup is good food" "o") + ⇒ ("S" "up is g" "" "d f" "" "d") +(split-string "Soup is good food" "o" t) + ⇒ ("S" "up is g" "d f" "d") +(split-string "Soup is good food" "o+") + ⇒ ("S" "up is g" "d f" "d") +</pre> +</div> <p>Empty matches do count, except that <code>split-string</code> will not look for a final empty match when it already reached the end of the string using a non-empty match or when <var>string</var> is empty: </p> <div class="example"> <pre class="example">(split-string "aooob" "o*") + ⇒ ("" "a" "" "b" "") +(split-string "ooaboo" "o*") + ⇒ ("" "" "a" "b" "") +(split-string "" "") + ⇒ ("") +</pre> +</div> <p>However, when <var>separators</var> can match the empty string, <var>omit-nulls</var> is usually <code>t</code>, so that the subtleties in the three previous examples are rarely relevant: </p> <div class="example"> <pre class="example">(split-string "Soup is good food" "o*" t) + ⇒ ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") +(split-string "Nice doggy!" "" t) + ⇒ ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!") +(split-string "" "" t) + ⇒ nil +</pre> +</div> <p>Somewhat odd, but predictable, behavior can occur for certain “non-greedy” values of <var>separators</var> that can prefer empty matches over non-empty matches. Again, such values rarely occur in practice: </p> <div class="example"> <pre class="example">(split-string "ooo" "o*" t) + ⇒ nil +(split-string "ooo" "\\|o+" t) + ⇒ ("o" "o" "o") +</pre> +</div> </dd> +</dl> <dl> <dt id="split-string-default-separators">Variable: <strong>split-string-default-separators</strong> +</dt> <dd><p>The default value of <var>separators</var> for <code>split-string</code>. Its usual value is <code>"[ \f\t\n\r\v]+"</code>. </p></dd> +</dl> <dl> <dt id="string-clean-whitespace">Function: <strong>string-clean-whitespace</strong> <em>string</em> +</dt> <dd><p>Clean up the whitespace in <var>string</var> by collapsing stretches of whitespace to a single space character, as well as removing all whitespace from the start and the end of <var>string</var>. </p></dd> +</dl> <dl> <dt id="string-trim-left">Function: <strong>string-trim-left</strong> <em>string &optional regexp</em> +</dt> <dd><p>Remove the leading text that matches <var>regexp</var> from <var>string</var>. <var>regexp</var> defaults to ‘<samp>[ \t\n\r]+</samp>’. </p></dd> +</dl> <dl> <dt id="string-trim-right">Function: <strong>string-trim-right</strong> <em>string &optional regexp</em> +</dt> <dd><p>Remove the trailing text that matches <var>regexp</var> from <var>string</var>. <var>regexp</var> defaults to ‘<samp>[ \t\n\r]+</samp>’. </p></dd> +</dl> <dl> <dt id="string-trim">Function: <strong>string-trim</strong> <em>string &optional trim-left trim-right</em> +</dt> <dd><p>Remove the leading text that matches <var>trim-left</var> and trailing text that matches <var>trim-right</var> from <var>string</var>. Both regexps default to ‘<samp>[ \t\n\r]+</samp>’. </p></dd> +</dl> <dl> <dt id="string-fill">Function: <strong>string-fill</strong> <em>string length</em> +</dt> <dd><p>Attempt to Word-wrap <var>string</var> so that no lines are longer than <var>length</var>. Filling is done on whitespace boundaries only. If there are individual words that are longer than <var>length</var>, these will not be shortened. </p></dd> +</dl> <dl> <dt id="string-limit">Function: <strong>string-limit</strong> <em>string length &optional end coding-system</em> +</dt> <dd> +<p>If <var>string</var> is shorter than <var>length</var> characters, <var>string</var> is returned as is. Otherwise, return a substring of <var>string</var> consisting of the first <var>length</var> characters. If the optional <var>end</var> parameter is given, return a string of the <var>length</var> last characters instead. </p> <p>If <var>coding-system</var> is non-<code>nil</code>, <var>string</var> will be encoded before limiting, and the result will be a unibyte string that’s shorter than <code>length</code> bytes. If <var>string</var> contains characters that are encoded into several bytes (for instance, when using <code>utf-8</code>), the resulting unibyte string is never truncated in the middle of a character representation. </p> <p>This function measures the string length in characters or bytes, and thus is generally inappropriate if you need to shorten strings for display purposes; use <code>truncate-string-to-width</code> or <code>window-text-pixel-size</code> instead (see <a href="size-of-displayed-text">Size of Displayed Text</a>). </p> +</dd> +</dl> <dl> <dt id="string-lines">Function: <strong>string-lines</strong> <em>string &optional omit-nulls</em> +</dt> <dd><p>Split <var>string</var> into a list of strings on newline boundaries. If <var>omit-nulls</var>, remove empty lines from the results. </p></dd> +</dl> <dl> <dt id="string-pad">Function: <strong>string-pad</strong> <em>string length &optional padding start</em> +</dt> <dd><p>Pad <var>string</var> to be of the given <var>length</var> using <var>padding</var> as the padding character. <var>padding</var> defaults to the space character. If <var>string</var> is longer than <var>length</var>, no padding is done. If <var>start</var> is <code>nil</code> or omitted, the padding is appended to the characters of <var>string</var>, and if it’s non-<code>nil</code>, the padding is prepended to <var>string</var>’s characters. </p></dd> +</dl> <dl> <dt id="string-chop-newline">Function: <strong>string-chop-newline</strong> <em>string</em> +</dt> <dd><p>Remove the final newline, if any, from <var>string</var>. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Creating-Strings.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Creating-Strings.html</a> + </p> +</div> |