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-beta2

 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 1982 2012-05-24 15:35:54Z 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))