The select Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The select Reference Manual

This is the select Reference Manual, version 1.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 06:07:37 2022 GMT+0.

Table of Contents


1 Introduction

Contributors Forks Stargazers Issues MS-PL License LinkedIn

About the Project

This library provides:

  1. 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 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 select.
  3. A set of utility functions for traversing selections in array-like objects.

Built With

Getting Started

To get a local copy up and running follow these steps:

Prerequisites

An ANSI Common Lisp implementation. Developed and tested with SBCL and CCL.

Installation

  1. Clone the repository
    cd ~/quicklisp/local-projects &&
    git clone https://github.com/Lisp-Stat/select.git
    
  2. Reset the ASDF source-registry to find the new system (from the REPL)
    (asdf:clear-source-registry)
    
  3. Load the system
    (ql:quickload :select)
    

Documentation

The API documentation is in the docs/ directory and is available in emacs info format, PDF and HTML. You can also view the documentation online.

Usage

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 in the documentation.

For more examples, please refer to the Reference Manual

Roadmap

See the open issues for a list of proposed features (and known issues).

Known Issues

Select is known to pass all tests on SBCL and ACL (Allegro Common Lisp), and fails two tests on CCL related to vector/array representations. The specifics are described in issue #3. I suspect this to be a bug somewhere in CCL. Version 1.12 of CCL doesn't run on MS Windows, so the obvious next step is not available (install 1.12 and try). It could also be specific to MS Windows. If someone successfully gets this to run on another platform, I'd appreciate hearing about it.

Changes from cl-slice

Documentation Improvements

Test Improvements

Enhancements

Bug Fixes

Resources

This system is part of the Lisp-Stat project; that should be your first stop for information. Also see the resources and community pages for more information.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Please see CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

License

Distributed under the MS-PL License. See LICENSE for more information.

Contact

Project Link: https://github.com/lisp-stat/select


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 select

DSL for array slices.

Author

Steve Nunez

Home Page

https://lisp-stat.github.io/select/

Source Control

