Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-slice Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 04:03:01 2022 GMT+0.
Next: Systems, Previous: The cl-slice Reference Manual, Up: The cl-slice Reference Manual [Contents][Index]
#+CAPTION: Project Status: Abandoned – Initial development has started, but there has not yet been a stable, usable release; the project has been abandoned and the author(s) do not intend on continuing development.
[[http://www.repostatus.org/badges/latest/abandoned.svg]]
This repository is *archived*. You may find an updated version of these
libraries at https://github.com/Lisp-Stat/select
* Array slices for Common Lisp
This library provides the following:
1. A user interface 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 =slice=. Unless you want to define a method for this (besides what is already implemented), this is pretty much all you need from this library. See the next section for a tutorial.
2. 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=.
3. A set of utility functions for traversing slices in array-like objects.
* User interface
The most frequently used form is
#+BEGIN_SRC lisp
(slice object slice1 slice2 ...)
#+END_SRC
Each /slice/ selects a subset of subscripts along the corresponding axis. The library supports the following slice specifications:
- a nonnegative integer selects the corresponding index, while a negative integer selects an index counting backwards from the last index:
#+BEGIN_SRC lisp
(slice #(0 1 2 3) 1) ; => 1
(slice #(0 1 2 3) -2) ; => 2
#+END_SRC
These are called /singleton slices/. Each singleton slice /drops/ the dimension: vectors become atoms, matrices become vectors, etc.
- =(cons start end)= selects integers $i: \text{start} \leq i < \text{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:
#+BEGIN_SRC lisp
(slice #(0 1 2 3) (cons 1 3)) ; => #(1 2)
(slice #(0 1 2 3) (cons 1 -1)) ; => #(1 2)
#+END_SRC
However, =(cons start end)= is /invalid unless/ $\text{start} < \text{end}$, so you can't use
#+BEGIN_SRC lisp
(slice #(0 1 2 3) (cons 2 2)) ; ERROR
#+END_SRC
- =t= selects all subscripts:
#+BEGIN_SRC lisp
(slice #2A((0 1 2)
(3 4 5))
t 1) ; => #(1 4)
#+END_SRC
- vectors concatenate selections (except for bit vectors):
#+BEGIN_SRC lisp
(slice #(0 1 2 3 4 5 6 7 8 9)
(vector (cons 1 3) 6 (cons -2 -1)))
; => #(1 2 3 6 8 9)
(slice #(0 1 2) #(2 2 1 0 0)) ; => #(2 2 1 0 0)
#+END_SRC
- bit vectors can be used as a mask:
#+BEGIN_SRC lisp
(slice #(0 1 2 3 4) #*00110) ; => #(2 3)
#+END_SRC
This is pretty much the core functionality --- the semantics can be extended, see the next section. The following extensions are provided by the library.
- =including= is convenient if you want the slice to include the end of the range:
#+BEGIN_SRC lisp
(slice #(0 1 2 3) (including 1 2)) ; => #(1 2), cf (slice ... (cons 1 3))
#+END_SRC
- =nodrop= is useful if you don't want to drop dimensions:
#+BEGIN_SRC lisp
(slice #(0 1 2 3) (nodrop 2)) ; => #(2), cf (slice ... (cons 2 3))
#+END_SRC
- =head= and =tail= do the obvious:
#+BEGIN_SRC lisp
(slice #(0 1 2 3) (head 2)) ; => #(0 1)
(slice #(0 1 2 3) (tail 2)) ; => #(2 3)
#+END_SRC
All of these are trivial to implement --- if there is something you are missing, you can easily extend =slice=. You may also want to submit a patch!
=ref= is a version of slice that always returns a single element, so it can only be used with singleton slices.
* Slice semantics
Arguments of =slice= (apart from the first one) are meant to be resolved using =canonical-representation=, in the =cl-slice-dev= package. If you want to extend =slice=, you should define methods for =canonical-representation=. See the documentation for details, here I provide a simple example that extends the semantics with ordinal numbers.
#+BEGIN_SRC lisp
(defmacro define-ordinal-slice (number)
(check-type number (integer 0))
`(defmethod cl-slice-dev:canonical-representation
((axis integer) (slice (eql ',(intern (format nil "~:@(~:r~)" number)))))
(assert (< ,number axis))
(cl-slice-dev:canonical-singleton ,number)))
(define-ordinal-slice 1)
(define-ordinal-slice 2)
(define-ordinal-slice 3)
(slice #(0 1 2 3 4 5) (cons 'first 'third)) ; => #(1 2)
#+END_SRC
Note the following:
1. The value returned by =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.
2. You can assume that =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.
3. You need to make sure that the subscript is valid, hence the assertion.
* Traversing slices
** TODO write this
* Reporting bugs
Please report bugs using the [[https://github.com/tpapp/cl-slice/issues][issue tracker]].
Next: Files, Previous: Introduction, Up: The cl-slice Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
DSL for array slices in Common Lisp.
Tamas K Papp <tkpapp@gmail.com>
MIT
0.1
Next: Packages, Previous: Systems, Up: The cl-slice Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-slice/cl-slice-dev.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-slice (system).
Next: cl-slice/cl-slice.lisp, Previous: cl-slice/cl-slice.asd, Up: Lisp [Contents][Index]
cl-slice (system).
Previous: cl-slice/cl-slice-dev.lisp, Up: Lisp [Contents][Index]
cl-slice-dev.lisp (file).
cl-slice (system).
Next: Definitions, Previous: Files, Up: The cl-slice Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: cl-slice-dev, Previous: Packages, Up: Packages [Contents][Index]
Next: Indexes, Previous: Packages, Up: The cl-slice Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
Anaphoric macro version of SLICE that binds the first argument to IT.
A macro for traversing representations. Loops over all possible subscripts in REPRESENTAITONS, making them available in SUBSCRIPS 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.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Test if all canonical representations are singletons.
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
Return the canonical representations of SLICES given the corresponding AXES, checking for matching length.
Canonical representation of array indexes from sequence. May share structure. Vectors of the upgraded type of (SIMPLE-ARRAY ARRAY-INDEX (*)) are preferred for efficiency, otherwise they are coerced.
Canonical representation of a singleton index (a nonnegative integer, which is a valid array index).
First COUNT indexes.
Range, including both ends.
Slice a single index, but don’t drop a dimension.
Return a list for the dimensions of canonical representations, dropping singletons.
Return SUBSCRIPTS (a list) and ITERATOR (a closure, no arguments) that increments the contents of SUBSCRIPTS. TERMINATOR is called when all subscripts have been visited.
Test if a canonical REPRESENTATION is a singleton.
Test if SYMBOL has special semantics for SLICE.
Last COUNT indexes.
Next: Structures, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Return the dimension of axis. Needs to be defined for non-integer axes.
Canonical representation of SLICE, given information in AXIS. The default methods just use dimensions as AXIS.
Each slice 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.
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. It recommended that methods that resolve symbols test them with SLICE-RESERVED-SYMBOL? and use CALL-NEXT-METHOD.
Map sequence into a simple-bit-vector, using 1 when PREDICATE yields true, 0 otherwise.
Return the element of OBJECT specified by SUBSCRIPTS.
Return the slice of OBJECT specified by SLICES.
Return an index of the positions in SEQUENCE which satisfy PREDICATE.
Previous: Generic functions, Up: Public Interface [Contents][Index]
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
Canonical representation of a sequence of array indexes.
structure-object.
common-lisp.
(simple-array alexandria:array-index (*))
Range, including both ends.
Select a single index, but don’t drop a dimension.
structure-object.
Previous: Public Interface, Up: Definitions [Contents][Index]
end.
end.
Return the dimension of a canonical-representation, or NIL for singleton slices (they are dropped).
Initial value for iteration.
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.
Previous: Definitions, Up: The cl-slice Reference Manual [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 types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | E I S V |
|---|
| Jump to: | E I S V |
|---|
| Jump to: | C F I N P S |
|---|
| Jump to: | C F I N P S |
|---|