Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the Select Reference Manual, version 1.0.
• Introduction | What Select is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Conclusion | Time to go | |
• Indexes | Concepts, functions, variables and data types |
Select is a library for taking slices from array-like objects. The most frequently used form is:
(select object selection1 selection2 ...)
where each selection specifies a set of subscripts along the corresponding axis. The selection specifications are found below.
A non-negative integer selects the corresponding index, while a negative integer selects an index counting backwards from the last index. For example:
(select #(0 1 2 3) 1) ; => 1 (select #(0 1 2 3) -2) ; => 2
These are called singleton slices. Each singleton slice drops the dimension: vectors become atoms, matrices become vectors, etc..
(range start end)
selects subscripts i where start <= i <
end. When end is nil, the last index is included (cf. subseq). Each
boundary is resolved according to the other rules if applicable, so
you can use negative integers:
(select #(0 1 2 3) (range 1 3)) ; => #(1 2) (select #(0 1 2 3) (range 1 -1)) ; => #(1 2)
t
selects all subscripts:
(select #2A((0 1 2) (3 4 5)) t 1) ; => #(1 4)
Sequences can be used to make specific selections from the object. For example:
(select #(0 1 2 3 4 5 6 7 8 9) (vector (range 1 3) 6 (range -2 -1))) ; => #(1 2 3 6 8 9) (select #(0 1 2) '(2 2 1 0 0)) ; => #(2 2 1 0 0)
Bit vectors can be used to select elements of arrays and sequences as well:
(select #(0 1 2 3 4) #*00110) ; => #(2 3)
Section 1.1 describes the core functionality. The semantics can be extended, as you will see in the next section. The extensions in this section are provided by the library and prove useful in practice. Their implementation provides good examples of extending the library.
including
is convenient if you want the selection to include
the end of the range:
(select #(0 1 2 3) (including 1 2)) ; => #(1 2), cf. (select ... (range 1 3))
nodrop
is useful if you do not want to drop dimensions:
(select #(0 1 2 3) (nodrop 2)) ; => #(2), cf. (select ... (range 2 3))
head
and tail
do the obvious:
(select #(0 1 2 3) (head 2)) ; => #(0 1) (select #(0 1 2 3) (tail 2)) ; => #(2 3)
All of these are trivial to implement. If there is something you are
missing, you can easily extend select
. Pull request are welcome.
ref
is a version of select
that always returns a single
element, so it can only be used with singleton slices.
Arguments of select
, except the first one, are meant to be
resolved using canonical-representation
, in the
select-dev
package. If you want to extend select
, you
should define methods for canonical-representation
. See the
source code for the best examples. Below is a simple example that
extends the semantics with ordinal numbers.
(defmacro define-ordinal-selection (number) (check-type number (integer 0)) `(defmethod select-dev:canonical-representation ((axis integer) (slice (eql ',(intern (format nil "~:@(~:r~)" number))))) (assert (< ,number axis)) (select-dev:canonical-singleton ,number))) (define-ordinal-selection 1) (define-ordinal-selection 2) (define-ordinal-selection 3) (select #(0 1 2 3 4 5) (range 'first 'third)) ; => #(1 2)
Note the following:
canonical-representation
needs to be
constructed using canonical-singleton
, canonical-range
,
or canonical-sequence
. You should not use the internal
representation directly as it is subject to change.
axis
is an integer: this is the default. An
object may define a more complex mapping (such as, for example, named
rows & columns), but unless a method specialized to that is found,
canonical-representation
will just query its dimension (with
axis-dimension
) and try to find a method that works on
integers.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The select system |
Steve Nunez
(:git "git://github.com/symbolics/select")
MS-PL
DSL for array slices.
Select is a facility for selecting portions of sequences or arrays. It
provides:
An API for taking slices (elements selected by the Cartesian product of vectors of subscripts for each axis) of array-like objects. The most important function is ‘select‘. Unless you want to define additional methods for ‘select‘, this is pretty much all you need from this library. See the documentation at https://symbolics.github.io/select/ for a tutorial.
An extensible DSL for selecting a subset of valid subscripts. This is useful if, for example, you want to resolve column names in a data frame in your implementation of slice.
A set of utility functions for traversing slices in array-like objects.
1.0
select.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The select.asd file | ||
• The select/package.lisp file | ||
• The select/select-dev.lisp file | ||
• The select/select.lisp file |
Next: The select/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
select (system)
Next: The select/select-dev․lisp file, Previous: The select․asd file, Up: Lisp files [Contents][Index]
select (system)
Next: The select/select․lisp file, Previous: The select/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
select (system)
Previous: The select/select-dev․lisp file, Up: Lisp files [Contents][Index]
select-dev.lisp (file)
select (system)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The slct package |
SELECT is a facility for selecting portions of sequences or arrays.
package.lisp (file)
select
Next: Conclusion, Previous: Packages, Up: Top [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported functions | ||
• Exported generic functions | ||
• Exported structures |
Next: Exported generic functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
First COUNT indexes.
select.lisp (file)
Range, including both ends.
select.lisp (file)
Select a single index, but do not drop a dimension.
select.lisp (file)
Range, including START, excluding END.
select.lisp (file)
Test if SYMBOL has special semantics for SELECTION.
select-dev.lisp (file)
Test if a canonical REPRESENTATION is a singleton.
select-dev.lisp (file)
Last COUNT indexes.
select.lisp (file)
Next: Exported structures, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Map sequence into a simple-bit-vector, using 1 when PREDICATE yields true, 0 otherwise.
select.lisp (file)
Return the element of OBJECT specified by SUBSCRIPTS.
select.lisp (file)
(setf ref) (generic function)
Stores VALUE into the place specified by SUBSCRIPTS.
select.lisp (file)
ref (generic function)
Return the slices of OBJECT specified by SELECTIONS.
select.lisp (file)
(setf select) (generic function)
Select from LST the subscripts or range specified in SELECTIONS. SELECTIONS must be a VECTOR, LIST or RANGE.
Return the SELECTIONS in the given ARRAY.
Stores VALUES into the locations given by SELECTIONS.
select.lisp (file)
select (generic function)
Return an index of the positions in SEQUENCE which satisfy PREDICATE.
select.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Range, including both ends.
select.lisp (file)
structure-object (structure)
canonical-representation (method)
including-start (function)
(setf including-start) (function)
including-end (function)
(setf including-end) (function)
Select a single index, but don’t drop a dimension.
select.lisp (file)
structure-object (structure)
canonical-representation (method)
nodrop-index (function)
(setf nodrop-index) (function)
Range, including start, excluding end.
select.lisp (file)
structure-object (structure)
canonical-representation (method)
range-start (function)
(setf range-start) (function)
range-end (function)
(setf range-end) (function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal macros | ||
• Internal functions | ||
• Internal generic functions | ||
• Internal structures |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Loops over all possible subscripts in REPRESENTAITONS, making them available in SUBSCRIPTS during the execution of BODY. The iterator is constructed using the function SETUP (see for example ROW-MAJOR-SETUP). When INDEX is given, a variable with that name is provided, containing an index that counts iterations.
select-dev.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
Test if all canonical representations are singletons.
select-dev.lisp (file)
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
select-dev.lisp (file)
select-dev.lisp (file)
select-dev.lisp (file)
select-dev.lisp (file)
Return the canonical representations of SELECTIONS given the corresponding AXES, checking for matching length.
select-dev.lisp (file)
Canonical representation of array indexes from canonical-sequence SEQUENCE.
May share structure. Vectors of the upgraded type of (SIMPLE-ARRAY ARRAY-INDEX (*)) are preferred for efficiency, otherwise they are coerced.
select-dev.lisp (file)
select-dev.lisp (file)
select-dev.lisp (file)
Canonical representation of a singleton index (a nonnegative integer, which is a valid array index).
select-dev.lisp (file)
Return SUBSCRIPTS (a list) and ITERATOR (a closure, no arguments) that increments the contents of SUBSCRIPTS in column-major order. TERMINATOR is called when all subscripts have been visited.
select-dev.lisp (file)
select-dev.lisp (file)
select-dev.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select-dev.lisp (file)
select-dev.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
select.lisp (file)
Return the dimension of a canonical-representation, or NIL for singleton selections (they are dropped).
select-dev.lisp (file)
Return a list for the dimensions of canonical representations, dropping singletons.
select-dev.lisp (file)
Initial value for iteration.
select-dev.lisp (file)
Return a closure that sets the car of CONS to the next value each time it is called, resetting and calling CARRY when it reaches the end of its range.
select-dev.lisp (file)
Return SUBSCRIPTS (a list) and ITERATOR (a closure, no arguments) that increments the contents of SUBSCRIPTS in row-major order. TERMINATOR is called when all subscripts have been visited.
select-dev.lisp (file)
Next: Internal structures, Previous: Internal functions, Up: Internal definitions [Contents][Index]
Return the dimension of axis. Needs to be defined for non-integer axes.
select-dev.lisp (file)
Canonical representation of SELECTION, given information in AXIS. The default methods use dimensions as AXIS.
Each selection needs to be resolved into a canonical representation, which is either a singleton, a range, or a sequence of subscripts. They should only be constructed with the corresponding CANONICAL-SINGLETION, CANONICAL-RANGE and CANONICAL-SEQUENCE functions.
@c(CANONICAL-REPRESENTATION) needs to ensure that the represented subscripts are valid for the axis.
Unless a specialized method is found, the dimension of the axis is queried with AXIS-DIMENSION and resolution is attempted using the latter. Methods that resolve symbols should test them with SELECT-RESERVED-SYMBOL? and use CALL-NEXT-METHOD.
select-dev.lisp (file)
The canonical representation for NODROP.
select.lisp (file)
The canonical representation for RANGE.
select.lisp (file)
The canonical representation for INCLUDING.
select.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
select-dev.lisp (file)
structure-object (structure)
canonical-representation (method)
alexandria.1.0.0:array-index
canonical-range-start (function)
(setf canonical-range-start) (function)
alexandria.1.0.0:array-index
canonical-range-end (function)
(setf canonical-range-end) (function)
Canonical representation of a sequence of array indexes.
select-dev.lisp (file)
structure-object (structure)
canonical-representation (method)
(simple-array alexandria.1.0.0:array-index (*))
canonical-sequence-vector (function)
(setf canonical-sequence-vector) (function)
Next: Indexes, Previous: Definitions, Up: Top [Contents][Index]
Select was originally called slice and written by Tamas K. Papp. Since it was abandoned in 2017, I have taken it over to be part of a rebooted Common Lisp statistics library. Changes in this version include:
Previous: Conclusion, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L S |
---|
Jump to: | F L S |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
A C F G H I M N R S T W |
---|
Jump to: | (
A C F G H I M N R S T W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | E I S V |
---|
Jump to: | E I S V |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C I N P R S |
---|
Jump to: | C I N P R S |
---|