./../../src/sclist.lsp

## 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-beta1

     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 1764 2012-05-17 11:49:59Z medward2 $

## sclist/combine [ Methods ]

[ Top ] [ sclist ] [ Methods ]

FUNCTION

     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 ]

FUNCTION

     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 ]

FUNCTION

     Create an sclist object with the specified list.

ARGUMENTS

     - A list of numbers or symbols.

OPTIONAL ARGUMENTS

     - keyword argument :id. A symbol that will be the ID of the given sclist
       object. Default = NIL.
     - keyword argument :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.
     - keyword argument :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 ]

FUNCTION

     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 ]

FUNCTION

     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 ]

FUNCTION

     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 ]

FUNCTION

     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 ]

FUNCTION

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