linked-named-object/sclist [ Classes ]

[ Top ] [ linked-named-object ] [ Classes ]

NAME

 player

 File:             sclist.lsp

 Class Hierarchy:  named-object -> linked-named-object -> sclist

 Version:          1.0.12

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Implementation of a simple but self-checking (hence
                   sclist) list class.  

 Author:           Michael Edwards: m@michael-edwards.org

 Creation date:    February 11th 2001

 $$ Last modified:  17:52:24 Wed Jan 31 2024 CET

 SVN ID: $Id$

sclist/combine [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Combine the contents of two given sclist objects into one list.  NB This
 changes the data list of a clone of the first argument by appending a
 copy of the data list of the second argument i.e. it creates a wholly new
 sclist object which it then returns.

ARGUMENTS

 - A first sclist object.
 - A second sclist object.

RETURN VALUE

 Returns an sclist object.

EXAMPLE

;; Combine the contents of two sclist objects to make a new one
(let ((scl1 (make-sclist '(0 1 2 3 4)))
      (scl2 (make-sclist '(5 6 7 8 9))))
  (combine scl1 scl2))

=> 
SCLIST: sclist-length: 10, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: (0 1 2 3 4 5 6 7 8 9)

SYNOPSIS

(defmethod combine ((scl1 sclist) (scl2 sclist))

sclist/get-last [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Returns the last element in the data list of a given sclist.

ARGUMENTS

 - An sclist.

RETURN VALUE

 The last object in the data list.

EXAMPLE

(let ((al (make-assoc-list 'test '((jim beam)
                                   (four roses)
                                   (wild turkey)))))
  (get-last al))

=> 
NAMED-OBJECT: id: WILD, tag: NIL,
data TURKEY

SYNOPSIS

(defmethod get-last ((scl sclist))

sclist/get-nth [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Get the nth element (zero-based) of data in a given sclist object.

ARGUMENTS

 - An index integer.
 - An sclist object.

RETURN VALUE

 Returns the item at index n within the given sclist object.
 
 Returns NIL and prints a warning if the specified index is greater than the
 number of items in the given list (minus 1).

EXAMPLE

;; Get the 3th item from the given sclist object
(let ((scl (make-sclist '(cat dog cow pig sheep))))
  (get-nth 3 scl))

=> PIG

;; Returns NIL and prints a warning when the specified index is beyond the
;; bounds of the given list
(let ((scl (make-sclist '(cat dog cow pig sheep))))
  (get-nth 31 scl))

=> 
NIL
WARNING: sclist::sclist-check-bounds: Illegal list reference: 31 
(length = 5) (sclist id = NIL)

SYNOPSIS

(defmethod get-nth (index (i sclist))

sclist/limits [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DATE

 January 12th 2019, Heidhausen

DESCRIPTION

 Get the lowest and highest values of the list

ARGUMENTS

 - an sclist object

RETURN VALUE

 two values: the minimum and maximum values in the list

SYNOPSIS

(defmethod limits ((scl sclist))

sclist/make-sclist [ Functions ]

[ Top ] [ sclist ] [ Functions ]

DESCRIPTION

 Create an sclist object with the specified list.

ARGUMENTS

 - A list of numbers or symbols.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :id. A symbol that will be the ID of the given sclist object. 
   Default = NIL.
 - :bounds-alert. T or NIL to indicate whether a warning should be issued
   when a request is given to set or get an out-of-bounds element (i.e. not
   enough elements in list). T = print warning. Default = NIL.
 - :copy. T or NIL to indicate whether the data in the list should be copied
   (any slippery-chicken class instances will be cloned), with subsequent
   modifications being applied to the copy. T = copy. Default = T.

RETURN VALUE

 Returns an sclist object. 

EXAMPLE

;; Create a simple object with just a list of numbers
(make-sclist '(1 2 3 4 5 6 7))

=> 
SCLIST: sclist-length: 7, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: (1 2 3 4 5 6 7)

;; Create the same object and assign an ID to it
(make-sclist '(1 2 3 4 5 6 7) :id 'number-list)

=> 
SCLIST: sclist-length: 7, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: NUMBER-LIST, tag: NIL, 
data: (1 2 3 4 5 6 7)

SYNOPSIS

(defun make-sclist (list &key (id nil) (bounds-alert t) (copy t))

sclist/max-items [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DATE

 September 21st 2018, Heidhausen

DESCRIPTION

 A destructive method to reduce the number of items in the list to a maximum
 of the 2nd argument. The remaining elements can be from either the beginning
 of the list, the middle, or the end. If the list has fewer then or the same
 number of elements as the 2nd argument, the list will remain unchanged.

ARGUMENTS

 - the sclist object
 - the number of elements the list should be reduced to (integer, >= 0)

OPTIONAL ARGUMENTS

 - a symbol ('start 'middle or 'end) to indicate which elements remain. See
   examples below. Default = 'start

RETURN VALUE

 the (potentially) modified sclist object (NB this method is destructive!)

EXAMPLE

(max-items (make-sclist '(1 2 3 4 5 6 7)) 3)
SCLIST: sclist-length: 3, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, 
                     this: NIL, 
                     next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: (1 2 3)
**************

(max-items (make-sclist '(1 2 3 4 5 6 7)) 3 'end)


SCLIST: sclist-length: 3, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, 
                     this: NIL, 
                     next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: (5 6 7)
**************

(max-items (make-sclist '(1 2 3 4 5 6 7)) 3 'middle)
SCLIST: sclist-length: 3, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, 
                     this: NIL, 
                     next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: (3 4 5)
**************

SYNOPSIS

(defmethod max-items ((scl sclist) max &optional (from 'start))

sclist/new-limits [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DATE

 January 12th 2019, Heidhausen

DESCRIPTION

 Rescale the numbers in the list to be within a new range.

ARGUMENTS

 - an sclist object

OPTIONAL ARGUMENTS

 - the new minimum value. Default = 0.0
 - the new maximum value. Default = 100.0

RETURN VALUE

 the new data list

EXAMPLE

(new-limits (make-sclist '(-1.4 5 6 2.3 7.3 -2.1)))
-->
(7.4468083 75.53192 86.17022 46.80851 100.0 0.0)

SYNOPSIS

(defmethod new-limits ((scl sclist) &optional (new-min 0.0) (new-max 100.0))

sclist/plot [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Create text and data files suitable for plotting the numbers in the data (or
 other) slot with gnuplot. The file name should be given without extension,
 as the method will create a .txt and a .data file, for the command and data
 files respectively. It is assumed that the data to be plotted is a list of
 numbers. An error will be triggered if not.

 The user must then call gnuplot in a terminal, in a manner such as "gnuplot
 sclist.txt; open sclist.ps". 

 The method will create files that draw data points connected by lines by
 default.

ARGUMENTS

 - An sclist object.
 - A string that is the directory path and base file name (without
   extension) of the files to create.

OPTIONAL ARGUMENTS

 - The slot to plot. By default this will be the data slot, but derived
   classes may want to plot a different list slot, e.g. the kernels slot of
   the popcorn class.
 - T or NIL to indicate whether to connect points by lines. T = draw
   lines. Default = T.

RETURN VALUE

 Returns the number of points plotted.

EXAMPLE

(let ((ppcn (make-popcorn '(0.01 0.02) :min-spike 3.0 :max-spike 5.0)))
  (fit-to-length ppcn 100)
  (plot ppcn "/tmp/ppcn" 'kernels))

then in a terminal:
gnuplot ppcn.txt

this will create the postscript file ppcn.ps

SYNOPSIS

(defmethod plot ((scl sclist) file &optional (slot 'data) (lines t))

sclist/sc-nthcdr [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Get the tail (rest) of a given sclist object beginning with and including
 the specified zero-based index number.

 NB: This method is destructive and replaces the contents of the given list
 with the sublist returned by the method.

ARGUMENTS

 - An index number.
 - An sclist object

RETURN VALUE

 Returns a list.

 Returns NIL if the specified index is greater (minus 1) than the number of
 items in the given list.

EXAMPLE

;; Create an sclist object and get the tail of the list starting at place
;; 4. The subset returned replaces the data of the original.
(let ((scl (make-sclist '(0 1 2 3 4 5 6 7 8 9))))
  (sc-nthcdr 4 scl)
  (data scl))

=> (4 5 6 7 8 9)

(let ((scl (make-sclist '(0 1 2 3 4 5 6 7 8 9))))
  (sc-nthcdr 14 scl))

=> NIL

SYNOPSIS

(defmethod sc-nthcdr (nth (scl sclist))

sclist/sc-subseq [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Return a subsequence from a given sclist based on starting and finishing
 indices. 

 NB: This method uses Common Lisp's subseq function and thus inherits its
 attributes, whereby the START argument indicates the zero-based index of
 the first list item to be returned and the FINISH argument indicates the
 zero-based index of the first list item after that NOT to be returned.

ARGUMENTS

 - An sclist object.
 - An integer indicating the zero-based index of the first list item to be
   returned. 
 - An integer indicating the zero-based index of the first list item after
   the START item to not be returned.

OPTIONAL ARGUMENTS

 - (fun #'error).  By default an error will be signalled if the requested
 subseq is out of bounds.  If you prefer, this could be a warning instead by
 passing #'warn, or nothing at all if NIL.

RETURN VALUE

 A list.

 An error is returned if the user attempts to apply the method with START
 and FINISH arguments that are beyond the bounds of the given sclist
 object. 

EXAMPLE

;; Returns a sublist from the given list. The START argument indicates the
;; zero-based index of the first item in the given list to be returned and the
;; FINISH argument indicates the zero-based index of the first item after that
;; to NOT be returned. 
(let ((scl (make-sclist '(1 2 3 4 5 6 7 8 9))))
  (sc-subseq scl 2 7))

=> (3 4 5 6 7)

;; Drops into the debugger with an error if one of the indexing arguments is
;; beyond the bounds of the given sclist object
(let ((scl (make-sclist '(1 2 3 4 5 6 7 8 9))))
  (sc-subseq scl 0 15))

=>
sclist::sc-subseq: Illegal indices for above list: 0 15 (length = 9)
   [Condition of type SIMPLE-ERROR]

(let ((scl (make-sclist '(1 2 3 4 5 6 7 8 9))))
  (sc-subseq scl 0 15 NIL))
=>
NIL

SYNOPSIS

(defmethod sc-subseq ((scl sclist) start finish &optional (fun #'error))

sclist/sclist-econs [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Add a single item to the end of a given sclist object.

 NB: This method destructively modifies the list.

 NB: This method adds any element specified as a single item. For combining
     two lists into one see sclist/combine.

 NB: Though related to Lisp's cons function, remember that the order of
    arguments here is the other way round i.e. element after list, not 
    before.

ARGUMENTS

 - An sclist object.
 - An item to add to the end of the given sclist object.

RETURN VALUE

 - The new value (list) of the given sclist object.

EXAMPLE

;; Add a single integer to the end of a list of integers
(let ((scl (make-sclist '(0 1 2 3 4))))
  (sclist-econs scl 5))

=> (0 1 2 3 4 5)

SYNOPSIS

(defmethod sclist-econs ((scl sclist) element)

sclist/sclist-remove-elements [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Remove a specified number of consecutive items from a given sclist object. 

 NB: This is a destructive method and replaces the data of the given sclist
 object with the newly created sublist.

ARGUMENTS

 - An sclist object.
 - The index integer within the given list with which to start (inclusive
   and zero-based).
 - An integer that is the number of items to remove.

RETURN VALUE

 Returns 

EXAMPLE

;;; Returns an sclist object.
(let ((scl (make-sclist '(0 1 2 3 4 5 6 7 8 9))))
  (sclist-remove-elements scl 3 4))

=> 
SCLIST: sclist-length: 6, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: NIL, tag: NIL, 
data: (0 1 2 7 8 9)

;; Drops into the debugger with an error if the given sclist object has fewer
;; items than specified for the START or HOW-MANY arguments
(let ((scl (make-sclist '(0 1 2 3 4 5 6 7 8 9))))
  (data (sclist-remove-elements scl 3 41)))

=> 
remove-elements: arguments 2 and 3 must be integers < the length of argument 1: 
3 41 10 
   [Condition of type SIMPLE-ERROR]

SYNOPSIS

(defmethod sclist-remove-elements ((scl sclist) start how-many)

sclist/set-nth [ Methods ]

[ Top ] [ sclist ] [ Methods ]

DESCRIPTION

 Set the nth element (zero-based) of a given sclist object.

 NB: This doesn't auto-grow the list.  

ARGUMENTS

 - An index integer.
 - An sclist object.

RETURN VALUE

 Returns the item added if successful.

 Returns NIL and prints a warning if the specified index number is greater
 than the number of items in the list (minus 1)

EXAMPLE

;; Returns the item added
(let ((scl (make-sclist '(cat dog cow pig sheep))))
  (set-nth 3 'horse scl))

=> HORSE

;; Access the DATA slot to see the change
(let ((scl (make-sclist '(cat dog cow pig sheep))))
  (set-nth 3 'horse scl)
  (data scl))

=> (CAT DOG COW HORSE SHEEP)

;; Returns NIL and prints a warning if the index number is beyond the bounds of
;; the list
(let ((scl (make-sclist '(cat dog cow pig sheep))))
  (set-nth 31 'horse scl))

=> NIL
WARNING: sclist::sclist-check-bounds: Illegal list reference: 31 
(length = 5) (sclist id = NIL)

SYNOPSIS

(defmethod set-nth (index new-element (i sclist))