The group-by Reference Manual

This is the group-by Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:37:46 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 group-by

A Common Lisp library to help group data into trees (of various formats) based on common/shared values

License

BSD

Version

0.1

Dependencies
  • iterate (system).
  • alexandria (system).
Source

group-by.asd.

Child Component

group-by.lisp (file).


3 Files

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


3.1 Lisp


3.1.1 group-by/group-by.asd

Source

group-by.asd.

Parent Component

group-by (system).

ASDF Systems

group-by.

Packages

group-by.system.


3.1.2 group-by/group-by.lisp

Source

group-by.asd.

Parent Component

group-by (system).

Packages

group-by.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 group-by

Source

group-by.lisp.

Use List
  • common-lisp.
  • common-lisp-user.
  • iterate.
Public Interface
Internals

4.2 group-by.system

Source

group-by.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: group-by (list &key key value key-fn test)

groups the list into an alist using the key function and value function to group by key, with a list of all values for that key.

key is used to determine the key in the a-list
value is used to determin the value in the a-list
key-fn is passed as the :key to assoc
test is passed as the :test to assoc

eg: (group-by ’((a 1 2) (a 3 4) (b 5 6)))
=> ((A (1 2) (3 4)) (B (5 6)))

Package

group-by.

Source

group-by.lisp.

Function: group-by-repeated (list &key keys tests)

Returns an alist tree that represents the items in the list as categorized
by keys (compared with tests)
ex: ((a 3 sam) (c 4 bob) (a 3 ted))

keys: a list of key functions that describe the categorizations in order tests: how we are testing whether or not two keys are equal, defaults to #’equal

Package

group-by.

Source

group-by.lisp.

Function: grouped-list-speed-tester (&key list keys tests hash-tests iterations actions)

A function to help assess which implementation will work best in your given scenario actions : (lambda (gl) ...) -to help test whatever grouped list
operations you will need to do repeatedly

Package

group-by.

Source

group-by.lisp.

Function: make-grouped-list (inp &key tests keys grouping-implementation)

Given a list of input, produce a grouped-list CLOS object that contains
the original list, configuration about the groupings and the result tree
of grouped-list objects

”keys”: a list of keys to group by<br />
”tests”: a list of tests to compare the keys with<br />

”grouping-implmentation”: What data structure should be used to perform the grouping<br /> ”:alist, :tree , :hash-table”<br />
The implementation doesnt change the output, but it does change
the performance characteristics of the grouped-object (see:
grouped-list-speed-tester for help deciding which to use)

Package

group-by.

Source

group-by.lisp.


5.1.2 Generic functions

Generic Function: add-item-to-grouping (item grouped-list)
Package

group-by.

Source

group-by.lisp.

Methods
Method: add-item-to-grouping (item (gl grouped-list))

puts a new item in the grouping of the grouped list (but not in the original list)

Generic Function: categorize-item (item root &key keys tests &allow-other-keys)

Insert a new item into a grouped list

Package

group-by.

Source

group-by.lisp.

Methods
Method: categorize-item (item (root grouped-list) &key &allow-other-keys)
Method: categorize-item (item (root list) &key keys tests &allow-other-keys)

Categorize a new item into an alist as produced by group-by-repeated This will create new category nodes if necessary

Generic Function: child-groupings (grouped-list)
Package

group-by.

Source

group-by.lisp.

Methods
Method: child-groupings ((gl grouped-list))
Generic Function: items-in-group (grouped-list &rest keys)

a list of key values that will produce a list of all the items in a given group

Package

group-by.

Source

group-by.lisp.

Methods
Method: items-in-group ((gl grouped-list) &rest key-values)
Generic Reader: key-value (object)
Generic Writer: (setf key-value) (object)
Package

group-by.

Methods
Reader Method: key-value ((grouped-list grouped-list))
Writer Method: (setf key-value) ((grouped-list grouped-list))

If this is a subgrouping of another grouped-list, what is the key this grouped-list represents in the parent grouping (mostly for testing)

Source

group-by.lisp.

Target Slot

key-value.

Generic Reader: keys (object)
Generic Writer: (setf keys) (object)
Package

group-by.

Methods
Reader Method: keys ((grouped-list grouped-list))
Writer Method: (setf keys) ((grouped-list grouped-list))

A list of key functions we will use to group the list

Source

group-by.lisp.

Target Slot

keys.

Generic Function: make-child-grouped-list (gl key-value grouped-list)
Package

group-by.

Methods
Method: make-child-grouped-list ((gl grouped-list) key-value grouped-list)
Source

