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.0-beta3 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: 21:26:09 Mon May 14 2012 BST SVN ID: $Id: sclist.lsp 2531 2012-07-03 19:50:40Z medward2 $
sclist/combine [ Methods ]
[ Top ] [ sclist ] [ Methods ]
DESCRIPTION
Combine the contents of two given sclist objects into one list.
ARGUMENTS
- A first sclist object. - A second sclist ojbect.
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-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/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/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 teh 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))