1
@node Sequences and Arrays and Hash Tables, Characters, Numbers, Top
2
@chapter Sequences and Arrays and Hash Tables
4
@defun VECTOR (&rest objects)
7
Constructs a Simple-Vector from the given objects.
12
@defun SUBSEQ (sequence start &optional (end (length sequence)))
15
Returns a copy of a subsequence of SEQUENCE between START (inclusive) and
21
@defun COPY-SEQ (sequence)
24
Returns a copy of SEQUENCE.
29
@defun POSITION (item sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (key #'identity))
32
Returns the index of the first element in SEQUENCE that satisfies TEST with
33
ITEM; NIL if no such element exists.
38
@defun ARRAY-RANK (array)
41
Returns the number of dimensions of ARRAY.
46
@defun SBIT (simple-bit-array &rest subscripts)
49
Returns the bit from SIMPLE-BIT-ARRAY at SUBSCRIPTS.
54
@defun STRING-CAPITALIZE (string &key (start 0) (end (length string)))
57
Returns a copy of STRING with the first character of each word converted to
58
upper-case, and remaining characters in the word converted to lower case.
63
@defun NSUBSTITUTE-IF-NOT (new test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
66
Returns a sequence of the same kind as SEQUENCE with the same elements
68
except that all elements not satisfying TEST are replaced with NEWITEM.
69
SEQUENCE may be destroyed.
74
@defun FIND-IF (test sequence &key (from-end nil) (start 0) (end (length sequence)) (key #'identity))
77
Returns the index of the first element in SEQUENCE that satisfies TEST; NIL if
78
no such element exists.
83
@defun BIT-EQV (bit-array1 bit-array2 &optional (result-bit-array nil))
86
Performs a bit-wise logical EQV on the elements of BIT-ARRAY1 and BIT-ARRAY2.
87
Puts the results into a new bit array if RESULT-BIT-ARRAY is NIL, into
88
BIT-ARRAY1 if RESULT-BIT-ARRAY is T, or into RESULT-BIT-ARRAY otherwise.
93
@defun STRING< (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
96
If STRING1 is lexicographically less than STRING2, then returns the longest
97
common prefix of the strings. Otherwise, returns NIL.
102
@defun REVERSE (sequence)
105
Returns a new sequence containing the same elements as SEQUENCE but in
111
@defun NSTRING-UPCASE (string &key (start 0) (end (length string)))
114
Returns STRING with all lower case characters converted to uppercase.
119
@defun STRING>= (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
122
If STRING1 is lexicographically greater than or equal to STRING2, then returns
123
the longest common prefix of the strings. Otherwise, returns NIL.
128
@defun ARRAY-ROW-MAJOR-INDEX (array &rest subscripts)
131
Returns the index into the data vector of ARRAY for the element of ARRAY
132
specified by SUBSCRIPTS.
138
@defun ARRAY-DIMENSION (array axis-number)
141
Returns the length of AXIS-NUMBER of ARRAY.
146
@defun FIND (item sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (key #'identity))
149
Returns the first element in SEQUENCE satisfying TEST with ITEM; NIL if no
155
@defun STRING-NOT-EQUAL (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
158
Similar to STRING=, but ignores cases.
163
@defun STRING-RIGHT-TRIM (char-bag string)
166
Returns a copy of STRING with the characters in CHAR-BAG removed from the
172
@defun DELETE-IF-NOT (test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
175
Returns a sequence formed by destructively removing the elements not
176
satisfying TEST from SEQUENCE.
181
@defun REMOVE-IF-NOT (test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
184
Returns a copy of SEQUENCE with elements not satisfying TEST removed.
189
@defun STRING= (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
192
Returns T if the two strings are character-wise CHAR=; NIL otherwise.
197
@defun NSUBSTITUTE-IF (new test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
200
Returns a sequence of the same kind as SEQUENCE with the same elements
201
except that all elements satisfying TEST are replaced with NEWITEM. SEQUENCE
207
@defun SOME (predicate sequence &rest more-sequences)
210
Returns T if at least one of the elements in SEQUENCEs satisfies PREDICATE;
216
@defun MAKE-STRING (size &key (initial-element #\Space))
219
Creates and returns a new string of SIZE length whose elements are all
225
@defun NSUBSTITUTE (newitem olditem sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
228
Returns a sequence of the same kind as SEQUENCE with the same elements
229
except that OLDITEMs are replaced with NEWITEM. SEQUENCE may be destroyed.
234
@defun STRING-EQUAL (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
237
Given two strings (string1 and string2), and optional integers start1,
238
start2, end1 and end2, compares characters in string1 to characters in
239
string2 (using char-equal).
244
@defun STRING-NOT-GREATERP (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
247
Similar to STRING<=, but ignores cases.
252
@defun STRING> (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
255
If STRING1 is lexicographically greater than STRING2, then returns the
256
longest common prefix of the strings. Otherwise, returns NIL.
264
Returns T if X is a string; NIL otherwise.
269
@defun DELETE-IF (test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
272
Returns a sequence formed by removing the elements satisfying TEST
273
destructively from SEQUENCE.
278
@defun SIMPLE-STRING-P (x)
281
Returns T if X is a simple string; NIL otherwise.
286
@defun REMOVE-IF (test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
289
Returns a copy of SEQUENCE with elements satisfying TEST removed.
294
@defun HASH-TABLE-COUNT (hash-table)
297
Returns the number of entries in the given Hash-Table.
302
@defun ARRAY-DIMENSIONS (array)
305
Returns a list whose elements are the dimensions of ARRAY
310
@defun SUBSTITUTE-IF-NOT (new test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
313
Returns a sequence of the same kind as SEQUENCE with the same elements
314
except that all elements not satisfying TEST are replaced with NEWITEM.
319
@defun ADJUSTABLE-ARRAY-P (array)
322
Returns T if ARRAY is adjustable; NIL otherwise.
327
@defun SVREF (simple-vector index)
330
Returns the INDEX-th element of SIMPLE-VECTOR.
335
@defun VECTOR-PUSH-EXTEND (new-element vector &optional (extension (length vector)))
338
Similar to VECTOR-PUSH except that, if the fill pointer gets too large,
339
extends VECTOR rather then simply returns NIL.
344
@defun DELETE (item sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
347
Returns a sequence formed by removing the specified ITEM destructively from
353
@defun REMOVE (item sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
356
Returns a copy of SEQUENCE with ITEM removed.
364
Coerces X into a string. If X is a string, then returns X itself. If X is a
365
symbol, then returns X's print name. If X is a character, then returns a one
366
element string containing that character. Signals an error if X cannot be
367
coerced into a string.
372
@defun STRING-UPCASE (string &key (start 0) (end (length string)))
375
Returns a copy of STRING with all lower case characters converted to
381
@defun GETHASH (key hash-table &optional (default nil))
384
Finds the entry in HASH-TABLE whose key is KEY and returns the associated
385
value and T, as multiple values. Returns DEFAULT and NIL if there is no
391
@defun MAKE-HASH-TABLE (&key (test 'eql) (size 1024) (rehash-size 1.5) (rehash-threshold 0.7))
394
Creates and returns a hash table.
399
@defun STRING/= (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
402
Returns NIL if STRING1 and STRING2 are character-wise CHAR=. Otherwise,
403
returns the index to the longest common prefix of the strings.
408
@defun STRING-GREATERP (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
411
Similar to STRING>, but ignores cases.
416
@defun ELT (sequence index)
419
Returns the INDEX-th element of SEQUENCE.
424
@defun MAKE-ARRAY (dimensions &key (element-type t) initial-element (initial-contents nil) (adjustable nil) (fill-pointer nil) (displaced-to nil) (displaced-index-offset 0) static)
427
Creates an array of the specified DIMENSIONS. The default for INITIAL-
428
ELEMENT depends on ELEMENT-TYPE.
429
MAKE-ARRAY will always try to find the `best' array to
430
accommodate the element-type specified. For example on a SUN element-type
432
(integer 0 10) --> unsigned-char
433
(integer -3 10) --> signed-char
434
si::best-array-element-type is the function doing this. It
435
is also used by the compiler, for coercing array element types.
436
If you are going to declare an array you should use the same
437
element type as was used in making it. eg
438
(setq my-array (make-array 4 :element-type '(integer 0 10)))
439
(the (array (integer 0 10)) my-array)
440
When wanting to optimize references to an array you need to
441
declare the array eg: (the (array (integer -3 10)) my-array) if ar
442
were constructed using the (integer -3 10) element-type. You could of
443
course have used signed-char, but since the ranges may be
444
implementation dependent it is better to use -3 10 range. MAKE-ARRAY
445
needs to do some calculation with the element-type if you don't
446
provide a primitive data-type. One way of doing this in a machine
449
(defvar *my-elt-type* #.
450
(array-element-type (make-array 1 :element-type '(integer -3 10))))
452
Then calls to (make-array n :element-type *my-elt-type*) will not have to go
453
through a type inclusion computation. The keyword STATIC (GCL specific) if non
454
nil, will cause the array body to be non relocatable.
460
@defun NSTRING-DOWNCASE (string &key (start 0) (end (length string)))
462
Returns STRING with all upper case
463
characters converted to lowercase.
468
@defun ARRAY-IN-BOUNDS-P (array &rest subscripts)
470
Returns T if SUBSCRIPTS are valid subscripts for
471
ARRAY; NIL otherwise.
476
@defun SORT (sequence predicate &key (key #'identity))
478
Destructively sorts SEQUENCE.
479
PREDICATE should return non-NIL if its first argument is to precede
485
@defun HASH-TABLE-P (x)
488
Returns T if X is a hash table object; NIL
494
@defun COUNT-IF-NOT (test sequence &key (from-end nil) (start 0) (end (length sequence)) (key #'identity))
497
Returns the number of elements in SEQUENCE not satisfying TEST.
502
@defun FILL-POINTER (vector)
505
Returns the fill pointer of VECTOR.
514
Returns T if X is an array; NIL otherwise.
519
@defun REPLACE (sequence1 sequence2 &key (start1 0) (end1 (length sequence1)) (start2 0) (end2 (length sequence2)))
522
Destructively modifies SEQUENCE1 by copying successive elements into it from
528
@defun BIT-XOR (bit-array1 bit-array2 &optional (result-bit-array nil))
531
Performs a bit-wise logical XOR on the elements of BIT-ARRAY1 and BIT-ARRAY2.
532
Puts the results into a new bit array if RESULT-BIT-ARRAY is NIL, into
533
BIT-ARRAY1 if RESULT-BIT-ARRAY is T, or into RESULT-BIT-ARRAY otherwise.
538
@defun CLRHASH (hash-table)
541
Removes all entries of HASH-TABLE and returns the hash table itself.
546
@defun SUBSTITUTE-IF (newitem test sequence &key (from-end nil) (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
549
Returns a sequence of the same kind as SEQUENCE with the same elements
550
except that all elements satisfying TEST are replaced with NEWITEM.
555
@defun MISMATCH (sequence1 sequence2 &key (from-end nil) (test #'eql) test-not (start1 0) (start2 0) (end1 (length sequence1)) (end2 (length sequence2)) (key #'identity))
558
The specified subsequences of SEQUENCE1 and SEQUENCE2 are compared
559
element-wise. If they are of equal length and match in every element, the
560
result is NIL. Otherwise, the result is a non-negative integer, the index
561
within SEQUENCE1 of the leftmost position at which they fail to match; or, if
562
one is shorter than and a matching prefix of the other, the index within
563
SEQUENCE1 beyond the last position tested is returned.
568
@defvr {Constant} ARRAY-TOTAL-SIZE-LIMIT
570
The exclusive upper bound on the total number of elements of an array.
575
@defun VECTOR-POP (vector)
578
Attempts to decrease the fill-pointer of VECTOR by 1 and returns the element
579
pointed to by the new fill pointer. Signals an error if the old value of
580
the fill pointer is 0.
585
@defun SUBSTITUTE (newitem olditem sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (count most-positive-fixnum) (key #'identity))
588
Returns a sequence of the same kind as SEQUENCE with the same elements
589
except that OLDITEMs are replaced with NEWITEM.
594
@defun ARRAY-HAS-FILL-POINTER-P (array)
597
Returns T if ARRAY has a fill pointer; NIL otherwise.
602
@defun CONCATENATE (result-type &rest sequences)
605
Returns a new sequence of the specified RESULT-TYPE, consisting of all
606
elements in SEQUENCEs.
611
@defun VECTOR-PUSH (new-element vector)
614
Attempts to set the element of ARRAY designated by its fill pointer to
615
NEW-ELEMENT and increments the fill pointer by one. Returns NIL if the fill
616
pointer is too large. Otherwise, returns the new fill pointer value.
621
@defun STRING-TRIM (char-bag string)
624
Returns a copy of STRING with the characters in CHAR-BAG removed from both
630
@defun ARRAY-ELEMENT-TYPE (array)
633
Returns the type of the elements of ARRAY
638
@defun NOTANY (predicate sequence &rest more-sequences)
641
Returns T if none of the elements in SEQUENCEs satisfies PREDICATE; NIL
647
@defun BIT-NOT (bit-array &optional (result-bit-array nil))
650
Performs a bit-wise logical NOT in the elements of BIT-ARRAY.
651
Puts the results into a new bit array if RESULT-BIT-ARRAY is NIL, into
652
BIT-ARRAY if RESULT-BIT-ARRAY is T, or into RESULT-BIT-ARRAY otherwise.
657
@defun BIT-ORC1 (bit-array1 bit-array2 &optional (result-bit-array nil))
660
Performs a bit-wise logical ORC1 on the elements of BIT-ARRAY1 and BIT-ARRAY2.
661
Puts the results into a new bit array if RESULT-BIT-ARRAY is NIL, into
662
BIT-ARRAY1 if RESULT-BIT-ARRAY is T, or into RESULT-BIT-ARRAY otherwise.
667
@defun COUNT-IF (test sequence &key (from-end nil) (start 0) (end (length sequence)) (key #'identity))
670
Returns the number of elements in SEQUENCE satisfying TEST.
675
@defun MAP (result-type function sequence &rest more-sequences)
678
FUNCTION must take as many arguments as there are sequences provided. The
679
result is a sequence such that the i-th element is the result of applying
680
FUNCTION to the i-th elements of the SEQUENCEs.
685
@defvr {Constant} ARRAY-RANK-LIMIT
687
The exclusive upper bound on the rank of an array.
692
@defun COUNT (item sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (key #'identity))
695
Returns the number of elements in SEQUENCE satisfying TEST with ITEM.
700
@defun BIT-VECTOR-P (x)
703
Returns T if X is a bit vector; NIL otherwise.
708
@defun NSTRING-CAPITALIZE (string &key (start 0) (end (length string)))
711
Returns STRING with the first character of each word converted to upper-case,
712
and remaining characters in the word converted to lower case.
717
@defun ADJUST-ARRAY (array dimensions &key (element-type (array-element-type array)) initial-element (initial-contents nil) (fill-pointer nil) (displaced-to nil) (displaced-index-offset 0))
720
Adjusts the dimensions of ARRAY to the given DIMENSIONS. The default value
721
of INITIAL-ELEMENT depends on ELEMENT-TYPE.
726
@defun SEARCH (sequence1 sequence2 &key (from-end nil) (test #'eql) test-not (start1 0) (start2 0) (end1 (length sequence1)) (end2 (length sequence2)) (key #'identity))
729
A search is conducted for the first subsequence of SEQUENCE2 which
730
element-wise matches SEQUENCE1. If there is such a subsequence in SEQUENCE2,
731
the index of the its leftmost element is returned; otherwise, NIL is
737
@defun SIMPLE-BIT-VECTOR-P (x)
740
Returns T if X is a simple bit-vector; NIL otherwise.
745
@defun MAKE-SEQUENCE (type length &key initial-element)
748
Returns a sequence of the given TYPE and LENGTH, with elements initialized
749
to INITIAL-ELEMENT. The default value of INITIAL-ELEMENT depends on TYPE.
754
@defun BIT-ORC2 (bit-array1 bit-array2 &optional (result-bit-array nil))
757
Performs a bit-wise logical ORC2 on the elements of BIT-ARRAY1 and BIT-ARRAY2.
758
Puts the results into a new bit array if RESULT-BIT-ARRAY is NIL, into
759
BIT-ARRAY1 if RESULT-BIT-ARRAY is T, or into RESULT-BIT-ARRAY otherwise.
764
@defun NREVERSE (sequence)
767
Returns a sequence of the same elements as SEQUENCE but in reverse order.
768
SEQUENCE may be destroyed.
773
@defvr {Constant} ARRAY-DIMENSION-LIMIT
775
The exclusive upper bound of the array dimension.
780
@defun NOTEVERY (predicate sequence &rest more-sequences)
783
Returns T if at least one of the elements in SEQUENCEs does not satisfy
784
PREDICATE; NIL otherwise.
789
@defun POSITION-IF-NOT (test sequence &key (from-end nil) (start 0) (end (length sequence)) (key #'identity))
792
Returns the index of the first element in SEQUENCE that does not satisfy TEST;
793
NIL if no such element exists.
798
@defun STRING-DOWNCASE (string &key (start 0) (end (length string)))
801
Returns a copy of STRING with all upper case characters converted to
807
@defun BIT (bit-array &rest subscripts)
810
Returns the bit from BIT-ARRAY at SUBSCRIPTS.
815
@defun STRING-NOT-LESSP (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
818
Similar to STRING>=, but ignores cases.
823
@defun CHAR (string index)
826
Returns the INDEX-th character in STRING.
831
@defun AREF (array &rest subscripts)
834
Returns the element of ARRAY specified by SUBSCRIPTS.
839
@defun FILL (sequence item &key (start 0) (end (length sequence)))
842
Replaces the specified elements of SEQUENCE all with ITEM.
847
@defun STABLE-SORT (sequence predicate &key (key #'identity))
850
Destructively sorts SEQUENCE. PREDICATE should return non-NIL if its first
851
argument is to precede its second argument.
856
@defun BIT-IOR (bit-array1 bit-array2 &optional (result-bit-array nil))
859
Performs a bit-wise logical IOR on the elements of BIT-ARRAY1 and BIT-ARRAY2.
860
Puts the results into a new bit array if RESULT-BIT-ARRAY is NIL, into
861
BIT-ARRAY1 if RESULT-BIT-ARRAY is T, or into RESULT-BIT-ARRAY otherwise.
866
@defun REMHASH (key hash-table)
869
Removes any entry for KEY in HASH-TABLE. Returns T if such an entry
870
existed; NIL otherwise.
878
Returns T if X is a vector; NIL otherwise.
883
@defun STRING<= (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
886
If STRING1 is lexicographically less than or equal to STRING2, then returns
887
the longest common prefix of the two strings. Otherwise, returns NIL.
892
@defun SIMPLE-VECTOR-P (x)
895
Returns T if X is a simple vector; NIL otherwise.
900
@defun STRING-LEFT-TRIM (char-bag string)
903
Returns a copy of STRING with the characters in CHAR-BAG removed from the
909
@defun ARRAY-TOTAL-SIZE (array)
912
Returns the total number of elements of ARRAY.
917
@defun FIND-IF-NOT (test sequence &key (from-end nil) (start 0) (end (length sequence)) (key #'identity))
920
Returns the index of the first element in SEQUENCE that does not satisfy
921
TEST; NIL if no such element exists.
926
@defun DELETE-DUPLICATES (sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (key #'identity))
929
Returns a sequence formed by removing duplicated elements destructively from
935
@defun REMOVE-DUPLICATES (sequence &key (from-end nil) (test #'eql) test-not (start 0) (end (length sequence)) (key #'identity))
938
The elements of SEQUENCE are examined, and if any two match, one is discarded.
939
Returns the resulting sequence.
944
@defun POSITION-IF (test sequence &key (from-end nil) (start 0) (end (length sequence)) (key #'identity))
947
Returns the index of the first element in SEQUENCE that satisfies TEST; NIL
948
if no such element exists.
953
@defun MERGE (result-type sequence1 sequence2 predicate &key (key #'identity))
956
SEQUENCE1 and SEQUENCE2 are destructively merged into a sequence of type
957
RESULT-TYPE using PREDICATE to order the elements.
962
@defun EVERY (predicate sequence &rest more-sequences)
965
Returns T if every elements of SEQUENCEs satisfy PREDICATE; NIL otherwise.
970
@defun REDUCE (function sequence &key (from-end nil) (start 0) (end (length sequence)) initial-value)
973
Combines all the elements of SEQUENCE using a binary operation FUNCTION.
974
If INITIAL-VALUE is supplied, it is logically placed before the SEQUENCE.
979
@defun STRING-LESSP (string1 string2 &key (start1 0) (end1 (length string1)) (start2 0) (end2 (length string2)))
982
Similar to STRING<, but ignores cases.
added
removed
info/sequence.texi