group-by.lisp.

Generic Reader: parent-grouping (object)
Generic Writer: (setf parent-grouping) (object)
Package

group-by.

Methods
Reader Method: parent-grouping ((grouped-list grouped-list))
Writer Method: (setf parent-grouping) ((grouped-list grouped-list))

If this is a subgrouping of another grouped-list, what is the parent grouping we are apart of (mostly for testing)

Source

group-by.lisp.

Target Slot

parent-grouping.

Generic Reader: tests (object)
Generic Writer: (setf tests) (object)
Package

group-by.

Methods
Reader Method: tests ((grouped-list grouped-list))
Writer Method: (setf tests) ((grouped-list grouped-list))

A list of test functions we will use to test key equality
tree: defaults to #’equal
hash-table: this be a single hash-equality symbol (defaults to ’equal)

Source

group-by.lisp.

Target Slot

tests.


5.1.3 Standalone methods

Method: initialize-instance :after ((o grouped-list) &key list &allow-other-keys)
Source

group-by.lisp.


5.1.4 Classes

Class: grouped-list

This class represents a list that we have grouped by multiple key values ala one of the group-by-repeatedly functions

Package

group-by.

Source

group-by.lisp.

Direct methods
Direct slots
Slot: orig-list
Initargs

:orig-list

Readers

orig-list.

Writers

(setf orig-list).

Slot: grouping-implementation

What data structure should be used to perform the grouping :list, :hash-table

Initform

:list

Initargs

:grouping-implementation

Readers

grouping-implementation.

Writers

(setf grouping-implementation).

Slot: keys

A list of key functions we will use to group the list

Initargs

:keys

Readers

keys.

Writers

(setf keys).

Slot: tests

A list of test functions we will use to test key equality
tree: defaults to #’equal
hash-table: this be a single hash-equality symbol (defaults to ’equal)

Initargs

:tests

Readers

tests.

Writers

(setf tests).

Slot: %child-groupings
Initargs

:%child-groupings

Readers

%child-groupings.

Writers

(setf %child-groupings).

Slot: %items
Initargs

:%items

Readers

%items.

Writers

(setf %items).

Slot: parent-grouping

If this is a subgrouping of another grouped-list, what is the parent grouping we are apart of (mostly for testing)

Initargs

:parent

Readers

parent-grouping.

Writers

(setf parent-grouping).

Slot: key-value

If this is a subgrouping of another grouped-list, what is the key this grouped-list represents in the parent grouping (mostly for testing)

Initargs

:key-value

Readers

key-value.

Writers

(setf key-value).


5.2 Internals


5.2.1 Ordinary functions

Function: find-single-sub-category (gl key-value &key test)
Package

group-by.

Source

group-by.lisp.


5.2.2 Generic functions

Generic Reader: %child-groupings (object)
Package

group-by.

Methods
Reader Method: %child-groupings ((grouped-list grouped-list))

automatically generated reader method

Source

group-by.lisp.

Target Slot

%child-groupings.

Generic Writer: (setf %child-groupings) (object)
Package

group-by.

Methods
Writer Method: (setf %child-groupings) ((grouped-list grouped-list))

automatically generated writer method

Source

group-by.lisp.

Target Slot

%child-groupings.

Generic Function: %grouping-items (grouped-list)
Package

group-by.

Source

group-by.lisp.

Methods
Method: %grouping-items ((gl grouped-list))

Returns the items in a given group

Generic Reader: %items (object)
Package

group-by.

Methods
Reader Method: %items ((grouped-list grouped-list))

automatically generated reader method

Source

group-by.lisp.

Target Slot

%items.

Generic Writer: (setf %items) (object)
Package

group-by.

Methods
Writer Method: (setf %items) ((grouped-list grouped-list))

automatically generated writer method

Source

group-by.lisp.

Target Slot

%items.

Generic Reader: grouping-implementation (object)
Generic Writer: (setf grouping-implementation) (object)
Package

group-by.

Methods
Reader Method: grouping-implementation ((grouped-list grouped-list))
Writer Method: (setf grouping-implementation) ((grouped-list grouped-list))

What data structure should be used to perform the grouping :list, :hash-table

Source

group-by.lisp.

Target Slot

grouping-implementation.

Generic Reader: orig-list (object)
Package

group-by.

Methods
Reader Method: orig-list ((grouped-list grouped-list))

automatically generated reader method

Source

group-by.lisp.

Target Slot

orig-list.

Generic Writer: (setf orig-list) (object)
Package

