# Class CircularList<T>

A circular list of values, where the next value added overwrites the oldest value. The list is filled in until full, then it overwrites earlier entries in the list.

## How CircularList Works

This section describes how the class works internally. This information is not needed for using this class.

### Index Numbers, Pointers, and Overflow

Each value added has an index number which starts at zero and increases by one with each new value. The index number keeps increasing even when the list has 'wrapped around' and starts overwriting earlier entries.

Internally we use the term 'pointer' to mean a number in the range from 0 to the list capacity which 'points at' a particular list entry. The pointer and index are related and we can convert between them with the functions pointerToIndex and indexToPointer. The relation between pointer and index is:

``````pointer = index mod capacity
index = pointer + cycles*capacity      (when pointer < nextPtr)
= pointer + (cycles-1)*capacity  (when pointer >= nextPtr)
``````

The index number can have a maximum value of 2^53. When the index number exceeds this maximum, an exception is thrown by methods that calculate the current index number. Because index numbers are visible outside of this class we cannot just reset the index number.

This 2^53 maximum value should be enough capacity for most uses of CircularList. If you add 1000 points per second, it would take 37 million years to run out of capacity.

It might be possible to add a method that the caller can use to reset the index numbers to start at or near zero again, preserving the data in the CircularList and changing the index number associated with each value. Or the caller can simply make a new CircularList when catching the exception.

### Example Scenario

We write new entries into the arrays `memX` and `memY` until they fill. Then we wrap around and start writing to the beginning again.

``````nextPtr always points to the next location to write to.
If size > capacity, then we have entries at 0,1,2,...,size-1
If size = capacity, then the order of entries is:
nextPtr, nextPtr+1, ..., capacity-1, 0, 1, 2, ..., nextPtr-1

Example: Suppose capacity = 10. The list will fill in as shown below.
The numbers are the index number returned by getIndex().
The caret ^ indicates nextPtr -- the next slot to be written to.

cycles
.  .  .  .  .  .  .  .  .  .      0
^
0  .  .  .  .  .  .  .  .  .      0
^
0  1  .  .  .  .  .  .  .  .      0
^
(write of 2 thru 7 omitted)
0  1  2  3  4  5  6  7  8  .      0
^
0  1  2  3  4  5  6  7  8  9      1
^
10 1  2  3  4  5  6  7  8  9      1
^
10 11 2  3  4  5  6  7  8  9      1
^
(write of 12 thru 16 omitted)
10 11 12 13 14 15 16 17 8  9      1
^
10 11 12 13 14 15 16 17 18 9      1
^
10 11 12 13 14 15 16 17 18 19     2
^
20 11 12 13 14 15 16 17 18 19     2
^
20 21 12 13 14 15 16 17 18 19     2
^
``````

## Constructors

#### Parameters

• ##### `Optional`capacity: number

the capacity of the list; default is 3000

## Properties

capacity_: number = 3000

capacity of the list, maximum size

cycles_: number = 0

number of times the list has been overwritten

lastPtr_: number = -1

pointer to newest entry: index of last entry written to list or -1 if never written.

lastValue_: null | T = null

last value written to memory list

nextPtr_: number = 0

pointer to next entry in list; oldest entry if list has wrapped around.

size_: number = 0

number of items now in memory list <= capacity

values_: T[] = ...

values stored

## Methods

• Causes the MAX_INDEX_ERROR exception to occur in near future by setting the number of cycles to be near the maximum allowed, for testing.

#### Returns void

• Returns the index of the ending value in this HistoryList. The ending value is the newest value in this HistoryList.

#### Returns number

the index of the ending value in this HistoryList, or –1 if nothing has been stored

#### Throws

when the index number exceeds the maximum representable integer

• Returns the last value stored in this HistoryList, or `null` if this HistoryList is empty.

#### Returns null | T

the last value stored in this HistoryList, or `null` if this HistoryList is empty

• Returns a HistoryIterator which begins at the given index in this HistoryList.

#### Parameters

• ##### `Optional`index: number

the index to start the iterator at; if undefined or –1, then starts at beginning of this HistoryList

#### Returns HistoryIterator<T>

a HistoryIterator which begins at the given index in this HistoryList.

• Returns the number of points currently stored in this HistoryList (which is less than or equal to the capacity of this HistoryList).

#### Returns number

the number of points currently stored in this HistoryList

• Returns the index of the starting value in this HistoryList. The starting value is the oldest value in this HistoryList.

#### Returns number

the index of the starting value in this HistoryList

#### Throws

when the index number exceeds the maximum representable integer

• Returns the value stored at the given index in this HistoryList.

#### Parameters

• ##### index: number

the index of the value of interest

#### Returns T

the value stored at the given index

#### Throws

if the index is out of range

• Returns the value stored at the given pointer in this HistoryList.

#### Parameters

• ##### pointer: number

the pointer to the value of interest

#### Returns T

the value stored at the given pointer

#### Throws

if the pointer is out of range

• Converts an index (which includes cycles) into a pointer. Pointer and index are the same until the list fills and 'wraps around'.

#### Parameters

• ##### index: number

the index number, which can be larger than the size of the list

#### Returns number

the pointer to the corresponding point in the list

• Converts a pointer into the list to an index number that includes cycles. Pointer and index are the same until the list fills and 'wraps around'.

#### Parameters

• ##### pointer: number

an index from 0 to size

#### Returns number

the index number of this point including cycles

#### Throws

when the index number exceeds the maximum representable integer

• Clears out the memory of this HistoryList, so that there are no values stored. The capacity of this HistoryList is unchanged.

#### Returns void

• Stores the given value into this HistoryList.

#### Parameters

• ##### value: T

the value to store

#### Returns number

index within HistoryList where the value was stored

#### Throws

when the index number exceeds the maximum representable integer

Generated using TypeDoc