cappedarray
===========


## Basic usage

```js
var cappedArray = require('cappedarray')

// Create array with a length cap of 3
var log = cappedArray(3)  // []

// log.lengthCap === 3


// Add some items
log.push(1)               // [1]         
log.push(2)               // [1, 2]       
log.push(3)               // [1, 2, 3]


// Add more items than the length cap
log.push(4)               // [2, 3, 4] - Too many items, The 1 is pushed off the front
log.push(5)               // [3, 4, 5]
log.unshift(6)            // [6, 3, 4] - The 5 is unshifted off the back

// Add a lot more than the cap length
for (var i = 0; i < 50; i++) {
	log.push(i)
}

// Still 3 items
console.log(log.length)
> 3

console.log(log)
> [47, 48, 49]
```

## Installation

```bash
$ npm install cappedarray
```


## How it works
The capped array is just a normal array with the `push` and `unshift` functions overridden and an extra `lengthCap` property.
The functions and lengthCap are set to enumerable `false` so they do not show up in forEach loops, Object.keys, etc...
```js
var recentItems = cappedArray(5)

recentItems.push('foo')
recentItems.push('bar')

var util = require('util')
util.isArray(recentItems)   // true
Array.isArray(recentItems)  // true

Object.keys(recentItems)    // ['0', '1']
JSON.stringify(recentItems) // '["foo","bar"]'
```

## Further Examples

#### Multiple arguments
```js
// Create array with a length cap of 5
var log = cappedArray(5)                    // []

// Multiple arguments to push and unshift work as expected.
log.unshift('a', 'b', 'c', 'd', 'e', 'f')   // ['a', 'b', 'c', 'd', 'e'] - Too long, 'f' has already popped off the end.
                                            // If this was a 'push' the 'f' would have stayed and the 'a' would have gone.

log.unshift('h')                            // ['h', 'a', 'b', 'c', 'd']
log.unshift.apply(log, ['i', 'j', 'k'])     // ['i', 'j', 'k', 'h', 'a']
log.push('l', 'm')                          // ['k', 'h', 'a', 'l', 'm']
```


#### The length cap can be changed on the fly.

```js
// Create array with a length cap of 5
var recentItems = cappedArray(5)

recentItems.push(1, 2, 3, 4, 5, 6, 7)   // [3, 4, 5, 6, 7]

// Need to keep more recent items
recentItems.lengthCap = 8               // [3, 4, 5, 6, 7] Still only 5 items

recentItems.push(8, 9, 10, 11)          // [4, 5, 6, 7, 8, 9, 10, 11]

```
When changing the length cap to a lower value than the existing item count, the extra items will **not** be automatically removed. It is unknown whether the first or last items should be removed until `push` or `unshift` is called afterward. 

```js

// I've changed my mind. There's too many items now, lower the cap.
recentItems.lengthCap = 6              // [4, 5, 6, 7, 8, 9, 10, 11]

// More items than the lengthCap?
console.log(recentItems.length)
> 8
console.log(recentItems.lengthCap)
> 6
```

Passing no arguments to either `push` or `unshift` will reduce the array to the capped length.
```js
// I want to keep the end of the array.
recentItems.push()                     // [6, 7, 8, 9, 10, 11]

// That has sorted it!
console.log(recentItems.length)
> 6
console.log(recentItems.lengthCap)
> 6

```


## Capping existing Arrays
```js
var cap = require('cappedarray').cap

var messages = [{msg: 'First!'}, {msg: 'Second'}, {msg: 'Third'}]

// Cap the array to 5 items
cap(messages, 5)

messages.push({msg: 'Forth'}, {msg: 'Fith'}, {msg: 'Sixth'})

console.log(log)
> [ { msg: 'Second' },
  { msg: 'Third' },
  { msg: 'Forth' },
  { msg: 'Fith' },
  { msg: 'Sixth' } ]
```

If the second argument is missing the cap is set to the length of the array or the lengthCap property if it exists.

```js
var numerosEnFrancais = cap(['un', 'deux', 'trois'])

// Both the cap and length are the same
console.log(numerosEnFrancais.length + ' === ' numerosEnFrancais.lengthCap)
> 3 === 3

// This can be used to loop through an array repeatedly
numerosEnFrancais.push(numerosEnFrancais[0])  // ['deux', 'trois', 'un']
numerosEnFrancais.push(numerosEnFrancais[0])  // ['trois', 'un', 'deux']
numerosEnFrancais.push(numerosEnFrancais[0])  // ['un', 'deux', 'trois']



var top5 = ['High Fidelity']

// This...
top5.lengthCap = 5
cap(top5)  // Uses the existing lengthCap property for the length cap

// ...is the same as
cap(top5, 5)
```



