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

[ Top ] [ circular-sclist ] [ Methods ]

DESCRIPTION

``` Determines whether the pointer for the given circular-sclist object is at
```

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