group-by.

Methods
Writer Method: (setf orig-list) ((grouped-list grouped-list))

automatically generated writer method

Source

group-by.lisp.

Target Slot

orig-list.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   C   F   G   I   K   M   O   P   T  
Index Entry  Section

%
%child-groupings: Private generic functions
%child-groupings: Private generic functions
%grouping-items: Private generic functions
%grouping-items: Private generic functions
%items: Private generic functions
%items: Private generic functions

(
(setf %child-groupings): Private generic functions
(setf %child-groupings): Private generic functions
(setf %items): Private generic functions
(setf %items): Private generic functions
(setf grouping-implementation): Private generic functions
(setf grouping-implementation): Private generic functions
(setf key-value): Public generic functions
(setf key-value): Public generic functions
(setf keys): Public generic functions
(setf keys): Public generic functions
(setf orig-list): Private generic functions
(setf orig-list): Private generic functions
(setf parent-grouping): Public generic functions
(setf parent-grouping): Public generic functions
(setf tests): Public generic functions
(setf tests): Public generic functions

A
add-item-to-grouping: Public generic functions
add-item-to-grouping: Public generic functions

C
categorize-item: Public generic functions
categorize-item: Public generic functions
categorize-item: Public generic functions
child-groupings: Public generic functions
child-groupings: Public generic functions

F
find-single-sub-category: Private ordinary functions
Function, find-single-sub-category: Private ordinary functions
Function, group-by: Public ordinary functions
Function, group-by-repeated: Public ordinary functions
Function, grouped-list-speed-tester: Public ordinary functions
Function, make-grouped-list: Public ordinary functions

G
Generic Function, %child-groupings: Private generic functions
Generic Function, %grouping-items: Private generic functions
Generic Function, %items: Private generic functions
Generic Function, (setf %child-groupings): Private generic functions
Generic Function, (setf %items): Private generic functions
Generic Function, (setf grouping-implementation): Private generic functions
Generic Function, (setf key-value): Public generic functions
Generic Function, (setf keys): Public generic functions
Generic Function, (setf orig-list): Private generic functions
Generic Function, (setf parent-grouping): Public generic functions
Generic Function, (setf tests): Public generic functions
Generic Function, add-item-to-grouping: Public generic functions
Generic Function, categorize-item: Public generic functions
Generic Function, child-groupings: Public generic functions
Generic Function, grouping-implementation: Private generic functions
Generic Function, items-in-group: Public generic functions
Generic Function, key-value: Public generic functions
Generic Function, keys: Public generic functions
Generic Function, make-child-grouped-list: Public generic functions
Generic Function, orig-list: Private generic functions
Generic Function, parent-grouping: Public generic functions
Generic Function, tests: Public generic functions
group-by: Public ordinary functions
group-by-repeated: Public ordinary functions
grouped-list-speed-tester: Public ordinary functions
grouping-implementation: Private generic functions
grouping-implementation: Private generic functions

I
initialize-instance: Public standalone methods
items-in-group: Public generic functions
items-in-group: Public generic functions

K
key-value: Public generic functions
key-value: Public generic functions
keys: Public generic functions
keys: Public generic functions

M
make-child-grouped-list: Public generic functions
make-child-grouped-list: Public generic functions
make-grouped-list: Public ordinary functions
Method, %child-groupings: Private generic functions
Method, %grouping-items: Private generic functions
Method, %items: Private generic functions
Method, (setf %child-groupings): Private generic functions
Method, (setf %items): Private generic functions
Method, (setf grouping-implementation): Private generic functions
Method, (setf key-value): Public generic functions
Method, (setf keys): Public generic functions
Method, (setf orig-list): Private generic functions
Method, (setf parent-grouping): Public generic functions
Method, (setf tests): Public generic functions
Method, add-item-to-grouping: Public generic functions
Method, categorize-item: Public generic functions
Method, categorize-item: Public generic functions
Method, child-groupings: Public generic functions
Method, grouping-implementation: Private generic functions
Method, initialize-instance: Public standalone methods
Method, items-in-group: Public generic functions
Method, key-value: Public generic functions
Method, keys: Public generic functions
Method, make-child-grouped-list: Public generic functions
Method, orig-list: Private generic functions
Method, parent-grouping: Public generic functions
Method, tests: Public generic functions

O
orig-list: Private generic functions
orig-list: Private generic functions

P
parent-grouping: Public generic functions
parent-grouping: Public generic functions

T
tests: Public generic functions
tests: Public generic functions