-
Notifications
You must be signed in to change notification settings - Fork 136
/
dash.texi
5039 lines (4289 loc) · 125 KB
/
dash.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename dash.info
@set DASHVER 2.19.1
@settitle Dash: A modern list library for GNU Emacs.
@documentencoding UTF-8
@documentlanguage en
@c %**end of header
@copying
This manual is for Dash version @value{DASHVER}.
Copyright @copyright{} 2012--2024 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License,'' and no
Front-Cover Texts or Back-Cover Texts. A copy of the license is
included in the section entitled ``GNU Free Documentation License''.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Dash: (dash.info). A modern list library for GNU Emacs.
@end direntry
@titlepage
@title Dash Manual
@subtitle For Dash Version @value{DASHVER}.
@author Magnar Sveen
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top Dash
@insertcopying
@end ifnottex
@menu
* Installation:: Installing and configuring Dash.
* Functions:: Dash API reference.
* Development:: Contributing to Dash development.
Appendices
* FDL:: The license for this documentation.
* GPL:: Conditions for copying and changing Dash.
* Index:: Index including functions and macros.
@detailmenu
--- The Detailed Node Listing ---
Installation
* Using in a package:: Listing Dash as a package dependency.
* Fontification of special variables:: Font Lock of anaphoric macro variables.
* Info symbol lookup:: Looking up Dash symbols in this manual.
Functions
* Maps::
* Sublist selection::
* List to list::
* Reductions::
* Unfolding::
* Predicates::
* Partitioning::
* Indexing::
* Set operations::
* Other list operations::
* Tree operations::
* Threading macros::
* Binding::
* Side effects::
* Destructive operations::
* Function combinators::
Development
* Contribute:: How to contribute.
* Contributors:: List of contributors.
@end detailmenu
@end menu
@node Installation
@chapter Installation
Dash is available on @url{https://elpa.gnu.org/, GNU ELPA},
@url{https://elpa.gnu.org/devel/, GNU-devel ELPA}, and
@url{https://melpa.org/, MELPA}, and can be installed with the
standard command @code{package-install} (@pxref{Package
Installation,,, emacs, The GNU Emacs Manual}).
@table @kbd
@item M-x package-install @key{RET} dash @key{RET}
Install the Dash library.
@end table
Alternatively, you can just dump @file{dash.el} in your
@code{load-path} somewhere (@pxref{Lisp Libraries,,, emacs, The GNU
Emacs Manual}).
@menu
* Using in a package:: Listing Dash as a package dependency.
* Fontification of special variables:: Font Lock of anaphoric macro variables.
* Info symbol lookup:: Looking up Dash symbols in this manual.
@end menu
@node Using in a package
@section Using in a package
If you use Dash in your own package, be sure to list it as a
dependency in the library's headers as follows (@pxref{Library
Headers,,, elisp, The Emacs Lisp Reference Manual}).
@lisp
;; Package-Requires: ((dash "@value{DASHVER}"))
@end lisp
@node Fontification of special variables
@section Fontification of special variables
@findex dash-fontify-mode
The autoloaded minor mode @code{dash-fontify-mode} is provided for
optional fontification of anaphoric Dash variables (@code{it},
@code{acc}, etc.@:) in Emacs Lisp buffers using search-based Font Lock
(@pxref{Font Lock,,, emacs, The GNU Emacs Manual}). In older Emacs
versions which do not dynamically detect macros, the minor mode also
fontifies calls to Dash macros.
@findex global-dash-fontify-mode
To automatically enable the minor mode in all Emacs Lisp buffers, just
call its autoloaded global counterpart
@code{global-dash-fontify-mode}, either interactively or from your
@code{user-init-file}:
@lisp
(global-dash-fontify-mode)
@end lisp
@node Info symbol lookup
@section Info symbol lookup
@findex dash-register-info-lookup
While editing Elisp files, you can use @kbd{C-h S}
(@code{info-lookup-symbol}) to look up Elisp symbols in the relevant
Info manuals (@pxref{Info Lookup,,, emacs, The GNU Emacs Manual}). To
enable the same for Dash symbols, use the command
@code{dash-register-info-lookup}. It can be called directly when
needed, or automatically from your @code{user-init-file}. For
example:
@lisp
(with-eval-after-load 'info-look
(dash-register-info-lookup))
@end lisp
@node Functions
@chapter Functions
This chapter contains reference documentation for the Dash
@acronym{API, Application Programming Interface}. The names of all
public functions defined in the library are prefixed with a dash
character (@samp{-}).
The library also provides anaphoric macro versions of functions where
that makes sense. The names of these macros are prefixed with two
dashes (@samp{--}) instead of one.
For instance, while the function @code{-map} applies a function to
each element of a list, its anaphoric counterpart @code{--map}
evaluates a form with the local variable @code{it} temporarily bound
to the current list element instead.
@lisp
@group
;; Normal version.
(-map (lambda (n) (* n n)) '(1 2 3 4))
@result{} (1 4 9 16)
@end group
@group
;; Anaphoric version.
(--map (* it it) '(1 2 3 4))
@result{} (1 4 9 16)
@end group
@end lisp
The normal version can, of course, also be written as in the following
example, which demonstrates the utility of both versions.
@lisp
@group
(defun my-square (n)
"Return N multiplied by itself."
(* n n))
(-map #'my-square '(1 2 3 4))
@result{} (1 4 9 16)
@end group
@end lisp
@menu
* Maps::
* Sublist selection::
* List to list::
* Reductions::
* Unfolding::
* Predicates::
* Partitioning::
* Indexing::
* Set operations::
* Other list operations::
* Tree operations::
* Threading macros::
* Binding::
* Side effects::
* Destructive operations::
* Function combinators::
@end menu
@node Maps
@section Maps
Functions in this category take a transforming function, which
is then applied sequentially to each or selected elements of the
input list. The results are collected in order and returned as a
new list.
@anchor{-map}
@defun -map (fn list)
Apply @var{fn} to each item in @var{list} and return the list of results.
This function's anaphoric counterpart is @code{--map}.
@example
@group
(-map (lambda (num) (* num num)) '(1 2 3 4))
@result{} (1 4 9 16)
@end group
@group
(-map #'1+ '(1 2 3 4))
@result{} (2 3 4 5)
@end group
@group
(--map (* it it) '(1 2 3 4))
@result{} (1 4 9 16)
@end group
@end example
@end defun
@anchor{-map-when}
@defun -map-when (pred rep list)
Use @var{pred} to conditionally apply @var{rep} to each item in @var{list}.
Return a copy of @var{list} where the items for which @var{pred} returns @code{nil}
are unchanged, and the rest are mapped through the @var{rep} function.
Alias: @code{-replace-where}
See also: @code{-update-at} (@pxref{-update-at})
@example
@group
(-map-when 'even? 'square '(1 2 3 4))
@result{} (1 4 3 16)
@end group
@group
(--map-when (> it 2) (* it it) '(1 2 3 4))
@result{} (1 2 9 16)
@end group
@group
(--map-when (= it 2) 17 '(1 2 3 4))
@result{} (1 17 3 4)
@end group
@end example
@end defun
@anchor{-map-first}
@defun -map-first (pred rep list)
Use @var{pred} to determine the first item in @var{list} to call @var{rep} on.
Return a copy of @var{list} where the first item for which @var{pred} returns
non-@code{nil} is replaced with the result of calling @var{rep} on that item.
See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-replace-first})
@example
@group
(-map-first 'even? 'square '(1 2 3 4))
@result{} (1 4 3 4)
@end group
@group
(--map-first (> it 2) (* it it) '(1 2 3 4))
@result{} (1 2 9 4)
@end group
@group
(--map-first (= it 2) 17 '(1 2 3 2))
@result{} (1 17 3 2)
@end group
@end example
@end defun
@anchor{-map-last}
@defun -map-last (pred rep list)
Use @var{pred} to determine the last item in @var{list} to call @var{rep} on.
Return a copy of @var{list} where the last item for which @var{pred} returns
non-@code{nil} is replaced with the result of calling @var{rep} on that item.
See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-last} (@pxref{-replace-last})
@example
@group
(-map-last 'even? 'square '(1 2 3 4))
@result{} (1 2 3 16)
@end group
@group
(--map-last (> it 2) (* it it) '(1 2 3 4))
@result{} (1 2 3 16)
@end group
@group
(--map-last (= it 2) 17 '(1 2 3 2))
@result{} (1 2 3 17)
@end group
@end example
@end defun
@anchor{-map-indexed}
@defun -map-indexed (fn list)
Apply @var{fn} to each index and item in @var{list} and return the list of results.
This is like @code{-map} (@pxref{-map}), but @var{fn} takes two arguments: the index of the
current element within @var{list}, and the element itself.
This function's anaphoric counterpart is @code{--map-indexed}.
For a side-effecting variant, see also @code{-each-indexed} (@pxref{-each-indexed}).
@example
@group
(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4))
@result{} (1 1 1 1)
@end group
@group
(--map-indexed (- it it-index) '(1 2 3 4))
@result{} (1 1 1 1)
@end group
@group
(-map-indexed #'* '(1 2 3 4))
@result{} (0 2 6 12)
@end group
@end example
@end defun
@anchor{-annotate}
@defun -annotate (fn list)
Pair each item in @var{list} with the result of passing it to @var{fn}.
Return an alist of (@var{result} . @var{item}), where each @var{item} is the
corresponding element of @var{list}, and @var{result} is the value obtained
by calling @var{fn} on @var{item}.
This function's anaphoric counterpart is @code{--annotate}.
@example
@group
(-annotate #'1+ '(1 2 3))
@result{} ((2 . 1) (3 . 2) (4 . 3))
@end group
@group
(-annotate #'length '((f o o) (bar baz)))
@result{} ((3 f o o) (2 bar baz))
@end group
@group
(--annotate (> it 1) '(0 1 2 3))
@result{} ((nil . 0) (nil . 1) (t . 2) (t . 3))
@end group
@end example
@end defun
@anchor{-splice}
@defun -splice (pred fun list)
Splice lists generated by @var{fun} in place of items satisfying @var{pred} in @var{list}.
Call @var{pred} on each element of @var{list}. Whenever the result of @var{pred}
is @code{nil}, leave that @code{it} as-is. Otherwise, call @var{fun} on the same
@code{it} that satisfied @var{pred}. The result should be a (possibly
empty) list of items to splice in place of @code{it} in @var{list}.
This can be useful as an alternative to the @code{,@@} construct in a
@code{`} structure, in case you need to splice several lists at
marked positions (for example with keywords).
This function's anaphoric counterpart is @code{--splice}.
See also: @code{-splice-list} (@pxref{-splice-list}), @code{-insert-at} (@pxref{-insert-at}).
@example
@group
(-splice #'numberp (lambda (n) (list n n)) '(a 1 b 2))
@result{} (a 1 1 b 2 2)
@end group
@group
(--splice t (list it it) '(1 2 3 4))
@result{} (1 1 2 2 3 3 4 4)
@end group
@group
(--splice (eq it :magic) '((magical) (code)) '((foo) :magic (bar)))
@result{} ((foo) (magical) (code) (bar))
@end group
@end example
@end defun
@anchor{-splice-list}
@defun -splice-list (pred new-list list)
Splice @var{new-list} in place of elements matching @var{pred} in @var{list}.
See also: @code{-splice} (@pxref{-splice}), @code{-insert-at} (@pxref{-insert-at})
@example
@group
(-splice-list 'keywordp '(a b c) '(1 :foo 2))
@result{} (1 a b c 2)
@end group
@group
(-splice-list 'keywordp nil '(1 :foo 2))
@result{} (1 2)
@end group
@group
(--splice-list (keywordp it) '(a b c) '(1 :foo 2))
@result{} (1 a b c 2)
@end group
@end example
@end defun
@anchor{-mapcat}
@defun -mapcat (fn list)
Return the concatenation of the result of mapping @var{fn} over @var{list}.
Thus function @var{fn} should return a list.
@example
@group
(-mapcat 'list '(1 2 3))
@result{} (1 2 3)
@end group
@group
(-mapcat (lambda (item) (list 0 item)) '(1 2 3))
@result{} (0 1 0 2 0 3)
@end group
@group
(--mapcat (list 0 it) '(1 2 3))
@result{} (0 1 0 2 0 3)
@end group
@end example
@end defun
@anchor{-copy}
@defun -copy (list)
Create a shallow copy of @var{list}.
@example
@group
(-copy '(1 2 3))
@result{} (1 2 3)
@end group
@group
(let ((a '(1 2 3))) (eq a (-copy a)))
@result{} nil
@end group
@end example
@end defun
@node Sublist selection
@section Sublist selection
Functions returning a sublist of the original list.
@anchor{-filter}
@defun -filter (pred list)
Return a new list of the items in @var{list} for which @var{pred} returns non-@code{nil}.
Alias: @code{-select}.
This function's anaphoric counterpart is @code{--filter}.
For similar operations, see also @code{-keep} (@pxref{-keep}) and @code{-remove} (@pxref{-remove}).
@example
@group
(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4))
@result{} (2 4)
@end group
@group
(-filter #'natnump '(-2 -1 0 1 2))
@result{} (0 1 2)
@end group
@group
(--filter (= 0 (% it 2)) '(1 2 3 4))
@result{} (2 4)
@end group
@end example
@end defun
@anchor{-remove}
@defun -remove (pred list)
Return a new list of the items in @var{list} for which @var{pred} returns @code{nil}.
Alias: @code{-reject}.
This function's anaphoric counterpart is @code{--remove}.
For similar operations, see also @code{-keep} (@pxref{-keep}) and @code{-filter} (@pxref{-filter}).
@example
@group
(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4))
@result{} (1 3)
@end group
@group
(-remove #'natnump '(-2 -1 0 1 2))
@result{} (-2 -1)
@end group
@group
(--remove (= 0 (% it 2)) '(1 2 3 4))
@result{} (1 3)
@end group
@end example
@end defun
@anchor{-remove-first}
@defun -remove-first (pred list)
Remove the first item from @var{list} for which @var{pred} returns non-@code{nil}.
This is a non-destructive operation, but only the front of @var{list}
leading up to the removed item is a copy; the rest is @var{list}'s
original tail. If no item is removed, then the result is a
complete copy.
Alias: @code{-reject-first}.
This function's anaphoric counterpart is @code{--remove-first}.
See also @code{-map-first} (@pxref{-map-first}), @code{-remove-item} (@pxref{-remove-item}), and @code{-remove-last} (@pxref{-remove-last}).
@example
@group
(-remove-first #'natnump '(-2 -1 0 1 2))
@result{} (-2 -1 1 2)
@end group
@group
(-remove-first #'stringp '(1 2 "first" "second"))
@result{} (1 2 "second")
@end group
@group
(--remove-first (> it 3) '(1 2 3 4 5 6))
@result{} (1 2 3 5 6)
@end group
@end example
@end defun
@anchor{-remove-last}
@defun -remove-last (pred list)
Remove the last item from @var{list} for which @var{pred} returns non-@code{nil}.
The result is a copy of @var{list} regardless of whether an element is
removed.
Alias: @code{-reject-last}.
This function's anaphoric counterpart is @code{--remove-last}.
See also @code{-map-last} (@pxref{-map-last}), @code{-remove-item} (@pxref{-remove-item}), and @code{-remove-first} (@pxref{-remove-first}).
@example
@group
(-remove-last #'natnump '(1 3 5 4 7 8 10 -11))
@result{} (1 3 5 4 7 8 -11)
@end group
@group
(-remove-last #'stringp '(1 2 "last" "second"))
@result{} (1 2 "last")
@end group
@group
(--remove-last (> it 3) '(1 2 3 4 5 6 7 8 9 10))
@result{} (1 2 3 4 5 6 7 8 9)
@end group
@end example
@end defun
@anchor{-remove-item}
@defun -remove-item (item list)
Return a copy of @var{list} with all occurrences of @var{item} removed.
The comparison is done with @code{equal}.
@example
@group
(-remove-item 3 '(1 2 3 2 3 4 5 3))
@result{} (1 2 2 4 5)
@end group
@group
(-remove-item 'foo '(foo bar baz foo))
@result{} (bar baz)
@end group
@group
(-remove-item "bob" '("alice" "bob" "eve" "bob"))
@result{} ("alice" "eve")
@end group
@end example
@end defun
@anchor{-non-nil}
@defun -non-nil (list)
Return a copy of @var{list} with all @code{nil} items removed.
@example
@group
(-non-nil '(nil 1 nil 2 nil nil 3 4 nil 5 nil))
@result{} (1 2 3 4 5)
@end group
@group
(-non-nil '((nil)))
@result{} ((nil))
@end group
@group
(-non-nil ())
@result{} ()
@end group
@end example
@end defun
@anchor{-slice}
@defun -slice (list from &optional to step)
Return copy of @var{list}, starting from index @var{from} to index @var{to}.
@var{from} or @var{to} may be negative. These values are then interpreted
modulo the length of the list.
If @var{step} is a number, only each STEPth item in the resulting
section is returned. Defaults to 1.
@example
@group
(-slice '(1 2 3 4 5) 1)
@result{} (2 3 4 5)
@end group
@group
(-slice '(1 2 3 4 5) 0 3)
@result{} (1 2 3)
@end group
@group
(-slice '(1 2 3 4 5 6 7 8 9) 1 -1 2)
@result{} (2 4 6 8)
@end group
@end example
@end defun
@anchor{-take}
@defun -take (n list)
Return a copy of the first @var{n} items in @var{list}.
Return a copy of @var{list} if it contains @var{n} items or fewer.
Return @code{nil} if @var{n} is zero or less.
See also: @code{-take-last} (@pxref{-take-last}).
@example
@group
(-take 3 '(1 2 3 4 5))
@result{} (1 2 3)
@end group
@group
(-take 17 '(1 2 3 4 5))
@result{} (1 2 3 4 5)
@end group
@group
(-take 0 '(1 2 3 4 5))
@result{} ()
@end group
@end example
@end defun
@anchor{-take-last}
@defun -take-last (n list)
Return a copy of the last @var{n} items of @var{list} in order.
Return a copy of @var{list} if it contains @var{n} items or fewer.
Return @code{nil} if @var{n} is zero or less.
See also: @code{-take} (@pxref{-take}).
@example
@group
(-take-last 3 '(1 2 3 4 5))
@result{} (3 4 5)
@end group
@group
(-take-last 17 '(1 2 3 4 5))
@result{} (1 2 3 4 5)
@end group
@group
(-take-last 1 '(1 2 3 4 5))
@result{} (5)
@end group
@end example
@end defun
@anchor{-drop}
@defun -drop (n list)
Return the tail (not a copy) of @var{list} without the first @var{n} items.
Return @code{nil} if @var{list} contains @var{n} items or fewer.
Return @var{list} if @var{n} is zero or less.
For another variant, see also @code{-drop-last} (@pxref{-drop-last}).
@example
@group
(-drop 3 '(1 2 3 4 5))
@result{} (4 5)
@end group
@group
(-drop 17 '(1 2 3 4 5))
@result{} ()
@end group
@group
(-drop 0 '(1 2 3 4 5))
@result{} (1 2 3 4 5)
@end group
@end example
@end defun
@anchor{-drop-last}
@defun -drop-last (n list)
Return a copy of @var{list} without its last @var{n} items.
Return a copy of @var{list} if @var{n} is zero or less.
Return @code{nil} if @var{list} contains @var{n} items or fewer.
See also: @code{-drop} (@pxref{-drop}).
@example
@group
(-drop-last 3 '(1 2 3 4 5))
@result{} (1 2)
@end group
@group
(-drop-last 17 '(1 2 3 4 5))
@result{} ()
@end group
@group
(-drop-last 0 '(1 2 3 4 5))
@result{} (1 2 3 4 5)
@end group
@end example
@end defun
@anchor{-take-while}
@defun -take-while (pred list)
Take successive items from @var{list} for which @var{pred} returns non-@code{nil}.
@var{pred} is a function of one argument. Return a new list of the
successive elements from the start of @var{list} for which @var{pred} returns
non-@code{nil}.
This function's anaphoric counterpart is @code{--take-while}.
For another variant, see also @code{-drop-while} (@pxref{-drop-while}).
@example
@group
(-take-while #'even? '(1 2 3 4))
@result{} ()
@end group
@group
(-take-while #'even? '(2 4 5 6))
@result{} (2 4)
@end group
@group
(--take-while (< it 4) '(1 2 3 4 3 2 1))
@result{} (1 2 3)
@end group
@end example
@end defun
@anchor{-drop-while}
@defun -drop-while (pred list)
Drop successive items from @var{list} for which @var{pred} returns non-@code{nil}.
@var{pred} is a function of one argument. Return the tail (not a copy)
of @var{list} starting from its first element for which @var{pred} returns
@code{nil}.
This function's anaphoric counterpart is @code{--drop-while}.
For another variant, see also @code{-take-while} (@pxref{-take-while}).
@example
@group
(-drop-while #'even? '(1 2 3 4))
@result{} (1 2 3 4)
@end group
@group
(-drop-while #'even? '(2 4 5 6))
@result{} (5 6)
@end group
@group
(--drop-while (< it 4) '(1 2 3 4 3 2 1))
@result{} (4 3 2 1)
@end group
@end example
@end defun
@anchor{-select-by-indices}
@defun -select-by-indices (indices list)
Return a list whose elements are elements from @var{list} selected
as `(nth i list)` for all i from @var{indices}.
@example
@group
(-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" "t" "o" "r"))
@result{} ("c" "o" "l" "o" "r")
@end group
@group
(-select-by-indices '(2 1 0) '("a" "b" "c"))
@result{} ("c" "b" "a")
@end group
@group
(-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l"))
@result{} ("f" "a" "r" "f" "a" "l" "l" "a")
@end group
@end example
@end defun
@anchor{-select-columns}
@defun -select-columns (columns table)
Select @var{columns} from @var{table}.
@var{table} is a list of lists where each element represents one row.
It is assumed each row has the same length.
Each row is transformed such that only the specified @var{columns} are
selected.
See also: @code{-select-column} (@pxref{-select-column}), @code{-select-by-indices} (@pxref{-select-by-indices})
@example
@group
(-select-columns '(0 2) '((1 2 3) (a b c) (:a :b :c)))
@result{} ((1 3) (a c) (:a :c))
@end group
@group
(-select-columns '(1) '((1 2 3) (a b c) (:a :b :c)))
@result{} ((2) (b) (:b))
@end group
@group
(-select-columns nil '((1 2 3) (a b c) (:a :b :c)))
@result{} (nil nil nil)
@end group
@end example
@end defun
@anchor{-select-column}
@defun -select-column (column table)
Select @var{column} from @var{table}.
@var{table} is a list of lists where each element represents one row.
It is assumed each row has the same length.
The single selected column is returned as a list.
See also: @code{-select-columns} (@pxref{-select-columns}), @code{-select-by-indices} (@pxref{-select-by-indices})
@example
@group
(-select-column 1 '((1 2 3) (a b c) (:a :b :c)))
@result{} (2 b :b)
@end group
@end example
@end defun
@node List to list
@section List to list
Functions returning a modified copy of the input list.
@anchor{-keep}
@defun -keep (fn list)
Return a new list of the non-@code{nil} results of applying @var{fn} to each item in @var{list}.
Like @code{-filter} (@pxref{-filter}), but returns the non-@code{nil} results of @var{fn} instead of
the corresponding elements of @var{list}.
Its anaphoric counterpart is @code{--keep}.
@example
@group
(-keep #'cdr '((1 2 3) (4 5) (6)))
@result{} ((2 3) (5))
@end group
@group
(-keep (lambda (n) (and (> n 3) (* 10 n))) '(1 2 3 4 5 6))
@result{} (40 50 60)
@end group
@group
(--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6))
@result{} (40 50 60)
@end group
@end example
@end defun
@anchor{-concat}
@defun -concat (&rest sequences)
Concatenate all the arguments and make the result a list.
The result is a list whose elements are the elements of all the arguments.
Each argument may be a list, vector or string.
All arguments except the last argument are copied. The last argument
is just used as the tail of the new list.
@example
@group
(-concat '(1))
@result{} (1)
@end group
@group
(-concat '(1) '(2))
@result{} (1 2)
@end group
@group
(-concat '(1) '(2 3) '(4))
@result{} (1 2 3 4)
@end group
@end example
@end defun
@anchor{-flatten}
@defun -flatten (l)
Take a nested list @var{l} and return its contents as a single, flat list.
Note that because @code{nil} represents a list of zero elements (an
empty list), any mention of @code{nil} in @var{l} will disappear after
flattening. If you need to preserve nils, consider @code{-flatten-n} (@pxref{-flatten-n})
or map them to some unique symbol and then map them back.
Conses of two atoms are considered "terminals", that is, they
aren't flattened further.
See also: @code{-flatten-n} (@pxref{-flatten-n})
@example
@group
(-flatten '((1)))
@result{} (1)
@end group
@group
(-flatten '((1 (2 3) (((4 (5)))))))
@result{} (1 2 3 4 5)
@end group
@group
(-flatten '(1 2 (3 . 4)))
@result{} (1 2 (3 . 4))
@end group
@end example
@end defun
@anchor{-flatten-n}
@defun -flatten-n (num list)
Flatten @var{num} levels of a nested @var{list}.
See also: @code{-flatten} (@pxref{-flatten})
@example
@group
(-flatten-n 1 '((1 2) ((3 4) ((5 6)))))
@result{} (1 2 (3 4) ((5 6)))
@end group
@group
(-flatten-n 2 '((1 2) ((3 4) ((5 6)))))
@result{} (1 2 3 4 (5 6))
@end group
@group
(-flatten-n 3 '((1 2) ((3 4) ((5 6)))))
@result{} (1 2 3 4 5 6)
@end group
@end example
@end defun
@anchor{-replace}
@defun -replace (old new list)
Replace all @var{old} items in @var{list} with @var{new}.
Elements are compared using @code{equal}.
See also: @code{-replace-at} (@pxref{-replace-at})
@example
@group
(-replace 1 "1" '(1 2 3 4 3 2 1))
@result{} ("1" 2 3 4 3 2 "1")
@end group
@group
(-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo"))
@result{} ("a" "nice" "bar" "sentence" "about" "bar")