Usage

`javascript
var circularBuffer = require( '@stdlib/utils-circular-buffer' );
`

#### circularBuffer( buffer )

Returns a new circular buffer instance.

`javascript
var buf = circularBuffer( 3 );
// returns
`

The buffer argument may either be a integer which specifies the buffer size or an array-like object to use as the underlying buffer.

`javascript
var Float64Array = require( '@stdlib/array-float64' );

// Use a typed array as the underlying buffer:
var buf = circularBuffer( new Float64Array( 3 ) );
// returns
`

##### circularBuffer.prototype.clear()

Clears a buffer.

`javascript
var buf = circularBuffer( 3 );
// returns

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );

// Get the number of elements currently in the buffer:
var n = buf.count;
// returns 3

// Clear all buffer items:
buf.clear();

// Get the number of elements in the buffer:
n = buf.count;
// returns 0
`

##### circularBuffer.prototype.count

Read-only property which returns the number of elements currently in the buffer.

`javascript
var buf = circularBuffer( 3 );
// returns

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );

// Determine how many elements are in the buffer:
var n = buf.count;
// returns 2
`

##### circularBuffer.prototype.full

Read-only property which returns a boolean indicating if a buffer is full.

`javascript
var buf = circularBuffer( 3 );
// returns

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );

// Determine if the buffer is full:
var bool = buf.full;
// returns false

// Add another value to the buffer:
buf.push( 'beep' );

// Determine if the buffer is full:
bool = buf.full;
// returns true
`

##### circularBuffer.prototype.iterator( \[niters] )

Returns an iterator for iterating over a buffer. If an environment supports Symbol.iterator, the returned iterator is iterable.

`javascript
var buf = circularBuffer( 2 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Create an iterator:
var it = buf.iterator();

// Iterate over the buffer...
var v = it.next().value;
// returns 'beep'

v = it.next().value;
// returns 'boop'

v = it.next().value;
// returns 'beep'

v = it.next().value;
// returns 'boop'

v = it.next().value;
// returns 'beep'
`

By default, provided a buffer is full, the method returns an infinite iterator. To limit the number of iterations, provide an niters argument.

`javascript
var buf = circularBuffer( 2 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Create an iterator:
var it = buf.iterator( buf.length );

// Iterate over the buffer...
var v = it.next().value;
// returns 'beep'

v = it.next().value;
// returns 'boop'

var bool = it.next().done;
// returns true
`

A returned iterator does not iterate over partially full circular buffers.

`javascript
var buf = circularBuffer( 5 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );

// Create an iterator:
var it = buf.iterator();

// Determine if the buffer is full:
var bool = buf.full;
// returns false

// Iterate over the buffer...
bool = it.next().done;
// returns true
`

If iterating over a partially full circular buffer is necessary, use buf.toArray() and iterate over the returned array.

##### circularBuffer.prototype.length

Read-only property returning the buffer length (i.e., capacity).

`javascript
var buf = circularBuffer( [ 0, 0, 0 ] );

// Get the buffer length:
var len = buf.length;
// returns 3
`

##### circularBuffer.prototype.push( value )

Adds a value to the buffer.

`javascript
var buf = circularBuffer( 3 );

// Fill the buffer...
var v = buf.push( 'foo' );
// returns undefined

v = buf.push( 'bar' );
// returns undefined

v = buf.push( 'beep' );
// returns undefined

// Now that the buffer is full, each push will cause a value to be removed:
v = buf.push( 'boop' );
// returns 'foo'
`

When a circular buffer is empty or partially full, this method returns undefined. Once a circular buffer is full, the method returns removed values.

##### circularBuffer.prototype.toArray()

Returns an array of buffer values.

`javascript
var buf = circularBuffer( 3 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Get an array of buffer values:
var vals = buf.toArray();
// returns [ 'bar', 'beep', 'boop' ]
`

##### circularBuffer.prototype.toJSON()

Serializes a circular buffer as JSON.

`javascript
var buf = circularBuffer( 3 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Serialize to JSON:
var o = buf.toJSON();
// returns { 'type': 'circular-buffer', 'length': 3, 'data': [ 'bar', 'beep', 'boop' ] }
`

Note: JSON.stringify() implicitly calls this method when stringifying a circular buffer instance.