Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-slice Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:20:24 2021 GMT+0.
| • Introduction | What cl-slice is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
#+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]]
* 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: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-slice system |
Tamas K Papp <tkpapp@gmail.com>
MIT
DSL for array slices in Common Lisp.
0.1
cl-slice.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-slice.asd file | ||
| • The cl-slice/cl-slice-dev.lisp file | ||
| • The cl-slice/cl-slice.lisp file |
Next: The cl-slice/cl-slice-dev․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-slice.asd
cl-slice (system)
Next: The cl-slice/cl-slice․lisp file, Previous: The cl-slice․asd file, Up: Lisp files [Contents][Index]
cl-slice (system)
cl-slice-dev.lisp
Previous: The cl-slice/cl-slice-dev․lisp file, Up: Lisp files [Contents][Index]
cl-slice-dev.lisp (file)
cl-slice (system)
cl-slice.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cl-slice-dev package | ||
| • The cl-slice package |
Next: The cl-slice package, Previous: Packages, Up: Packages [Contents][Index]
cl-slice-dev.lisp (file)
Previous: The cl-slice-dev package, Up: Packages [Contents][Index]
cl-slice.lisp (file)
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 macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported structures |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Anaphoric macro version of SLICE that binds the first argument to IT.
cl-slice.lisp (file)
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.
cl-slice-dev.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Test if all canonical representations are singletons.
cl-slice-dev.lisp (file)
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
cl-slice-dev.lisp (file)
Return the canonical representations of SLICES given the corresponding AXES, checking for matching length.
cl-slice-dev.lisp (file)
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.
cl-slice-dev.lisp (file)
Canonical representation of a singleton index (a nonnegative integer, which is a valid array index).
cl-slice-dev.lisp (file)
First COUNT indexes.
cl-slice.lisp (file)
Range, including both ends.
cl-slice.lisp (file)
Slice a single index, but don’t drop a dimension.
cl-slice.lisp (file)
Return a list for the dimensions of canonical representations, dropping singletons.
cl-slice-dev.lisp (file)
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.
cl-slice-dev.lisp (file)
Test if a canonical REPRESENTATION is a singleton.
cl-slice-dev.lisp (file)
Test if SYMBOL has special semantics for SLICE.
cl-slice-dev.lisp (file)
Last COUNT indexes.
cl-slice.lisp (file)
Next: Exported structures, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Return the dimension of axis. Needs to be defined for non-integer axes.
cl-slice-dev.lisp (file)
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.
cl-slice-dev.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
Map sequence into a simple-bit-vector, using 1 when PREDICATE yields true, 0 otherwise.
cl-slice.lisp (file)
Return the element of OBJECT specified by SUBSCRIPTS.
cl-slice.lisp (file)
(setf ref) (generic function)
cl-slice.lisp (file)
ref (generic function)
Return the slice of OBJECT specified by SLICES.
cl-slice.lisp (file)
(setf slice) (generic function)
cl-slice.lisp (file)
slice (generic function)
Return an index of the positions in SEQUENCE which satisfy PREDICATE.
cl-slice.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
cl-slice-dev.lisp (file)
structure-object (structure)
canonical-representation (method)
alexandria:array-index
canonical-range-start (function)
(setf canonical-range-start) (function)
alexandria:array-index
canonical-range-end (function)
(setf canonical-range-end) (function)
Canonical representation of a sequence of array indexes.
cl-slice-dev.lisp (file)
structure-object (structure)
canonical-representation (method)
(simple-array alexandria:array-index (*))
canonical-sequence-vector (function)
(setf canonical-sequence-vector) (function)
Range, including both ends.
cl-slice.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.
cl-slice.lisp (file)
structure-object (structure)
canonical-representation (method)
nodrop-index (function)
(setf nodrop-index) (function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal functions |
Previous: Internal definitions, Up: Internal definitions [Contents][Index]
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
cl-slice-dev.lisp (file)
cl-slice-dev.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
cl-slice.lisp (file)
Return the dimension of a canonical-representation, or NIL for singleton slices (they are dropped).
cl-slice-dev.lisp (file)
Initial value for iteration.
cl-slice-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.
cl-slice-dev.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
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 S |
|---|
| Jump to: | C I N P S |
|---|