path: root/devdocs/elisp/sequence-functions.html

 <h3 class="section">Sequences</h3> <p>This section describes functions that accept any kind of sequence. </p> <dl> <dt id="sequencep">Function: <strong>sequencep</strong> <em>object</em>
</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is a list, vector, string, bool-vector, or char-table, <code>nil</code> otherwise. See also <code>seqp</code> below. </p></dd>
</dl> <dl> <dt id="length">Function: <strong>length</strong> <em>sequence</em>
</dt> <dd>
      <p>This function returns the number of elements in <var>sequence</var>. The function signals the <code>wrong-type-argument</code> error if the argument is not a sequence or is a dotted list; it signals the <code>circular-list</code> error if the argument is a circular list. For a char-table, the value returned is always one more than the maximum Emacs character code. </p> <p>See <a href="list-elements#Definition-of-safe_002dlength">Definition of safe-length</a>, for the related function <code>safe-length</code>. </p> <div class="example"> <pre class="example">(length '(1 2 3))
    ⇒ 3
</pre>
<pre class="example">(length ())
    ⇒ 0
</pre>
<pre class="example">(length "foobar")
    ⇒ 6
</pre>
<pre class="example">(length [1 2 3])
    ⇒ 3
</pre>
<pre class="example">(length (make-bool-vector 5 nil))
    ⇒ 5
</pre>
</div> </dd>
</dl> <p>See also <code>string-bytes</code>, in <a href="text-representations">Text Representations</a>. </p> <p>If you need to compute the width of a string on display, you should use <code>string-width</code> (see <a href="size-of-displayed-text">Size of Displayed Text</a>), not <code>length</code>, since <code>length</code> only counts the number of characters, but does not account for the display width of each character. </p> <dl> <dt id="length&lt;">Function: <strong>length&lt;</strong> <em>sequence length</em>
</dt> <dd><p>Return non-<code>nil</code> if <var>sequence</var> is shorter than <var>length</var>. This may be more efficient than computing the length of <var>sequence</var> if <var>sequence</var> is a long list. </p></dd>
</dl> <dl> <dt id="length&gt;">Function: <strong>length&gt;</strong> <em>sequence length</em>
</dt> <dd><p>Return non-<code>nil</code> if <var>sequence</var> is longer than <var>length</var>. </p></dd>
</dl> <dl> <dt id="length=">Function: <strong>length=</strong> <em>sequence length</em>
</dt> <dd><p>Return non-<code>nil</code> if the length of <var>sequence</var> is equal to <var>length</var>. </p></dd>
</dl> <dl> <dt id="elt">Function: <strong>elt</strong> <em>sequence index</em>
</dt> <dd>
 <p>This function returns the element of <var>sequence</var> indexed by <var>index</var>. Legitimate values of <var>index</var> are integers ranging from 0 up to one less than the length of <var>sequence</var>. If <var>sequence</var> is a list, out-of-range values behave as for <code>nth</code>. See <a href="list-elements#Definition-of-nth">Definition of nth</a>. Otherwise, out-of-range values trigger an <code>args-out-of-range</code> error. </p> <div class="example"> <pre class="example">(elt [1 2 3 4] 2)
     ⇒ 3
</pre>
<pre class="example">(elt '(1 2 3 4) 2)
     ⇒ 3
</pre>
<pre class="example">;; <span class="roman">We use <code>string</code> to show clearly which character <code>elt</code> returns.</span>
(string (elt "1234" 2))
     ⇒ "3"
</pre>
<pre class="example">(elt [1 2 3 4] 4)
     error→ Args out of range: [1 2 3 4], 4
</pre>
<pre class="example">(elt [1 2 3 4] -1)
     error→ Args out of range: [1 2 3 4], -1
</pre>
</div> <p>This function generalizes <code>aref</code> (see <a href="array-functions">Array Functions</a>) and <code>nth</code> (see <a href="list-elements#Definition-of-nth">Definition of nth</a>). </p>
</dd>
</dl> <dl> <dt id="copy-sequence">Function: <strong>copy-sequence</strong> <em>seqr</em>
</dt> <dd>
 <p>This function returns a copy of <var>seqr</var>, which should be either a sequence or a record. The copy is the same type of object as the original, and it has the same elements in the same order. However, if <var>seqr</var> is empty, like a string or a vector of zero length, the value returned by this function might not be a copy, but an empty object of the same type and identical to <var>seqr</var>. </p> <p>Storing a new element into the copy does not affect the original <var>seqr</var>, and vice versa. However, the elements of the copy are not copies; they are identical (<code>eq</code>) to the elements of the original. Therefore, changes made within these elements, as found via the copy, are also visible in the original. </p> <p>If the argument is a string with text properties, the property list in the copy is itself a copy, not shared with the original’s property list. However, the actual values of the properties are shared. See <a href="text-properties">Text Properties</a>. </p> <p>This function does not work for dotted lists. Trying to copy a circular list may cause an infinite loop. </p> <p>See also <code>append</code> in <a href="building-lists">Building Lists</a>, <code>concat</code> in <a href="creating-strings">Creating Strings</a>, and <code>vconcat</code> in <a href="vector-functions">Vector Functions</a>, for other ways to copy sequences. </p> <div class="example"> <pre class="example">(setq bar (list 1 2))
     ⇒ (1 2)
</pre>
<pre class="example">(setq x (vector 'foo bar))
     ⇒ [foo (1 2)]
</pre>
<pre class="example">(setq y (copy-sequence x))
     ⇒ [foo (1 2)]
</pre>

<pre class="example">(eq x y)
     ⇒ nil
</pre>
<pre class="example">(equal x y)
     ⇒ t
</pre>
<pre class="example">(eq (elt x 1) (elt y 1))
     ⇒ t
</pre>

<pre class="example">;; <span class="roman">Replacing an element of one sequence.</span>
(aset x 0 'quux)
x ⇒ [quux (1 2)]
y ⇒ [foo (1 2)]
</pre>

<pre class="example">;; <span class="roman">Modifying the inside of a shared element.</span>
(setcar (aref x 1) 69)
x ⇒ [quux (69 2)]
y ⇒ [foo (69 2)]
</pre>
</div> </dd>
</dl> <dl> <dt id="reverse">Function: <strong>reverse</strong> <em>sequence</em>
</dt> <dd>
    <p>This function creates a new sequence whose elements are the elements of <var>sequence</var>, but in reverse order. The original argument <var>sequence</var> is <em>not</em> altered. Note that char-tables cannot be reversed. </p> <div class="example"> <pre class="example">(setq x '(1 2 3 4))
     ⇒ (1 2 3 4)
</pre>
<pre class="example">(reverse x)
     ⇒ (4 3 2 1)
x
     ⇒ (1 2 3 4)
</pre>
<pre class="example">(setq x [1 2 3 4])
     ⇒ [1 2 3 4]
</pre>
<pre class="example">(reverse x)
     ⇒ [4 3 2 1]
x
     ⇒ [1 2 3 4]
</pre>
<pre class="example">(setq x "xyzzy")
     ⇒ "xyzzy"
</pre>
<pre class="example">(reverse x)
     ⇒ "yzzyx"
x
     ⇒ "xyzzy"
</pre>
</div> </dd>
</dl> <dl> <dt id="nreverse">Function: <strong>nreverse</strong> <em>sequence</em>
</dt> <dd>
   <p>This function reverses the order of the elements of <var>sequence</var>. Unlike <code>reverse</code> the original <var>sequence</var> may be modified. </p> <p>For example: </p> <div class="example"> <pre class="example">(setq x (list 'a 'b 'c))
     ⇒ (a b c)
</pre>
<pre class="example">x
     ⇒ (a b c)
(nreverse x)
     ⇒ (c b a)
</pre>
<pre class="example">;; <span class="roman">The cons cell that was first is now last.</span>
x
     ⇒ (a)
</pre>
</div> <p>To avoid confusion, we usually store the result of <code>nreverse</code> back in the same variable which held the original list: </p> <div class="example"> <pre class="example">(setq x (nreverse x))
</pre>
</div> <p>Here is the <code>nreverse</code> of our favorite example, <code>(a b c)</code>, presented graphically: </p> <div class="example"> <pre class="example"><span class="roman">Original list head:</span>                       <span class="roman">Reversed list:</span>
 -------------        -------------        ------------
| car  | cdr  |      | car  | cdr  |      | car | cdr  |
|   a  |  nil |&lt;--   |   b  |   o  |&lt;--   |   c |   o  |
|      |      |   |  |      |   |  |   |  |     |   |  |
 -------------    |   --------- | -    |   -------- | -
                  |             |      |            |
                   -------------        ------------
</pre>
</div> <p>For the vector, it is even simpler because you don’t need setq: </p> <div class="example"> <pre class="example">(setq x (copy-sequence [1 2 3 4]))
     ⇒ [1 2 3 4]
(nreverse x)
     ⇒ [4 3 2 1]
x
     ⇒ [4 3 2 1]
</pre>
</div> <p>Note that unlike <code>reverse</code>, this function doesn’t work with strings. Although you can alter string data by using <code>aset</code>, it is strongly encouraged to treat strings as immutable even when they are mutable. See <a href="mutability">Mutability</a>. </p> </dd>
</dl> <dl> <dt id="sort">Function: <strong>sort</strong> <em>sequence predicate</em>
</dt> <dd>
   <p>This function sorts <var>sequence</var> stably. Note that this function doesn’t work for all sequences; it may be used only for lists and vectors. If <var>sequence</var> is a list, it is modified destructively. This functions returns the sorted <var>sequence</var> and compares elements using <var>predicate</var>. A stable sort is one in which elements with equal sort keys maintain their relative order before and after the sort. Stability is important when successive sorts are used to order elements according to different criteria. </p> <p>The argument <var>predicate</var> must be a function that accepts two arguments. It is called with two elements of <var>sequence</var>. To get an increasing order sort, the <var>predicate</var> should return non-<code>nil</code> if the first element is “less” than the second, or <code>nil</code> if not. </p> <p>The comparison function <var>predicate</var> must give reliable results for any given pair of arguments, at least within a single call to <code>sort</code>. It must be <em>antisymmetric</em>; that is, if <var>a</var> is less than <var>b</var>, <var>b</var> must not be less than <var>a</var>. It must be <em>transitive</em>—that is, if <var>a</var> is less than <var>b</var>, and <var>b</var> is less than <var>c</var>, then <var>a</var> must be less than <var>c</var>. If you use a comparison function which does not meet these requirements, the result of <code>sort</code> is unpredictable. </p> <p>The destructive aspect of <code>sort</code> for lists is that it rearranges the cons cells forming <var>sequence</var> by changing <small>CDR</small>s. A nondestructive sort function would create new cons cells to store the elements in their sorted order. If you wish to make a sorted copy without destroying the original, copy it first with <code>copy-sequence</code> and then sort. </p> <p>Sorting does not change the <small>CAR</small>s of the cons cells in <var>sequence</var>; the cons cell that originally contained the element <code>a</code> in <var>sequence</var> still has <code>a</code> in its <small>CAR</small> after sorting, but it now appears in a different position in the list due to the change of <small>CDR</small>s. For example: </p> <div class="example"> <pre class="example">(setq nums (list 1 3 2 6 5 4 0))
     ⇒ (1 3 2 6 5 4 0)
</pre>
<pre class="example">(sort nums #'&lt;)
     ⇒ (0 1 2 3 4 5 6)
</pre>
<pre class="example">nums
     ⇒ (1 2 3 4 5 6)
</pre>
</div> <p><strong>Warning</strong>: Note that the list in <code>nums</code> no longer contains 0; this is the same cons cell that it was before, but it is no longer the first one in the list. Don’t assume a variable that formerly held the argument now holds the entire sorted list! Instead, save the result of <code>sort</code> and use that. Most often we store the result back into the variable that held the original list: </p> <div class="example"> <pre class="example">(setq nums (sort nums #'&lt;))
</pre>
</div> <p>For the better understanding of what stable sort is, consider the following vector example. After sorting, all items whose <code>car</code> is 8 are grouped at the beginning of <code>vector</code>, but their relative order is preserved. All items whose <code>car</code> is 9 are grouped at the end of <code>vector</code>, but their relative order is also preserved: </p> <div class="example"> <pre class="example">(setq
  vector
  (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz")
          '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff")))
     ⇒ [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz")
         (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")]
</pre>
<pre class="example">(sort vector (lambda (x y) (&lt; (car x) (car y))))
     ⇒ [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee")
         (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")]
</pre>
</div> <p>See <a href="sorting">Sorting</a>, for more functions that perform sorting. See <code>documentation</code> in <a href="accessing-documentation">Accessing Documentation</a>, for a useful example of <code>sort</code>. </p>
</dd>
</dl>    <p>The <samp>seq.el</samp> library provides the following additional sequence manipulation macros and functions, prefixed with <code>seq-</code>. To use them, you must first load the <samp>seq</samp> library. </p> <p>All functions defined in this library are free of side-effects; i.e., they do not modify any sequence (list, vector, or string) that you pass as an argument. Unless otherwise stated, the result is a sequence of the same type as the input. For those functions that take a predicate, this should be a function of one argument. </p> <p>The <samp>seq.el</samp> library can be extended to work with additional types of sequential data-structures. For that purpose, all functions are defined using <code>cl-defgeneric</code>. See <a href="generic-functions">Generic Functions</a>, for more details about using <code>cl-defgeneric</code> for adding extensions. </p> <dl> <dt id="seq-elt">Function: <strong>seq-elt</strong> <em>sequence index</em>
</dt> <dd>
<p>This function returns the element of <var>sequence</var> at the specified <var>index</var>, which is an integer whose valid value range is zero to one less than the length of <var>sequence</var>. For out-of-range values on built-in sequence types, <code>seq-elt</code> behaves like <code>elt</code>. For the details, see <a href="#Definition-of-elt">Definition of elt</a>. </p> <div class="example"> <pre class="example">(seq-elt [1 2 3 4] 2)
⇒ 3
</pre>
</div> <p><code>seq-elt</code> returns places settable using <code>setf</code> (see <a href="setting-generalized-variables">Setting Generalized Variables</a>). </p> <div class="example"> <pre class="example">(setq vec [1 2 3 4])
(setf (seq-elt vec 2) 5)
vec
⇒ [1 2 5 4]
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-length">Function: <strong>seq-length</strong> <em>sequence</em>
</dt> <dd><p>This function returns the number of elements in <var>sequence</var>. For built-in sequence types, <code>seq-length</code> behaves like <code>length</code>. See <a href="#Definition-of-length">Definition of length</a>. </p></dd>
</dl> <dl> <dt id="seqp">Function: <strong>seqp</strong> <em>object</em>
</dt> <dd>
<p>This function returns non-<code>nil</code> if <var>object</var> is a sequence (a list or array), or any additional type of sequence defined via <samp>seq.el</samp> generic functions. This is an extensible variant of <code>sequencep</code>. </p> <div class="example"> <pre class="example">(seqp [1 2])
⇒ t
</pre>
<pre class="example">(seqp 2)
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-drop">Function: <strong>seq-drop</strong> <em>sequence n</em>
</dt> <dd>
<p>This function returns all but the first <var>n</var> (an integer) elements of <var>sequence</var>. If <var>n</var> is negative or zero, the result is <var>sequence</var>. </p> <div class="example"> <pre class="example">(seq-drop [1 2 3 4 5 6] 3)
⇒ [4 5 6]
</pre>
<pre class="example">(seq-drop "hello world" -4)
⇒ "hello world"
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-take">Function: <strong>seq-take</strong> <em>sequence n</em>
</dt> <dd>
<p>This function returns the first <var>n</var> (an integer) elements of <var>sequence</var>. If <var>n</var> is negative or zero, the result is <code>nil</code>. </p> <div class="example"> <pre class="example">(seq-take '(1 2 3 4) 3)
⇒ (1 2 3)
</pre>
<pre class="example">(seq-take [1 2 3 4] 0)
⇒ []
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-take-while">Function: <strong>seq-take-while</strong> <em>predicate sequence</em>
</dt> <dd>
<p>This function returns the members of <var>sequence</var> in order, stopping before the first one for which <var>predicate</var> returns <code>nil</code>. </p> <div class="example"> <pre class="example">(seq-take-while (lambda (elt) (&gt; elt 0)) '(1 2 3 -1 -2))
⇒ (1 2 3)
</pre>
<pre class="example">(seq-take-while (lambda (elt) (&gt; elt 0)) [-1 4 6])
⇒ []
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-drop-while">Function: <strong>seq-drop-while</strong> <em>predicate sequence</em>
</dt> <dd>
<p>This function returns the members of <var>sequence</var> in order, starting from the first one for which <var>predicate</var> returns <code>nil</code>. </p> <div class="example"> <pre class="example">(seq-drop-while (lambda (elt) (&gt; elt 0)) '(1 2 3 -1 -2))
⇒ (-1 -2)
</pre>
<pre class="example">(seq-drop-while (lambda (elt) (&lt; elt 0)) [1 4 6])
⇒ [1 4 6]
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-do">Function: <strong>seq-do</strong> <em>function sequence</em>
</dt> <dd><p>This function applies <var>function</var> to each element of <var>sequence</var> in turn (presumably for side effects), and returns <var>sequence</var>. </p></dd>
</dl> <dl> <dt id="seq-map">Function: <strong>seq-map</strong> <em>function sequence</em>
</dt> <dd>
<p>This function returns the result of applying <var>function</var> to each element of <var>sequence</var>. The returned value is a list. </p> <div class="example"> <pre class="example">(seq-map #'1+ '(2 4 6))
⇒ (3 5 7)
</pre>
<pre class="example">(seq-map #'symbol-name [foo bar])
⇒ ("foo" "bar")
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-map-indexed">Function: <strong>seq-map-indexed</strong> <em>function sequence</em>
</dt> <dd>
<p>This function returns the result of applying <var>function</var> to each element of <var>sequence</var> and its index within <var>seq</var>. The returned value is a list. </p> <div class="example"> <pre class="example">(seq-map-indexed (lambda (elt idx)
                   (list idx elt))
                 '(a b c))
⇒ ((0 a) (1 b) (2 c))
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-mapn">Function: <strong>seq-mapn</strong> <em>function &amp;rest sequences</em>
</dt> <dd>
<p>This function returns the result of applying <var>function</var> to each element of <var>sequences</var>. The arity (see <a href="what-is-a-function">subr-arity</a>) of <var>function</var> must match the number of sequences. Mapping stops at the end of the shortest sequence, and the returned value is a list. </p> <div class="example"> <pre class="example">(seq-mapn #'+ '(2 4 6) '(20 40 60))
⇒ (22 44 66)
</pre>
<pre class="example">(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"])
⇒ ("moskitobee" "bitesting")
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-filter">Function: <strong>seq-filter</strong> <em>predicate sequence</em>
</dt> <dd>
 <p>This function returns a list of all the elements in <var>sequence</var> for which <var>predicate</var> returns non-<code>nil</code>. </p> <div class="example"> <pre class="example">(seq-filter (lambda (elt) (&gt; elt 0)) [1 -1 3 -3 5])
⇒ (1 3 5)
</pre>
<pre class="example">(seq-filter (lambda (elt) (&gt; elt 0)) '(-1 -3 -5))
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-remove">Function: <strong>seq-remove</strong> <em>predicate sequence</em>
</dt> <dd>
 <p>This function returns a list of all the elements in <var>sequence</var> for which <var>predicate</var> returns <code>nil</code>. </p> <div class="example"> <pre class="example">(seq-remove (lambda (elt) (&gt; elt 0)) [1 -1 3 -3 5])
⇒ (-1 -3)
</pre>
<pre class="example">(seq-remove (lambda (elt) (&lt; elt 0)) '(-1 -3 -5))
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-reduce">Function: <strong>seq-reduce</strong> <em>function sequence initial-value</em>
</dt> <dd>
 <p>This function returns the result of calling <var>function</var> with <var>initial-value</var> and the first element of <var>sequence</var>, then calling <var>function</var> with that result and the second element of <var>sequence</var>, then with that result and the third element of <var>sequence</var>, etc. <var>function</var> should be a function of two arguments. </p> <p><var>function</var> is called with two arguments. <var>intial-value</var> (and then the accumulated value) is used as the first argument, and the elements in <var>sequence</var> are used for the second argument. </p> <p>If <var>sequence</var> is empty, this returns <var>initial-value</var> without calling <var>function</var>. </p> <div class="example"> <pre class="example">(seq-reduce #'+ [1 2 3 4] 0)
⇒ 10
</pre>
<pre class="example">(seq-reduce #'+ '(1 2 3 4) 5)
⇒ 15
</pre>
<pre class="example">(seq-reduce #'+ '() 3)
⇒ 3
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-some">Function: <strong>seq-some</strong> <em>predicate sequence</em>
</dt> <dd>
<p>This function returns the first non-<code>nil</code> value returned by applying <var>predicate</var> to each element of <var>sequence</var> in turn. </p> <div class="example"> <pre class="example">(seq-some #'numberp ["abc" 1 nil])
⇒ t
</pre>
<pre class="example">(seq-some #'numberp ["abc" "def"])
⇒ nil
</pre>
<pre class="example">(seq-some #'null ["abc" 1 nil])
⇒ t
</pre>
<pre class="example">(seq-some #'1+ [2 4 6])
⇒ 3
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-find">Function: <strong>seq-find</strong> <em>predicate sequence &amp;optional default</em>
</dt> <dd>
<p>This function returns the first element in <var>sequence</var> for which <var>predicate</var> returns non-<code>nil</code>. If no element matches <var>predicate</var>, the function returns <var>default</var>. </p> <p>Note that this function has an ambiguity if the found element is identical to <var>default</var>, as in that case it cannot be known whether an element was found or not. </p> <div class="example"> <pre class="example">(seq-find #'numberp ["abc" 1 nil])
⇒ 1
</pre>
<pre class="example">(seq-find #'numberp ["abc" "def"])
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-every-p">Function: <strong>seq-every-p</strong> <em>predicate sequence</em>
</dt> <dd>
<p>This function returns non-<code>nil</code> if applying <var>predicate</var> to every element of <var>sequence</var> returns non-<code>nil</code>. </p> <div class="example"> <pre class="example">(seq-every-p #'numberp [2 4 6])
⇒ t
</pre>
<pre class="example">(seq-every-p #'numberp [2 4 "6"])
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-empty-p">Function: <strong>seq-empty-p</strong> <em>sequence</em>
</dt> <dd>
<p>This function returns non-<code>nil</code> if <var>sequence</var> is empty. </p> <div class="example"> <pre class="example">(seq-empty-p "not empty")
⇒ nil
</pre>
<pre class="example">(seq-empty-p "")
⇒ t
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-count">Function: <strong>seq-count</strong> <em>predicate sequence</em>
</dt> <dd>
<p>This function returns the number of elements in <var>sequence</var> for which <var>predicate</var> returns non-<code>nil</code>. </p> <div class="example"> <pre class="example">(seq-count (lambda (elt) (&gt; elt 0)) [-1 2 0 3 -2])
⇒ 2
</pre>
</div> </dd>
</dl>  <dl> <dt id="seq-sort">Function: <strong>seq-sort</strong> <em>function sequence</em>
</dt> <dd><p>This function returns a copy of <var>sequence</var> that is sorted according to <var>function</var>, a function of two arguments that returns non-<code>nil</code> if the first argument should sort before the second. </p></dd>
</dl> <dl> <dt id="seq-sort-by">Function: <strong>seq-sort-by</strong> <em>function predicate sequence</em>
</dt> <dd>
<p>This function is similar to <code>seq-sort</code>, but the elements of <var>sequence</var> are transformed by applying <var>function</var> on them before being sorted. <var>function</var> is a function of one argument. </p> <div class="example"> <pre class="example">(seq-sort-by #'seq-length #'&gt; ["a" "ab" "abc"])
⇒ ["abc" "ab" "a"]
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-contains-p">Function: <strong>seq-contains-p</strong> <em>sequence elt &amp;optional function</em>
</dt> <dd>
<p>This function returns non-<code>nil</code> if at least one element in <var>sequence</var> is equal to <var>elt</var>. If the optional argument <var>function</var> is non-<code>nil</code>, it is a function of two arguments to use instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-contains-p '(symbol1 symbol2) 'symbol1)
⇒ t
</pre>
<pre class="example">(seq-contains-p '(symbol1 symbol2) 'symbol3)
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-set-equal-p">Function: <strong>seq-set-equal-p</strong> <em>sequence1 sequence2 &amp;optional testfn</em>
</dt> <dd>
<p>This function checks whether <var>sequence1</var> and <var>sequence2</var> contain the same elements, regardless of the order. If the optional argument <var>testfn</var> is non-<code>nil</code>, it is a function of two arguments to use instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-set-equal-p '(a b c) '(c b a))
⇒ t
</pre>
<pre class="example">(seq-set-equal-p '(a b c) '(c b))
⇒ nil
</pre>
<pre class="example">(seq-set-equal-p '("a" "b" "c") '("c" "b" "a"))
⇒ t
</pre>
<pre class="example">(seq-set-equal-p '("a" "b" "c") '("c" "b" "a") #'eq)
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-position">Function: <strong>seq-position</strong> <em>sequence elt &amp;optional function</em>
</dt> <dd>
<p>This function returns the index of the first element in <var>sequence</var> that is equal to <var>elt</var>. If the optional argument <var>function</var> is non-<code>nil</code>, it is a function of two arguments to use instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-position '(a b c) 'b)
⇒ 1
</pre>
<pre class="example">(seq-position '(a b c) 'd)
⇒ nil
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-uniq">Function: <strong>seq-uniq</strong> <em>sequence &amp;optional function</em>
</dt> <dd>
<p>This function returns a list of the elements of <var>sequence</var> with duplicates removed. If the optional argument <var>function</var> is non-<code>nil</code>, it is a function of two arguments to use instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-uniq '(1 2 2 1 3))
⇒ (1 2 3)
</pre>
<pre class="example">(seq-uniq '(1 2 2.0 1.0) #'=)
⇒ (1 2)
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-subseq">Function: <strong>seq-subseq</strong> <em>sequence start &amp;optional end</em>
</dt> <dd>
 <p>This function returns a subset of <var>sequence</var> from <var>start</var> to <var>end</var>, both integers (<var>end</var> defaults to the last element). If <var>start</var> or <var>end</var> is negative, it counts from the end of <var>sequence</var>. </p> <div class="example"> <pre class="example">(seq-subseq '(1 2 3 4 5) 1)
⇒ (2 3 4 5)
</pre>
<pre class="example">(seq-subseq '[1 2 3 4 5] 1 3)
⇒ [2 3]
</pre>
<pre class="example">(seq-subseq '[1 2 3 4 5] -3 -1)
⇒ [3 4]
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-concatenate">Function: <strong>seq-concatenate</strong> <em>type &amp;rest sequences</em>
</dt> <dd>
<p>This function returns a sequence of type <var>type</var> made of the concatenation of <var>sequences</var>. <var>type</var> may be: <code>vector</code>, <code>list</code> or <code>string</code>. </p> <div class="example"> <pre class="example">(seq-concatenate 'list '(1 2) '(3 4) [5 6])
⇒ (1 2 3 4 5 6)
</pre>
<pre class="example">(seq-concatenate 'string "Hello " "world")
⇒ "Hello world"
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-mapcat">Function: <strong>seq-mapcat</strong> <em>function sequence &amp;optional type</em>
</dt> <dd>
<p>This function returns the result of applying <code>seq-concatenate</code> to the result of applying <var>function</var> to each element of <var>sequence</var>. The result is a sequence of type <var>type</var>, or a list if <var>type</var> is <code>nil</code>. </p> <div class="example"> <pre class="example">(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4)))
⇒ (1 2 3 4 5 6)
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-partition">Function: <strong>seq-partition</strong> <em>sequence n</em>
</dt> <dd>
<p>This function returns a list of the elements of <var>sequence</var> grouped into sub-sequences of length <var>n</var>. The last sequence may contain less elements than <var>n</var>. <var>n</var> must be an integer. If <var>n</var> is a negative integer or 0, the return value is <code>nil</code>. </p> <div class="example"> <pre class="example">(seq-partition '(0 1 2 3 4 5 6 7) 3)
⇒ ((0 1 2) (3 4 5) (6 7))
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-union">Function: <strong>seq-union</strong> <em>sequence1 sequence2 &amp;optional function</em>
</dt> <dd>
  <p>This function returns a list of the elements that appear either in <var>sequence1</var> or <var>sequence2</var>. The elements of the returned list are all unique, in the sense that no two elements there will compare equal. If the optional argument <var>function</var> is non-<code>nil</code>, it should be a function of two arguments to use to compare elements, instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-union [1 2 3] [3 5])
⇒ (1 2 3 5)
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-intersection">Function: <strong>seq-intersection</strong> <em>sequence1 sequence2 &amp;optional function</em>
</dt> <dd>
  <p>This function returns a list of the elements that appear both in <var>sequence1</var> and <var>sequence2</var>. If the optional argument <var>function</var> is non-<code>nil</code>, it is a function of two arguments to use to compare elements instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-intersection [2 3 4 5] [1 3 5 6 7])
⇒ (3 5)
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-difference">Function: <strong>seq-difference</strong> <em>sequence1 sequence2 &amp;optional function</em>
</dt> <dd>
<p>This function returns a list of the elements that appear in <var>sequence1</var> but not in <var>sequence2</var>. If the optional argument <var>function</var> is non-<code>nil</code>, it is a function of two arguments to use to compare elements instead of the default <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-difference '(2 3 4 5) [1 3 5 6 7])
⇒ (2 4)
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-group-by">Function: <strong>seq-group-by</strong> <em>function sequence</em>
</dt> <dd>
<p>This function separates the elements of <var>sequence</var> into an alist whose keys are the result of applying <var>function</var> to each element of <var>sequence</var>. Keys are compared using <code>equal</code>. </p> <div class="example"> <pre class="example">(seq-group-by #'integerp '(1 2.1 3 2 3.2))
⇒ ((t 1 3 2) (nil 2.1 3.2))
</pre>
<pre class="example">(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4)))
⇒ ((b (b 2)) (a (a 1) (a 3)) (c (c 4)))
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-into">Function: <strong>seq-into</strong> <em>sequence type</em>
</dt> <dd>
    <p>This function converts the sequence <var>sequence</var> into a sequence of type <var>type</var>. <var>type</var> can be one of the following symbols: <code>vector</code>, <code>string</code> or <code>list</code>. </p> <div class="example"> <pre class="example">(seq-into [1 2 3] 'list)
⇒ (1 2 3)
</pre>
<pre class="example">(seq-into nil 'vector)
⇒ []
</pre>
<pre class="example">(seq-into "hello" 'vector)
⇒ [104 101 108 108 111]
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-min">Function: <strong>seq-min</strong> <em>sequence</em>
</dt> <dd>
  <p>This function returns the smallest element of <var>sequence</var>. The elements of <var>sequence</var> must be numbers or markers (see <a href="markers">Markers</a>). </p> <div class="example"> <pre class="example">(seq-min [3 1 2])
⇒ 1
</pre>
<pre class="example">(seq-min "Hello")
⇒ 72
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-max">Function: <strong>seq-max</strong> <em>sequence</em>
</dt> <dd>
  <p>This function returns the largest element of <var>sequence</var>. The elements of <var>sequence</var> must be numbers or markers. </p> <div class="example"> <pre class="example">(seq-max [1 3 2])
⇒ 3
</pre>
<pre class="example">(seq-max "Hello")
⇒ 111
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-doseq">Macro: <strong>seq-doseq</strong> <em>(var sequence) body…</em>
</dt> <dd>
  <p>This macro is like <code>dolist</code> (see <a href="iteration">dolist</a>), except that <var>sequence</var> can be a list, vector or string. This is primarily useful for side-effects. </p>
</dd>
</dl> <dl> <dt id="seq-let">Macro: <strong>seq-let</strong> <em>var-sequence val-sequence body…</em>
</dt> <dd>
 <p>This macro binds the variables defined in <var>var-sequence</var> to the values that are the corresponding elements of <var>val-sequence</var>. This is known as <em>destructuring binding</em>. The elements of <var>var-sequence</var> can themselves include sequences, allowing for nested destructuring. </p> <p>The <var>var-sequence</var> sequence can also include the <code>&amp;rest</code> marker followed by a variable name to be bound to the rest of <var>val-sequence</var>. </p> <div class="example"> <pre class="example">(seq-let [first second] [1 2 3 4]
  (list first second))
⇒ (1 2)
</pre>
<pre class="example">(seq-let (_ a _ b) '(1 2 3 4)
  (list a b))
⇒ (2 4)
</pre>
<pre class="example">(seq-let [a [b [c]]] [1 [2 [3]]]
  (list a b c))
⇒ (1 2 3)
</pre>
<pre class="example">(seq-let [a b &amp;rest others] [1 2 3 4]
  others)
</pre>
<pre class="example">⇒ [3 4]
</pre>
</div> <p>The <code>pcase</code> patterns provide an alternative facility for destructuring binding, see <a href="destructuring-with-pcase-patterns">Destructuring with pcase Patterns</a>. </p>
</dd>
</dl> <dl> <dt id="seq-setq">Macro: <strong>seq-setq</strong> <em>var-sequence val-sequence</em>
</dt> <dd>
 <p>This macro works similarly to <code>seq-let</code>, except that values are assigned to variables as if by <code>setq</code> instead of as in a <code>let</code> binding. </p> <div class="example"> <pre class="example">(let ((a nil)
      (b nil))
  (seq-setq (_ a _ b) '(1 2 3 4))
  (list a b))
⇒ (2 4)
</pre>
</div> </dd>
</dl> <dl> <dt id="seq-random-elt">Function: <strong>seq-random-elt</strong> <em>sequence</em>
</dt> <dd>
<p>This function returns an element of <var>sequence</var> taken at random. </p> <div class="example"> <pre class="example">(seq-random-elt [1 2 3 4])
⇒ 3
(seq-random-elt [1 2 3 4])
⇒ 2
(seq-random-elt [1 2 3 4])
⇒ 4
(seq-random-elt [1 2 3 4])
⇒ 2
(seq-random-elt [1 2 3 4])
⇒ 1
</pre>
</div> <p>If <var>sequence</var> is empty, this function signals an error. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/Sequence-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Sequence-Functions.html</a>
  </p>
</div>