https://github.com/mikolalysenko/guarded-array

Bounds checked array
https://github.com/mikolalysenko/guarded-array

Last synced: about 2 months ago
JSON representation

Bounds checked array

• Host: GitHub
• URL: https://github.com/mikolalysenko/guarded-array
• Owner: mikolalysenko
• License: mit
• Created: 2014-12-18T18:15:31.000Z (about 10 years ago)
• Default Branch: master
• Last Pushed: 2014-12-18T18:16:17.000Z (about 10 years ago)
• Last Synced: 2024-10-19T00:19:18.390Z (2 months ago)
• Language: JavaScript
• Size: 113 KB
• Stars: 2
• Watchers: 3
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
guarded-array

=============

A slow bounds checked array to help with debugging.

# Example

```javascript

var guard = require('guarded-array')

//First create any old array

var array = [ 0, 1, 2, 3, 4, 5 ]

//Then we protect it using guard!

var guardedArray = guard(array)

//The guarded array works just like a normal array:

console.log(guardedArray.length, guardedArray.slice())

//Accessing elements in the middle of array is ok

guardedArray[3] = 100

//Writes propagate to underlying array

console.log(array)

//But reading out of bounds throws an exception

try {

  console.log(guardedArray[-1])

} catch(e) {

  console.log(e)

}

try {

  console.log(guardedArray[10])

} catch(e) {

  console.log(e)

}

//You can also create guarded arrays for subarrays of arrays

var subGuard = guard(array, 1, 3)

//Now you can only access elements in the range 1-3 of array safely

console.log(subGuard[1], subGuard[2])

//Writing/reading out of bounds throws an exception

console.log(subGuard[3])

//Use this module in your unit tests to help track down

//pesky off-by-one errors

```

#### Output:

```

6 [ 0, 1, 2, 3, 4, 5 ]

[ 0, 1, 2, 100, 4, 5 ]

[Error: read out of bounds: -1]

[Error: read out of bounds: 10]

1 2

Error: read out of bounds: 3

    at Array.get [as 3] (/Users/mikolalysenko/GitHub/guarded-array/guarded-array.js:39:15)

    at Object. (/Users/mikolalysenko/GitHub/guarded-array/example/example.js:38:21)

    at Module._compile (module.js:456:26)

    at Object.Module._extensions..js (module.js:474:10)

    at Module.load (module.js:356:32)

    at Function.Module._load (module.js:312:12)

    at Function.Module.runMain (module.js:497:10)

    at startup (node.js:119:16)

    at node.js:902:3

```

# Install

```sh

npm install guarded-array

```

# API

## `require('guarded-array')(array[,lo, hi])`

Creates a guarded view of `array`.  Attempting to access outside of the bounds `[lo,hi)` or changing the length of the array will result in an exception.

* `array` is an ordinary JavaScript array

* `lo` is an optional lower bound (default `0`)

* `hi` is an optional upper bound (default `array.length`)

**Returns** A guarded view of the array object.  Writes to the guarded array propagate down to the underlying array object.  Out of bounds access will trigger an exception.

#### Notes/Warnings

`Array.isArray` doesn't work on `guarded-array`.  I'm open to suggestions on how to get this to work.

# Credits

(c) 2014 Mikola Lysenko. MIT License