(GIT git://github.com/Lisp-Stat/select)

Bug Tracker

https://github.com/Lisp-Stat/select/issues/

License

MS-PL

Long Description

Select is a facility for selecting portions of sequences, arrays or data-frames. 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://lisp-stat.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.

Version

1.3

Dependencies
  • alexandria (system).
  • anaphora (system).
  • let-plus (system).
Source

select.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 select/select.asd

Source

select.asd.

Parent Component

select (system).

ASDF Systems

select.


3.1.2 select/package.lisp

Source

select.asd.

Parent Component

select (system).

Packages

3.1.3 select/select-dev.lisp

Dependency

package.lisp (file).

Source

select.asd.

Parent Component

select (system).

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.4 select/select.lisp

Dependency

select-dev.lisp (file).

Source

select.asd.

Parent Component

select (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 select-dev

SELECT-DEV is used to implement SELECT operations on data structures other than arrays.

Source

package.lisp.

Use List
  • alexandria.
  • anaphora.
  • common-lisp.
  • let-plus.
Used By List

select.

Public Interface
Internals

Previous: , Up: Packages   [Contents][Index]

4.2 select

SELECT is a facility for selecting portions of sequences or arrays.

Source

package.lisp.

Nickname

slct

Use List
  • alexandria.
  • anaphora.
  • common-lisp.
  • let-plus.
  • select-dev.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Macros

Macro: traverse-representations ((subscripts representations &key index setup) &body body)

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.

Package

select-dev.

Source

select-dev.lisp.


5.1.2 Ordinary functions

Function: all-singleton-representations? (representations)

Test if all canonical representations are singletons.

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-range (start end)

Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-representations (axes selections)

Return the canonical representations of SELECTIONS given the corresponding AXES, checking for matching length.

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-sequence (sequence)

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.

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-singleton (index)

Canonical representation of a singleton index (a nonnegative integer, which is a valid array index).

Package

select-dev.

Source

select-dev.lisp.

Function: column-major-setup (representations terminator)

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.

Package

select-dev.

Source

select-dev.lisp.

Function: including (start end)

Range, including both ends.

Package

select.

Source

select.lisp.

Function: nodrop (index)

Select a single index, but do not drop a dimension.

Package

select.

Source

select.lisp.

Function: range (start end)

Range, including START, excluding END.

Package

select.

Source

select.lisp.

Function: representation-dimensions (representations)

Return a list for the dimensions of canonical representations, dropping singletons.

Package

select-dev.

Source

select-dev.lisp.

Function: row-major-setup (representations terminator)

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.

Package

select-dev.

Source

select-dev.lisp.

Function: select-reserved-symbol? (symbol)

Test if SYMBOL has special semantics for SELECTION.

Package

select-dev.

Source

select-dev.lisp.

Function: singleton-representation? (representation)

Test if a canonical REPRESENTATION is a singleton.

Package

select-dev.

Source

select-dev.lisp.


5.1.3 Generic functions

Generic Function: axis-dimension (axis)

Return the dimension of axis. Needs to be defined for non-integer axes.

Package

select-dev.

Source

select-dev.lisp.

Generic Function: canonical-representation (axis selection)

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.

Package

select-dev.

Source

select-dev.lisp.

Methods
Method: canonical-representation (axis (selection nodrop))

The canonical representation for NODROP.

Source

select.lisp.

Method: canonical-representation (axis (selection range))

The canonical representation for RANGE.

Source

select.lisp.

Method: canonical-representation (axis (selection including))

The canonical representation for INCLUDING.

Source

select.lisp.

Method: canonical-representation (axis selection)
Method: canonical-representation (axis (canonical-range canonical-range))
Method: canonical-representation (axis (canonical-sequence canonical-sequence))
Method: canonical-representation ((axis integer) (slice null))
Method: canonical-representation ((axis integer) (selection integer))
Method: canonical-representation (axis (selection sequence))
Method: canonical-representation ((axis integer) (selection (eql t)))
Method: canonical-representation (axis (selection bit-vector))
Generic Function: mask (sequence predicate)

Map sequence into a simple-bit-vector, using 1 when PREDICATE yields true, 0 otherwise.

Package

select.

Source

select.lisp.

Methods
Method: mask ((sequence sequence) predicate)
Generic Function: ref (object &rest subscripts)

Return the element of OBJECT specified by SUBSCRIPTS.

Package

select.

Source

select.lisp.

Methods
Method: ref ((array array) &rest subscripts)
Generic Function: (setf ref) (object &rest subscripts)

Stores VALUE into the place specified by SUBSCRIPTS.

Package

select.

Source

select.lisp.

Methods
Method: (setf ref) ((array array) &rest subscripts)
Generic Function: select (object &rest selections)

Return the slices of OBJECT specified by SELECTIONS.

Package

select.

Source

select.lisp.

Methods
Method: select ((lst list) &rest selections)

Select from LST the subscripts or range specified in SELECTIONS. SELECTIONS must be a VECTOR, LIST or RANGE.

Method: select ((array array) &rest selections)

Return the SELECTIONS in the given ARRAY.

Generic Function: (setf select) (object &rest selections)

Stores VALUES into the locations given by SELECTIONS.

Package

select.

Source

select.lisp.

Methods
Method: (setf select) ((array array) &rest selections)
Method: (setf select) ((array array) &rest selections)
Generic Function: which (sequence &key predicate)

Return an index of the positions in SEQUENCE which satisfy PREDICATE. Defaults to return non-NIL indices.

Package

select.

Source

select.lisp.

Methods
Method: which ((sequence sequence) &key predicate)

5.1.4 Structures

Structure: canonical-range

Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).

Package

select-dev.

Source

select-dev.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: start
Type

alexandria:array-index

Readers

canonical-range-start.

Writers

(setf canonical-range-start).

Slot: end
Type

alexandria:array-index

Readers

canonical-range-end.

Writers

(setf canonical-range-end).

Structure: canonical-sequence

Canonical representation of a sequence of array indexes.

Package

select-dev.

Source

select-dev.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: vector
Package

common-lisp.

Type

(simple-array alexandria:array-index (*))

Readers

canonical-sequence-vector.

Writers

(setf canonical-sequence-vector).

Structure: including

Range, including both ends.

Package

select.

Source

select.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: start
Readers

including-start.

Writers

(setf including-start).

Slot: end
Readers

including-end.

Writers

(setf including-end).

Structure: nodrop

Select a single index, but don’t drop a dimension.

Package

select.

Source

select.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: index
Readers

nodrop-index.

Writers

(setf nodrop-index).

Structure: range

Range, including start, excluding end.

Package

select.

Source

select.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: start
Readers

range-start.

Writers

(setf range-start).

Slot: end
Readers

range-end.

Writers

(setf range-end).


5.2 Internals


Previous: , Up: Internals   [Contents][Index]

5.2.1 Ordinary functions

Reader: canonical-range-end (instance)
Writer: (setf canonical-range-end) (instance)
Package

select-dev.

Source

select-dev.lisp.

Target Slot

end.

Function: canonical-range-p (object)
Package

select-dev.

Source

select-dev.lisp.

Reader: canonical-range-start (instance)
Writer: (setf canonical-range-start) (instance)
Package

select-dev.

Source

select-dev.lisp.

Target Slot

start.

Function: canonical-sequence-p (object)
Package

select-dev.

Source

select-dev.lisp.

Reader: canonical-sequence-vector (instance)
Writer: (setf canonical-sequence-vector) (instance)
Package

select-dev.

Source

select-dev.lisp.

Target Slot

vector.

Function: copy-canonical-range (instance)
Package

select-dev.

Source

select-dev.lisp.

Function: copy-canonical-sequence (instance)
Package

select-dev.

Source

select-dev.lisp.

Function: copy-including (instance)
Package

select.

Source

select.lisp.

Function: copy-nodrop (instance)
Package

select.

Source

select.lisp.

Function: copy-range (instance)
Package

select.

Source

select.lisp.

Reader: including-end (instance)
Writer: (setf including-end) (instance)
Package

select.

Source

select.lisp.

Target Slot

end.

Function: including-p (object)
Package

select.

Source

select.lisp.

Reader: including-start (instance)
Writer: (setf including-start) (instance)
Package

select.

Source

select.lisp.

Target Slot

start.

Function: make-canonical-range (&key start end)
Package

select-dev.

Source

select-dev.lisp.

Function: make-canonical-sequence (&key vector)
Package

select-dev.

Source

select-dev.lisp.

Function: make-including (&key start end)
Package

select.

Source

select.lisp.

Function: make-nodrop (&key index)
Package

select.

Source

select.lisp.

Function: make-range (&key start end)
Package

select.

Source

select.lisp.

Reader: nodrop-index (instance)
Writer: (setf nodrop-index) (instance)
Package

select.

Source

select.lisp.

Target Slot

index.

Function: nodrop-p (object)
Package

select.

Source

select.lisp.

Reader: range-end (instance)
Writer: (setf range-end) (instance)
Package

select.

Source

select.lisp.

Target Slot

end.

Function: range-p (object)
Package

select.

Source

select.lisp.

Reader: range-start (instance)
Writer: (setf range-start) (instance)
Package

select.

Source

select.lisp.

Target Slot

start.

Function: representation-dimension (representation)

Return the dimension of a canonical-representation, or NIL for singleton selections (they are dropped).

Package

select-dev.

Source

select-dev.lisp.

Function: representation-initial-value (representation)

Initial value for iteration.

Package

select-dev.

Source

select-dev.lisp.

Function: representation-iterator (representation carry cons)

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.

Package

select-dev.

Source

select-dev.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   F   G   I   M   N   R   S   T   W  
Index Entry  Section

(
(setf canonical-range-end): Private ordinary functions
(setf canonical-range-start): Private ordinary functions
(setf canonical-sequence-vector): Private ordinary functions
(setf including-end): Private ordinary functions
(setf including-start): Private ordinary functions
(setf nodrop-index): Private ordinary functions
(setf range-end): Private ordinary functions
(setf range-start): Private ordinary functions
(setf ref): Public generic functions
(setf ref): Public generic functions
(setf select): Public generic functions
(setf select): Public generic functions
(setf select): Public generic functions

A
all-singleton-representations?: Public ordinary functions
axis-dimension: Public generic functions

C
canonical-range: Public ordinary functions
canonical-range-end: Private ordinary functions
canonical-range-p: Private ordinary functions
canonical-range-start: Private ordinary functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representations: Public ordinary functions
canonical-sequence: Public ordinary functions
canonical-sequence-p: Private ordinary functions
canonical-sequence-vector: Private ordinary functions
canonical-singleton: Public ordinary functions
column-major-setup: Public ordinary functions
copy-canonical-range: Private ordinary functions
copy-canonical-sequence: Private ordinary functions
copy-including: Private ordinary functions
copy-nodrop: Private ordinary functions
copy-range: Private ordinary functions

F
Function, (setf canonical-range-end): Private ordinary functions
Function, (setf canonical-range-start): Private ordinary functions
Function, (setf canonical-sequence-vector): Private ordinary functions
Function, (setf including-end): Private ordinary functions
Function, (setf including-start): Private ordinary functions
Function, (setf nodrop-index): Private ordinary functions
Function, (setf range-end): Private ordinary functions
Function, (setf range-start): Private ordinary functions
Function, all-singleton-representations?: Public ordinary functions
Function, canonical-range: Public ordinary functions
Function, canonical-range-end: Private ordinary functions
Function, canonical-range-p: Private ordinary functions
Function, canonical-range-start: Private ordinary functions
Function, canonical-representations: Public ordinary functions
Function, canonical-sequence: Public ordinary functions
Function, canonical-sequence-p: Private ordinary functions
Function, canonical-sequence-vector: Private ordinary functions
Function, canonical-singleton: Public ordinary functions
Function, column-major-setup: Public ordinary functions
Function, copy-canonical-range: Private ordinary functions
Function, copy-canonical-sequence: Private ordinary functions
Function, copy-including: Private ordinary functions
Function, copy-nodrop: Private ordinary functions
Function, copy-range: Private ordinary functions
Function, including: Public ordinary functions
Function, including-end: Private ordinary functions
Function, including-p: Private ordinary functions
Function, including-start: Private ordinary functions
Function, make-canonical-range: Private ordinary functions
Function, make-canonical-sequence: Private ordinary functions
Function, make-including: Private ordinary functions
Function, make-nodrop: Private ordinary functions
Function, make-range: Private ordinary functions
Function, nodrop: Public ordinary functions
Function, nodrop-index: Private ordinary functions
Function, nodrop-p: Private ordinary functions
Function, range: Public ordinary functions
Function, range-end: Private ordinary functions
Function, range-p: Private ordinary functions
Function, range-start: Private ordinary functions
Function, representation-dimension: Private ordinary functions
Function, representation-dimensions: Public ordinary functions
Function, representation-initial-value: Private ordinary functions
Function, representation-iterator: Private ordinary functions
Function, row-major-setup: Public ordinary functions
Function, select-reserved-symbol?: Public ordinary functions
Function, singleton-representation?: Public ordinary functions

G
Generic Function, (setf ref): Public generic functions
Generic Function, (setf select): Public generic functions
Generic Function, axis-dimension: Public generic functions
Generic Function, canonical-representation: Public generic functions
Generic Function, mask: Public generic functions
Generic Function, ref: Public generic functions
Generic Function, select: Public generic functions
Generic Function, which: Public generic functions

I
including: Public ordinary functions
including-end: Private ordinary functions
including-p: Private ordinary functions
including-start: Private ordinary functions

M
Macro, traverse-representations: Public macros
make-canonical-range: Private ordinary functions
make-canonical-sequence: Private ordinary functions
make-including: Private ordinary functions
make-nodrop: Private ordinary functions
make-range: Private ordinary functions
mask: Public generic functions
mask: Public generic functions
Method, (setf ref): Public generic functions
Method, (setf select): Public generic functions
Method, (setf select): Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, mask: Public generic functions
Method, ref: Public generic functions
Method, select: Public generic functions
Method, select: Public generic functions
Method, which: Public generic functions

N
nodrop: Public ordinary functions
nodrop-index: Private ordinary functions
nodrop-p: Private ordinary functions

R
range: Public ordinary functions
range-end: Private ordinary functions
range-p: Private ordinary functions
range-start: Private ordinary functions
ref: Public generic functions
ref: Public generic functions
representation-dimension: Private ordinary functions
representation-dimensions: Public ordinary functions
representation-initial-value: Private ordinary functions
representation-iterator: Private ordinary functions
row-major-setup: Public ordinary functions

S
select: Public generic functions
select: Public generic functions
select: Public generic functions
select-reserved-symbol?: Public ordinary functions
singleton-representation?: Public ordinary functions

T
traverse-representations: Public macros

W
which: Public generic functions
which: Public generic functions

Jump to:   (  
A   C   F   G   I   M   N   R   S   T   W