circular-sclist.lsp

circular-sclist/at-start [ Methods ]

DESCRIPTION

 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-current [ Methods ]

[ Top ] [ circular-sclist ] [ Methods ]

DESCRIPTION

 Return the current list element without incrementing the current slot.

ARGUMENTS

 - The circular-sclist object

RETURN VALUE

 The current list element, which can be of any type.

EXAMPLE

(let ((cscl (make-cscl '(0 1 2 3 4))))
  (loop for i below 10 do
     (print (if (oddp i) (get-next cscl) (get-current cscl)))))
(let ((cscl (make-cscl '(0 1 2 3 4))))
  (loop for i below 10 
     collect (if (oddp i) (get-next cscl) (get-current cscl))))
=>
(0 0 1 1 2 2 3 3 4 4)

SYNOPSIS

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

circular-sclist/get-last [ Methods ]

[ Top ] [ circular-sclist ] [ Methods ]

DESCRIPTION

 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 ]

DESCRIPTION

 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 collect (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 ]

DESCRIPTION

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

ARGUMENTS

 - A list.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :id. A symbol that will be used as the ID for the created circular-sclist
   object. Default = NIL.
 - :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.
 - :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 ]

DESCRIPTION

 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 (warn t))

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.1.0

 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:  11:26:03 Sat Sep 26 2020 CEST

 SVN ID: $Id$