Like changing the lengthCap above, capping an existing array with more items than the length cap will **not** automatically remove the extra items. Use `push` or `unshift` with no arguments to reduce the array to the capped length.

```js

var alphabet = ['a', 'b', 'c', 'd', etc..., 'x', 'y', 'z']
console.log(alphabet.length)
> 26

// Cap it to 13 items...
cap(alphabet, 13)

// ...but it still has 26 items.
console.log(alphabet.length)
> 26
console.log(alphabet.lengthCap)
> 13

// removes extra items from the front.
cap.push()        

console.log(alphabet.length)
> 13
console.log(alphabet)
> ['n', 'o', 'p', 'q', 'r', 's', etc..., 'x', 'y', 'z']


// Lets try that again with unshift
var alphabet = ['a', 'b', 'c', 'd', etc..., 'x', 'y', 'z']

// cap returns the array so we can do this. Unshift removes extra items from the back.
cap(alphabet, 13).unshift()

console.log(alphabet.length)
> 13
console.log(alphabet)
> ['a', 'b', 'c', 'd', 'e', 'f', etc..., 'k', 'l', 'm']

``` 

## Uncap

Use uncap to turn the array back to normal.

```js
var cap   = require('cappedarray').cap
var uncap = require('cappedarray').uncap

var cycleNumbers = cap([1, 2, 3, 4, 5]) // Sets lengthCap to length: 5

cycleNumbers.push(cycleNumbers[0])      // [2, 3, 4, 5, 1]
cycleNumbers.push(cycleNumbers[0])      // [3, 4, 5, 1, 2]
cycleNumbers.push(cycleNumbers[0])      // [4, 5, 1, 2, 3]

uncap(cycleNumbers)

// The cycle is broken
cycleNumbers.push(cycleNumbers[0])      // [4, 5, 1, 2, 3, 4]
cycleNumbers.push(cycleNumbers[0])      // [4, 5, 1, 2, 3, 4, 4]
cycleNumbers.push(cycleNumbers[0])      // [4, 5, 1, 2, 3, 4, 4, 4]

```

## Clone

Copy the values into a new capped array with the same lengthCap

```js
var cap   = require('cappedarray').cap
var clone = require('cappedarray').clone

var capped1 = cap([1, 2, 3])
var capped2 = clone(capped1)

capped2.push(4)

console.log(capped1, capped2)
> [1, 2, 3] [2, 3, 4]

// Clone is just a wrapper for
cap(capped.slice(), capped.lengthCap)
```


## Gotchas

* Behavior maybe unexpected if a capped array is passed to a library for modification.
* lengthCap must be a non negative integer. Other values will throw 'Invalid array lengthCap'. This mimics the behavior of assigning array.length.
* `push` and `unshift` return the length of the array, **not** the array, in line with the existing behavior.
```js
// array1 is not an array
var array1 = cap([1, 2, 3, 4, 5, 6], 3).push()
console.log(array1)
> 3

// This works
var array2 = cap([1, 2, 3, 4, 5, 6], 3)
array2.push()
console.log(array2)
> [4, 5, 6]

// or this
var array3
( array3 = cap([1, 2, 3, 4, 5, 6], 3) ).push()
console.log(array3)
> [4, 5, 6]
```

* Arrays can be made longer than lengthCap by using splice, assigning to a numbered key or using the Array prototype functions with `call` or `apply`.
```js
var array1 = cap([1, 2, 3], 3)       // [1, 2, 3]                length = 3, lengthCap = 3
array1.splice(1, 0, 1.1, 1.2, 1.3)   // [1, 1.1, 1.2, 1.3, 2, 3] length = 6, lengthCap = 3


var array2 = cap([1, 2, 3], 3)       // [1, 2, 3]    length = 3, lengthCap = 3
array2[3] = 4                        // [1, 2, 3, 4] length = 4, lengthCap = 3


var array3 = cap([1, 2, 3], 3)       // [1, 2, 3]          length = 3, lengthCap = 3
Array.prototype.push.call(array3, 4) // [1, 2, 3, 4]       length = 4, lengthCap = 3
[].push.apply(array3, [5, 6])        // [1, 2, 3, 4, 5, 6] length = 6, lengthCap = 3
```