ELisp: Sequence Functions

The Sequence library seq.el

seq.el is a library of functions on Sequence Type .

seq.el is new in Emacs 25 (Released 2016-09)

seq.el is loaded when emacs starts.

You may want to explicitly declare (require 'seq)

Some of the functions provide new functionalities, some gives a unified interface to old functions.

is Sequence, Length, Empty

• seqp → return true if it's a sequence.
• seq-length → same as length
• seq-empty-p → use this to check is empty. because if a list is large, it takes longer time to find length.

Sort, Reverse

• ELisp: Sequence, Sort, Reverse

Get Nth

• seq-elt → same as elt

Min, Max

• seq-min → get the smallest number.
• seq-max → get the biggest number.

Insert / Delete / Modify Items (At Arbitrary Positions)

• seq-mapcat → apply a function that return a list (can be empty list), but insert its elements into the sequence.

💡 TIP: this is the most general function, that you can have a function go thru each item, delete it by returning nil, or add more items by returning a list, or change it by returning a list of one item. This is more general than map because map cannot delete items, and more general than filter because filter cannot add item nor transform the items you want.

;; if an item is even, insert a extra copy
(seq-mapcat
 (lambda (x)
   (if (eq 0 (mod x 2))
       (list x x)
     (list x)
     ))
 '(1 2 3 4))
;; (1 2 2 3 4 4)

Take / Remove Elements in Sequence

Take / Remove First N

• seq-take → get first n.
• seq-take-while → get first n , with a condition to stop.

• seq-drop → remove first n.
• seq-drop-while → remove first n, with a condition to stop.

Take a Slice

• seq-subseq → get a sublist specified by begin and end index.

Filter by Function

• seq-filter → get elements by a function check.
• seq-remove → remove elements by a function check.

Delete Duplicates

• seq-uniq → get unique elements.

Delete by Equality Test

remove

(remove x sequence)

• Remove all x in sequence.
• The original sequence is unchanged.
• Returns a new sequence.
• Comparison is done with equal. [see ELisp: Equality Test]

(setq xx '(3 4 5))
(remove 4 xx) ;; (3 5)
xx ; (3 4 5)

delete

(delete x sequence)

• Remove all x in sequence.
• The original sequence is destroyed if it's a list.
• Returns a new sequence.
• Comparison is done with equal. [see ELisp: Equality Test]

(setq xx '(3 4 5))

;; always set result to the same var. because original is usually destroyed
(setq xx (delete 4 xx)) ; (3 5)

;; on vector
(setq xx [3 4 5])
(setq xx (delete 4 xx)) ; [3 5]

Loop, Iteration

Foreach (side-effect use)

• seq-do → loop a function over the sequence. (Same as mapc).
• seq-doseq → loop a variable over the sequence. (similar to dolist.)

Return Changed Sequence

• seq-map → apply a function to sequence, return result sequence. (basically same as mapcar.)
• seq-mapn → apply a function of n params over n sequences.

• seq-reduce → take 2 elements at a time, in the end return one single value.

Return True/False

• seq-every-p → apply a function to all, return true if every result is true.
• seq-some → apply a function to all, return true if at least one result is true.

💡 TIP: these are useful as functional version of loop with break. As soon as a condition found, the loop stops.

;; demo of seq-some
(seq-some (lambda (x) (eq 5 x)) [4 5 6])
;; t

Check Existance, Count

• seq-contains → check existance by equality test.
• seq-find → check existance by function.
• seq-position → check existance and return its position. By equality test or function.
• seq-count → check existance by function and return count.

Restructure

• seq-partition
• seq-group-by

• seq-into → flatten

Copy, Join, Intersection, Difference

• copy-sequence
• seq-concatenate

• seq-intersection
• seq-difference

Sequence Binding

• seq-let
• seq-setq

[see ELisp: Destructure Binding]