./../../src/circular-sclist.lsp

## circular-sclist/at-start [ Methods ]

[ Top ] [ circular-sclist ] [ Methods ]

FUNCTION

     Determines whether the pointer for the given circular-sclist object is at
     the head of its list.

ARGUMENTS

     - A circular-sclist object.

RETURN VALUE

EXAMPLE

    ;; At creation the pointer is located at the start of the list
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (at-start cscl))

    => T

    ;; Retrieve a number of the items using get-next, then determine whether the
    ;; pointer is located at the start of the list
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (loop repeat 7 do (get-next cscl))
      (at-start cscl))

    => NIL

SYNOPSIS

    (defmethod at-start ((cscl circular-sclist))

## circular-sclist/get-last [ Methods ]

[ Top ] [ circular-sclist ] [ Methods ]

FUNCTION

     Return the the most recent item retrieved in a circular-sclist object.

ARGUMENTS

     - A circular-sclist object.

RETURN VALUE

     An item from the given circular-sclist object.

EXAMPLE

    ;; Retrieves the final item in the list at creation
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (get-last cscl))

    => 4

    ;; Get and print a number of items from the list using get-next, then return
    ;; the most recent item retrieved using get-last
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (loop repeat 7 do (print (get-next cscl)))
      (get-last cscl))

    => 1

SYNOPSIS

    (defmethod get-last ((cscl circular-sclist))

## circular-sclist/get-next [ Methods ]

[ Top ] [ circular-sclist ] [ Methods ]

FUNCTION

     Get the next item in a given circular-sclist object. The class
     automatically keeps track of the last item retrieved. If the final item of
     the given circular-sclist object was the last item retrieved, the method
     begins again at the beginning of the list.

ARGUMENTS

     - A circular-sclist object.

RETURN VALUE

     An item from the given circular-sclist object.

EXAMPLE

    ;; Repeatedly calling get-next retrieves each subsequent item from the
    ;; given circular-sclist object. When the list has been exhausted, retrieval
    ;; begins again from the head of the list.
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (loop repeat 10
         do (print (get-next cscl))))

    =>
    0
    1
    2
    3
    4
    0
    1
    2
    3
    4

SYNOPSIS

    (defmethod get-next ((cscl circular-sclist))

## circular-sclist/make-cscl [ Functions ]

[ Top ] [ circular-sclist ] [ Functions ]

FUNCTION

     Create a circular-sclist object from a specified list of items. The items
     themselves may also be lists.

ARGUMENTS

     - A list.

OPTIONAL ARGUMENTS

     - keyword argument :id. A symbol that will be used as the ID for the
       created circular-sclist object. Default = NIL.
     - keyword argument :bounds-alert. T or NIL to indicate whether or not to
       print a warning if when an attempt is made to access the object using an
       out-of-bounds index number (i.e., not enough elements in the list).
       T = print a warning. Default = T.
     - keyword argument :copy. T or NIL to indicate whether the given data 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

     A circular-sclist object.

EXAMPLE

    ;; Returns a circular-sclist object with ID of NIL, bounds-alert=T and copy=T
    ;; by default
    (make-cscl '(1 2 3 4))

    =>
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 4, 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)

    ;; Can be created using nested lists
    (let ((cscl (make-cscl '((1 (4 5 6))
                             (2 (7 8 9))
                             (3 (10 11 12))))))
      (data cscl))

    => ((1 (4 5 6)) (2 (7 8 9)) (3 (10 11 12)))

    ;; Setting the ID
    (make-cscl '(1 2 3 4) :id 'test-cscl)

    =>
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 4, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: TEST-CSCL, tag: NIL,
    data: (1 2 3 4)

    ;; By default, attempts to access the object with an out-of-bounds index result
    ;; in a warning being printed
    (let ((cscl (make-cscl '(1 2 3 4))))
      (get-nth 11 cscl))

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

    ;; This can be suppressed by creating the object with :bounds-alert set to NIL
    (let ((cscl (make-cscl '(1 2 3 4) :bounds-alert nil)))
      (get-nth 11 cscl))

    => NIL

SYNOPSIS

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

## circular-sclist/reset [ Methods ]

[ Top ] [ circular-sclist ] [ Methods ]

FUNCTION

     Reset the pointer of a given circular-sclist object. The pointer is reset
     to 0 by default, but the desired index may be specified using the optional
     argument.

     NB: An immediately subsequent get-next call will retrieve the item at the
         index to which the pointer is reset. An immediately subsequent
         get-last call will retrieve the item at the index one-less
         than the value to which the pointer is set.

ARGUMENTS

     - A circular-sclist object.

OPTIONAL ARGUMENTS

     - An index integer to which the pointer for the given circular-sclist
       object should be reset.

RETURN VALUE

     Returns T.

EXAMPLE

    ;; Resets to 0 by default. Here: Get a number of items using get-next, reset
    ;; the pointer, and apply get-next again.
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (loop repeat 8 do (print (get-next cscl)))
      (reset cscl)
      (get-next cscl))

    => 0

    ;; Reset to a specified index
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (loop repeat 8 do (print (get-next cscl)))
      (reset cscl 3)
      (get-next cscl))

    => 3

    ;; By default, get-last will then retrieve the item at index one less than the
    ;; reset value
    (let ((cscl (make-cscl '(0 1 2 3 4))))
      (loop repeat 8 do (print (get-next cscl)))
      (reset cscl 3)
      (get-last cscl))

    => 2

SYNOPSIS

    (defmethod reset ((cscl circular-sclist) &optional where)

## sclist/circular-sclist [ Classes ]

[ Top ] [ sclist ] [ Classes ]

NAME

     circular-sclist

     File:             circular-sclist.lsp

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

     Version:          1.0.0-beta1

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the circular-sclist class which offers
                       the use of a function to cycle through the values in the
                       sclist, starting at the beginning again once we've
                       reached the end.

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

     Creation date:    February 19th 2001

     $$ Last modified: 21:25:56 Mon May 14 2012 BST

     SVN ID: $Id: circular-sclist.lsp 1764 2012-05-17 11:49:59Z medward2 $