assoc-list/add [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Add a new element to the given assoc-list object. By default the new element is added at the end of the data list but the optional argument can change this.
ARGUMENTS
- A key/data pair as a list, or a named-object. - The assoc-list object to which it is to be added.
OPTIONAL ARGUMENTS
- T or NIL to add items to the front of the data list. Default = NIL = to the end
RETURN VALUE
Returns T if the specified named-object is successfully added to the given assoc-list. Returns an error if an attempt is made to add NIL to the given assoc-list or if the given named-object is already present in the given assoc-list.
EXAMPLE
(let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (add '(makers mark) al)) => T (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (add '(makers mark) al) (get-data 'makers al)) => NAMED-OBJECT: id: MAKERS, tag: NIL, data: MARK (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (add '(makers mark) al) (get-position 'makers al)) => 3 (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (add '(knob creek) al)) => T
SYNOPSIS
(defmethod add (named-object (al assoc-list) &optional front)
assoc-list/add-to-list-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Add an element of any type to the end of the data (list) associated with a given key of a given assoc-list. The data associated with the given key must already be a list.
ARGUMENTS
- An item of any type. - A given key that must be present in the given assoc-list. - The given assoc-list.
RETURN VALUE
Returns the whole named-object to which the new element was added. This method will abort with an error if a key is sought which does not exist within the given assoc-list. For such cases, use add-to-list-data-force instead.
EXAMPLE
(let ((al (make-assoc-list 'test '((cat felix) (dog (fido spot)) (cow bessie))))) (add-to-list-data 'rover 'dog al)) => NAMED-OBJECT: id: DOG, tag: NIL, data: (FIDO SPOT ROVER)
SYNOPSIS
(defmethod add-to-list-data (new-element key (al assoc-list))
assoc-list/add-to-list-data-force [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Similar to add-to-list-data, but if the given key doesn't already exist in the given assoc-list, it is first added, then the given new element is added to that as a 1-element list. If the given key already exists within the given assoc-list, its data must already be in the form of a list.
ARGUMENTS
- A (new) element of any type. - A given key that may or may not be present in the given assoc-list. - The the given assoc-list.
RETURN VALUE
Returns the whole named-object to which the element was added when used with a key that already exists within the given assoc-list. Returns T when used with a key that does not already exist in the given assoc-list.
EXAMPLE
(let ((al (make-assoc-list 'test '((cat felix) (dog (fido spot)) (cow bessie))))) (add-to-list-data-force 'rover 'dog al)) => NAMED-OBJECT: id: DOG, tag: NIL, data: (FIDO SPOT ROVER) (let ((al (make-assoc-list 'test '((cat felix) (dog (fido spot)) (cow bessie))))) (add-to-list-data-force 'wilbur 'pig al) (get-keys al)) => (CAT DOG COW PIG)
SYNOPSIS
(defmethod add-to-list-data-force (new-element key (al assoc-list))
assoc-list/ascending-ids? [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DATE
September 19th 2020, Heidhausen
DESCRIPTION
Check whether all IDs are ascending integers (though order can be any), none missing, optionally starting from particular integer.
ARGUMENTS
- the assoc-list object
OPTIONAL ARGUMENTS
- an integer representing the lowest required ID
RETURN VALUE
T or NIL
EXAMPLE
(ascending-ids? (make-assoc-list 'test '((1 dog) (2 cat) (3 horse)))) -> T ;;; 3 is missing (ascending-ids? (make-assoc-list 'test '((1 dog) (2 cat) (4 horse)))) -> NIL ;; doesn't start at 2 (ascending-ids? (make-assoc-list 'test '((1 dog) (2 cat) (3 horse))) 2) -> NIL ;; missing several integers (ascending-ids? (make-assoc-list 'test '((4 dog) (2 cat) (7 horse))) 2) -> NIL (ascending-ids? (make-assoc-list 'test '((4 dog) (2 cat) (3 horse))) 2) -> T
SYNOPSIS
(defmethod ascending-ids? ((al assoc-list) &optional starting-from)
assoc-list/get-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Return the named-object (id, tag and data) that is identified by a specified key within a given assoc-list. NB: This method returns the named object itself, not just the data associated with the key (use get-data-data for that).
ARGUMENTS
- A symbol that is the key (id) of the named-object sought. - The assoc-list object in which it is be sought.
OPTIONAL ARGUMENTS
- T or NIL to indicate whether a warning is printed if the specified key cannot be found within the given assoc-list. T = print. Default = T. Mostly we define whether we want to warn in the instance itself, but sometimes it would be good to warn or not on a call basis, hence the optional argument. If a function is passed here that will be called instead of warn (e.g. #'error)
RETURN VALUE
A named-object is returned if the specified key is found within the given assoc-list object. NIL is returned and a warning is printed if the specified key is not found in the given assoc-list object.
EXAMPLE
(let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-data 'four al)) => NAMED-OBJECT: id: FOUR, tag: NIL, data: ROSES (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-data 'jack al)) => NIL WARNING: assoc-list::get-data: Could not find data with key JACK in assoc-list with id TEST (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-data 'jack al t)) => NIL WARNING: assoc-list::get-data: Could not find data with key JACK in assoc-list with id TEST (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-data 'jack al nil)) => NIL
SYNOPSIS
(defmethod get-data (key (al assoc-list) &optional (warn t))
assoc-list/get-data-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
(Short-cut for (data (get-data ...)) Get the data associated with the given key of the given assoc-list.
ARGUMENTS
- The assoc-list key symbol associated with the data list which is sought. - The assoc-list in which it is to be sought.
OPTIONAL ARGUMENTS
- T or NIL to indicate whether to print a warning if no such named-object can be found within the given assoc-list (default = T).
RETURN VALUE
If the given key is found within the given assoc-list, the data associated with that key is returned.
EXAMPLE
(let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-data-data 'jim al)) => BEAM (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-data-data 'jack al)) => NIL WARNING: assoc-list::get-data: Could not find data with key JACK in assoc-list with id TEST
SYNOPSIS
(defmethod get-data-data (key (al assoc-list) &optional (warn t))
assoc-list/get-first [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Returns the first named-object in the DATA slot of the given assoc-list object.
ARGUMENTS
- An assoc-list object.
RETURN VALUE
A named-object that is the first object in the DATA slot of the given assoc-list object.
EXAMPLE
(let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-first al)) => NAMED-OBJECT: id: JIM, tag: NIL, data BEAM
SYNOPSIS
(defmethod get-first ((al assoc-list))
assoc-list/get-keys [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Get a simple list of the keys in a given association list.
ARGUMENTS
- An assoc-list.
OPTIONAL ARGUMENTS
- Optional argument: T or NIL (default T) to indicate whether a warning should be printed when the first argument is a recursive assoc-list.
RETURN VALUE
A list of the keys only of all top-level association list pairs in the given assoc-list. get-keys is a method of the assoc-list class and therefore returns only top-level keys if accessing a recursive assoc-list.
EXAMPLE
(let ((al (make-assoc-list 'test '((cat felix) (dog fido) (cow bessie))))) (get-keys al)) => (CAT DOG COW) (let ((al (make-assoc-list 'test '((cat felix) (dog ((scottish terrier) (german shepherd) (irish wolfhound))) (cow bessie))))) (get-keys al)) => (CAT DOG COW)
SYNOPSIS
(defmethod get-keys ((al assoc-list) &optional (warn t))
assoc-list/get-nearest [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DATE
4/8/2015
DESCRIPTION
In assoc-lists with numeric IDs, return the object with the closest ID to the given key.
ARGUMENTS
- they key (number) - the assoc-list object
RETURN VALUE
a named-object
SYNOPSIS
(defmethod get-nearest (key (al assoc-list) &optional ignore1 ignore2)
assoc-list/get-position [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Returns the index position (zero-based) of a named-object within a given assoc-list.
ARGUMENTS
- The assoc-list key symbol (named-object id) of the object for which the position is sought. - The assoc-list in which it is to be sought.
OPTIONAL ARGUMENTS
- Optional argument: An indexing integer. In this case, get-position will search for the given object starting part-way into the list, skipping all objects located at indices lower than the given integer (default = 0).
RETURN VALUE
The integer index of the named-object within the given assoc-list. NIL is returned if the object is not present in the assoc-list starting with the index number given as the start argument (i.e., in the entire list if the optional start argument is omitted).
EXAMPLE
(let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-position 'four al)) => 1 (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-position 'jack al)) => NIL (let ((al (make-assoc-list 'test '((jim beam) (four roses) (wild turkey))))) (get-position 'jim al 1)) => NIL
SYNOPSIS
(defmethod get-position (key (al assoc-list) &optional (start 0))
assoc-list/make-assoc-list [ Functions ]
[ Top ] [ assoc-list ] [ Functions ]
DESCRIPTION
A function that provides a shortcut to creating an assoc-list, filling it with data, and assigning a name to it.
ARGUMENTS
- The name of the assoc-list to be created. - The data with which to fill it.
OPTIONAL ARGUMENTS
keyword arguments: - :warn-not-found. T or NIL to indicate whether a warning is printed when an index which doesn't exist is used for look-up. T = warn. Default = T.
RETURN VALUE
Returns the assoc-list as a named-object.
EXAMPLE
(make-assoc-list 'looney-tunes '((bugs bunny)
(daffy duck)
(porky pig)))
=>
ASSOC-LIST: warn-not-found T
CIRCULAR-SCLIST: current 0
SCLIST: sclist-length: 3, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL
this: NIL
next: NIL
NAMED-OBJECT: id: LOONEY-TUNES, tag: NIL,
data: (
NAMED-OBJECT: id: BUGS, tag: NIL,
data: BUNNY
NAMED-OBJECT: id: DAFFY, tag: NIL,
data: DUCK
NAMED-OBJECT: id: PORKY, tag: NIL,
data: PIG)
SYNOPSIS
(defun make-assoc-list (id al &key (warn-not-found t))
assoc-list/map-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Map a function over the data in the assoc-list, i.e. call the given function/method on each data slot of each named-object in the assoc-list data slot. See also recursive-assoc-list's rmap method which does pretty much the same but acting recursively on each named-object (unless it is itself recursive), rather than the named-object's data.
ARGUMENTS
- The assoc-list to which the function is to be applied. - The function to be applied. This must take the data in the assoc-list as a first argument.
OPTIONAL ARGUMENTS
- &rest: Further arguments for the function.
RETURN VALUE
Returns a list of the values returned by the function call on the data.
EXAMPLE
(let ((al (make-assoc-list 'al-test '((1 (1 2 3 4)) (2 (5 6 7 8)) (3 (9 10 11 12)))))) (map-data al #'(lambda (y) (loop for i in y collect (* i 2))))) => ((2 4 6 8) (10 12 14 16) (18 20 22 24))
SYNOPSIS
(defmethod map-data ((al assoc-list) function &rest further-arguments)
assoc-list/nmap-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DATE
November 1st 2018, Heidhausen
DESCRIPTION
A destructive version of map-data: replace the data slot with the named-object returned by the 2nd argument after it is passed one named-object after another.
ARGUMENTS
See the map-data method in this class.
RETURN VALUE
the assoc-list object with modified data in its elements.
EXAMPLE
(let ((al (make-assoc-list 'test '((1 (2 3)) (2 (4 5 6)) (3 (7)))))) (nmap-data al #'(lambda (data) (length data))) al) ... data: ( NAMED-OBJECT: id: 1, tag: NIL, data: 2 ************** NAMED-OBJECT: id: 2, tag: NIL, data: 3 ************** NAMED-OBJECT: id: 3, tag: NIL, data: 1 ...
SYNOPSIS
(defmethod nmap-data ((al assoc-list) function &rest further-arguments)
assoc-list/reindex [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DATE
14th June 2017, Edinburgh
DESCRIPTION
Re-index the named-objects to consecutive integers starting from a given number.
ARGUMENTS
- the assoc-list object
OPTIONAL ARGUMENTS
- the integer to start reindexing at
RETURN VALUE
the assoc-list object
SYNOPSIS
(defmethod reindex ((al assoc-list) &optional (start 1))
assoc-list/remove-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DATE
February 1st 2016
DESCRIPTION
Convenience function to allow objects to be removed from an assoc-list (and subclasses e.g. palettes and maps)
ARGUMENTS
- the assoc-list object - as many keys as you like for the members of the assoc-list. If none are passed then all are removed.
RETURN VALUE
The assoc-list object's new data list, i.e. with elements removed. Could of course be NIL if you've not passed any keys.
SYNOPSIS
(defmethod remove-data ((al assoc-list) &rest keys)
assoc-list/remove-when [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DATE
June 28th 2017, Edinburgh
DESCRIPTION
Use a function to test each object in an assoc-list and if the test returns T, then remove the object. Works in recursive-assoc-list class too.
ARGUMENTS
- an assoc-list object - a function that returns T or NIL after interrogating a named-object or subclass's slots
RETURN VALUE
a list of the IDs of the objects removed.
EXAMPLE
(let ((al (make-assoc-list 'mixed-bag '((jim beam) (wild turkey) (four roses))))) (remove-when al #'(lambda (x) (eq (data x) 'roses))))
SYNOPSIS
(defmethod remove-when ((al assoc-list) test)
assoc-list/replace-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
A convenience method that's essentially the same as set-data but without having to pass the new ID in a list along with the new value.
ARGUMENTS
- The key (number, symbol, string) to the existing data. - The new value to be associated with this key (any data). - The assoc-list object
RETURN VALUE
The named-object for the datum.
SYNOPSIS
(defmethod replace-data (key new-value (al assoc-list))
assoc-list/set-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Replace the named-object associated with a specified key within a given assoc-list object. This method replaces the whole named-object, not just the data of that object.
ARGUMENTS
- A key present within the given assoc-list object. - A key/data pair as a list. - The assoc-list object in which to find and replace the named-object associated with the specified key.
RETURN VALUE
Returns the new named-object. Returns NIL when the given key is not present within the given assoc-list.
EXAMPLE
(let ((al (make-assoc-list 'test '((cat felix) (dog fido) (cow bessie))))) (set-data 'dog '(dog spot) al)) => NAMED-OBJECT: id: DOG, tag: NIL, data: SPOT (let ((al (make-assoc-list 'test '((cat felix) (dog fido) (cow bessie))))) (set-data 'pig '(pig wilbur) al)) => NIL WARNING: assoc-list::set-data: Could not find data with key PIG in assoc-list with id TEST (let ((al (make-assoc-list 'test '((cat felix) (dog fido) (cow bessie))))) (set-data 'dog '(pig wilbur) al)) => NAMED-OBJECT: id: PIG, tag: NIL, data: WILBUR
SYNOPSIS
(defmethod set-data (key new-value (al assoc-list))
assoc-list/set-nth-of-data [ Methods ]
[ Top ] [ assoc-list ] [ Methods ]
DESCRIPTION
Replace a given member of a given data list within a given assoc-list.
ARGUMENTS
- The key (named-object id) associated with the data to be changed. - The zero-based integer index of the member of the list to be changed. - The new value. - The assoc-list in which the change is to be made. The data to be modified must already be in the form of a list. The index integer given must be less than the length of the data list to be modified.
RETURN VALUE
Returns the new value only.
EXAMPLE
(let ((al (make-assoc-list 'test '((cat felix) (dog (fido spot rover)) (cow bessie))))) (set-nth-of-data 'dog 0 'snoopy al)) => SNOOPY (let ((al (make-assoc-list 'test '((cat felix) (dog (fido spot rover)) (cow bessie))))) (set-nth-of-data 'dog 0 'snoopy al) (get-data 'dog al)) => NAMED-OBJECT: id: DOG, tag: NIL, data: (SNOOPY SPOT ROVER)
SYNOPSIS
(defmethod set-nth-of-data (key nth new-value (al assoc-list))
circular-sclist/assoc-list [ Classes ]
[ Top ] [ circular-sclist ] [ Classes ]
NAME
assoc-list File: assoc-list.lsp Class Hierarchy: named-object -> linked-named-object -> sclist -> circular-sclist -> assoc-list Version: 1.1.0 Project: slippery chicken (algorithmic composition) Purpose: Implementation of the assoc-list class that is somewhat like the lisp association list but with more error-checking. Author: Michael Edwards: m@michael-edwards.org Creation date: February 18th 2001 $$ Last modified: 12:21:40 Fri Mar 22 2024 CET SVN ID: $Id$