README
Bit Array - A Javascript Data Type extension
A BitArray works like a regular Array object. In fact, anything you can do with Arrays
index.Of lastIndexOf slice splice join reverse filter sort etc
you can do with a BitArray instance. Keep in mind that the elements will always be a numeric 0 or a 1.
As it's still impossible to inherit from the Array object, to take advantage of the bracket syntax i.e. customArray[index], as explained in the article by perfectionkills:
Subclassing an array in Javascript has never been a trivial task. At least for a certain meaning of “subclassing an array”. Curiously, new edition of the language — ECMAScript 5 — still does not allow to fully subclass an array.
Direct property injection is used, as it is the only reliable choice.
Intallation
Browser
<script src="pathto/bitarray.js"></script>
Usage
All ES5 Array methods are supported
var buffer = new BitArray(1,1,0,0)
console.log(buffer[0], buffer[1], buffer[2], buffer[3]) // 1 1 0 0
buffer.push(1, 0, 1, 0, 1)
console.log(buffer) // [1,1,0,0,1,0,1,0,1]
buffer.push(1, 1, 1, 1, 1)
console.log(buffer) // [1,1,0,0,1,0,1,0,1,1,1,1,1,1]
buffer.length = 0 // []
buffer.push('A') // 65. characters are stored in 16 bits
console.log(buffer) // [0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,1]
buffer.pop()
buffer.pop()
console.log(buffer) // [0,0,0,0,0,0,0,0,0,1,0,0,0,0]
buffer.unshift(1,1,1)
console.log(buffer) // [1,1,1,0,0,0,0,0,0,0,0,0,1,0,0,0,0]
// Lets go nuts
buffer.length = 0 // []
buffer.push(1,0,1,1,1, 'Hello World', 255, 0xFFFF, 0, true, false, 1, 0, 1, 0)
console.log(buffer) // See **Accepted Types**
// [1,0,1,1,1,0,0,0,0,0,0,0,0,0,1,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,1,1,
// 0,0,1,0,1,0,0,0,0,0,0,0,0,0,1,1,0,1,1,0,0,0,0,0,0,0,0,0,0,0,1,1,
// 0,1,1,0,0,0,0,0,0,0,0,0,0,0,1,1,0,1,1,1,1,0,0,0,0,0,0,0,0,0,0,1,
// 0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,1,0,1,1,1,0,0,0,0,0,0,0,0,0,1,1,
// 0,1,1,1,1,0,0,0,0,0,0,0,0,0,1,1,1,0,0,1,0,0,0,0,0,0,0,0,0,0,1,1,
// 0,1,1,0,0,0,0,0,0,0,0,0,0,0,1,1,0,0,1,0,0,0,1,0,1,0,1,0]
NOTE Javasciript uses 16 bits for a single character from the most common characters defined by the UCS-2 standard a subset of UTF-16. All characters are treated as 16 bits. reference
Accepted Types
The Array equivalant methods defined by the BitArray, will resolve values in the following order:
typeof value === 'string'
Treat each character as its 16 bit character code
typeof value === 'boolean'
Treat each value as either a 1 or a 0
typeof value === 'number'
If number is a 0 or 1, it is treated as a single bit.
else
The number is treated as a ~64 bit number...
almost 64bits, the number has to be less than 0xFFFFFFFFFFFFFBFF
(18446744073709550000. instead of 18446744073709552000.)
When in doubt, be specific:
NOTICE Specifiers have not been implemented yet, they are in the kitchen, on their way out. Specifiers will become a postfix to common Array-equivalent methods, this is simply to enforce a particular type of input, since a Number, for example can be a single bit or 64 bits depending on it's value, this may cause conflift, hence the specifiers.
buffer.pushBit(1) // 1 bit
buffer.pushBit(1, 0, 1) // 3 bits
buffer.pushChar('A') // 16 bits
buffer.pushString('Awesome') // (16 * `Awesome`.length) bits
buffer.pushNumber(1) // 64 bits
buffer.pushUInt32(0xFFFF44) // 32 bits
All The Array equivalant methods will have more specific counterparts where the type is explicit, e.g.
unshiftBit popBit spliceBit joinNumber forEachBit sliceNumber join32UInt indexOfString sliceBit spliceString joinChar findBit
Everything is treated as bits internally, so when using lastIndexOfString for example, the string being searched for will be converted to binary, and a binary search will be done. This is true for all iterating methods: indexOfChar forEachString findChar etc
The idea is to iterate the internal bits in a BitArray while treating them as bytes, words and even strings, depending on the postfix applied.
Specific Methods
Use any postfix on a method if you want to work on the internal bits as specific bit structure
BitArray.<method>[<postfix>]()
| postfix | bit size | alias | accepted types |
|---|---|---|---|
| Bit | 1 | Bits | number |
| Char | 16 | Character | string (only first character) |
| String | length * 16 | Str | string |
| Date | 64 | instanceof Date |
|
| Number | 64 | 64Uint Qword QWORD | number (0 - 18446744073709550000) |
| UInt32 | 32 | Dword DWORD | number (0 - 4294967295) |
| UInt16 | 16 | Word WORD | number (0 - 65535) |
| UInt8 | 8 | Byte BYTE | number (0 - 255) |
| Array | length * 1 | instanceof Array each element is a bit |
|
| BitArray | length * 1 | BitArray.isBitArray() |
Note When only a number is an accepted type, it can be a Numeric string as well as a boolean, as it will be casted into a number. When using a specifier, if the argument is not a supported type, it will throw
Static Methods
BitArray has the following static methods that allow you to create a new BitArray from different types:
Boolean BitArray.isBitArray(Object) Test if object is a BitArray
BitArray BitArray.fromNumber(Number) Convert a number into a 64 bit BitArray
BitArray BitArray.fromString(String) Convert a string into a BitArray
BitArray BitArray.fromArray(Array) Convert an array of 0s and 1s into a BitArray
BitArray BitArray.fromMixedArray(Array) Convert an array of mixed element types (and bit sizes), into a BitArray
BitArray BitArray.fromDate(Date) Convert a date into a 64 bit BitArray
BitArray BitArray.fromBoolean(Boolean) Convert a boolean into a 1 bit BitArray
Documentation
Documentation is generated with the very awesome yuidoc
make sure it's installed:
npm yuidoc -g
And run the following command in the root folder to create a folder called documentation
yuidoc
Testing
Testing is done with mocha, make sure it's installed:
npm i mocha -g
and run the tests found inside the test folder with
mocha
Todo
- Include Specifiers and their alias
- Conversion from and to types including Typed Arrays
- Bit manipulation methods (rotr, xor, etc)
- Node.js streaming
- ES6 support (shims & implementation)
- ES5 shims, in case they are ever needed