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. 

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.0.12

 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:  18:16:28 Wed Jan 31 2024 CET

 SVN ID: $Id$