./../../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.10

     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:  16:25:20 Sat May 18 2019 CEST

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