UInt

This is a simple javascript library for handing a subset of operations on a
precise width unsigned integer type. We developed this library to aid in working
with low-level network and device types. It is not an arbitrary precision
integer library. However, if you are dealing with network addresses, performing
route lookups, or attempting bitwise logical operations over a range of unsigned
integer widths this library may be helpful for you.

$3

``
var Broadcast = new UInt({ bits: 48}); // Ethernet MAC address
Braodcast.value('0xffffffffffff'); // Set to the Braodcast address
console.log(MAC.toString()); // Output the string version

// IPv4 network and mask address, construct using values or strings
var route = new UInt({ bits: 32, value: 0x0a000000 });
var mask = new UInt({ bits: 32, value: '0xffffff00' });

// IPv4 packet destination address
var ip = new UInt({ bits: 32, value: 0x0a00000a });

// Perform a route comparison
if(ip.and(mask).equal(route)) { ... }
if(equal(route, and(ip, mask))) { ... }

// IPv6 Address
var IPv6 = new UInt({ bits: 128 });
`

$3


- Prerequisites:
- Install Node or IO.js
- Install Grunt globally - `sudo npm install -g grunt-cli`
- Dependencies:
- Install local dependencies - `npm install`
- Tests:
- Execute unit tests - `grunt`

Types Supported

- UInt - unsigned integer with arbitrary bit/byte precision
- Match - pair of UInt, value and mask, useful for bitstring matching

Type Operations Supported

- Constructors: default, copy, fromJSON
- Equality: equal, notEqual
- Relational: less, lessEqual, greater, greaterEqual
- Logical bitwise: and, or, xor, neg, mask, lshift, rshift
- Arithmetic: plus, minus

Functions Supported

- Validation: is
- Equality: equal, notEqual
- Relational: less, lessEqual, greater, greaterEqual
- Logical bitwise: and, or, xor, neg, mask, lshift, rshift
- Arithmetic: plus, minus
- Uitility: howManyBits, howManyBytes, maxFromBits, maxFromBytes

Exceptions Generated

The UInt facilities will generate an exception under three conditions:
construction, internal value mutation, and binary operations/functions.

An exception is generated during construction if the supplied value requires
more bit/byte storage than has been specified with the bit/byte construction
parameters. Or construction can generate an exception if the supplied value is
not convertable to an unsigned integer. Mutating the internal value of a UInt
will generate the same types of exceptions as construction.

The supplied UInt binary operators can also generate exceptions. All of the
binary operations that return a UInt type will generate an exception if the two
supplied operands do not have the same bit/byte width.

Exceptions are currently explantory strings; they should be refactored into
distinct exception objects for easier catch handling.

Internal Storage

The UInt object stores the successfully constructed unsigned integer value in
the _value property. The type of this property is either a number or an array
of numbers. The reason for the non-uniform storage type is due to javascript's
handling of numbers.

Javascript treats all numbers (reals, naturals, integers) as real
numbers that it can store in a 64 bit floating point register. Integers up to
2^52 -1 can be safely stored in this register without loss of precision.
However, javascript's logical bitwise operators only work on 32 bit integer
representations. This means that for integers that can be stored in 32 bits or
less, a javascript number type will work. However, for all larger integers an
alterantive representational type is needed.

The UInt library stores all values that can be represented with a 32 bit
register as a javascript number, otherwise the value is stored in a javascript
array of numbers where each array cell is an 8 bit value. It might be more
efficient to store large representations in each cell of an array; however, for
expediency we chose an 8 bit representation.

If you review our code you will see all UInt methodes will typically test the
type of the _value property for either Number or Array, and perform a
slightly different computation accordingly. This is to handle the alternative
internalized representation of unsigned integers.

Construction

The UInt constructor can take an object as a paramter. The object can have
three properties: bits, bytes, and value. If bits or bytes are specified the
constructed UInt will be bounded by this precise width. The value may be a
number, string, or array of numbers. If no value is provided the UInt is
initialized to an invalid state; this is useful for deserialization from: JSON,
memory, file, socket, etc. If bits and bytes are omitted the width of the object
is fixed to the maximum width necessary to contain the provided value; otherwise
the object is constructed in an invalid state.

`
// no boundary width, invalid state
new UInt();

// Construct with boundary widths
// .. but defer setting values
new UInt({ bits: 4 }); // 4 bit width, invalid state
new UInt({ bytes: 4 }); // 4 byte width, invalid state
new UInt({ bits: 4, bytes: 2 }); // 20 bit width, invalid state
new UInt({ bits: 48 }); // 48 bit | 6 byte width, invalid state

// Consturct using numbers, strings, or arrays
new UInt({ value: 0 });
new UInt({ value: 0x0f0f0f0f });
new UInt({ value: '0x0f0f0f0f });
new UInt({ value: [ 1, 0, 0, 0, 0, 0, 0, 0, 0 ] });

var x = uint.copy(); // copy construct a new UInt object, as a method
var x = copy(uint); // copy construct a new UInt object, as a funciton

// Copy construct a new UInt object, from a json representation, as a function
var x = fromJSON(JSON.stringify(uint));
`

Accessor operations


The internalized unsigned integer value can be accesses through the value
method. Providing a parameter to this function will attempt a mutation of the
internal value, while omitting the parameter will just get the interalized
value.
`
console.log(x.value()); // Access the internalized UInt value
x.value(0xffffffffffff); // Mutate the internalized UInt value
`

Serializtion operations/functions

A UInt object can be serialized to either a string or a JSON string.
`
// UInt method versions of toString
console.log(uint.toString()); // decimal string representation
console.log(uint.toString(16)); // hex string representation
console.log(uint.toString(16, ':')); // hex rep. with inter-byte separator

// Function versions of toString
console.log(toString(uint)); // decimal string representation
console.log(toString(uint, 16)); // hex string representation
console.log(toString(uint, 16, ':')); // hex rep. with inter-byte separator

// Return a JSON representation of the object
return toJSON(uint);
`

Equality operations/functions


Equality and inequality methods and functions are provided for the UInt type.
All equality methods/functions return a boolean.
`
if(x.equal(y)) { console.log("x = y"); }
if(equal(x, y)) { console.log("x = y"); }
if(x.notEqual(y)) { console.log("x != y"); }
if(notEqual(x, y)) { console.log("x != y"); }
`

Relational operations/functions

Standard relational methods and functions are provided for the UInt type. All
relational methods/functions return a boolean;

`
if(x.less(y) { console.log("x < y"); }
if(less(x, y) { console.log("x < y"); }
if(x.lessEqual(y) { console.log("x <= y"); }
if(lessEqual(x, y) { console.log("x <= y"); }
if(x.greater(y)) { console.log("x > y"); }
if(greater(x, y)) { console.log("x > y"); }
if(x.greaterEqual(y)) { console.log("x >= y"); }
if(greaterEqual(x, y)) { console.log("x >= y"); }
`

Logical bitwise operations/functions


Standard logical bitwise methods and functions are provided for the UInt type.
These operations only work for UInt's of the same precision. If the calling
parameters of either function or mether do not have the bit and byte width, then
an exception is generated. All logical bitwise methods return the this
reference, all logical bitwise functions return a new UInt object.
`
return x.and(y); // Performs a &= and returns this
return and(x, y); // Constructs UInt, assigns x & y, returns new UInt
return x.or(y); // Performs a |= and returns this
return or(x, y); // Constructs UInt, assigns x | y, returns new UInt
return x.xor(y); // Performs a ^= and returns this
return xor(x, y); // Constructs UInt, assigns x ^ y, returns new UInt
return x.neg(); // Performs a ~= and returns this
return neg(x); // Constructs UInt, assigns ~x, returns new UInt
return x.lshift(4); // FIXME: not implemented
return lshift(x, 4); // FIXME: not implemented
return x.rshift(4); // FIXME: not implemented
return rshift(x, 4); // FIXME: not implemented
`

Arithmetic operations/functions

Plus and minus arithmetic methods and functions are provided for the UInt type.
These operations only work for UInt's of the same precision. If the calling
parameters of either function or mether do not have the bit and byte width, then
an exception is generated. All arithmetic methods return the this reference,
all arithmetic functions return a new UInt object.
`
return x.plus(y); // FIXME: not implemented
return plus(x, y); // FIXME: not implemented
return x.minus(y); // FIXME: not implemented
return minus(x, y); // FIXME: not implemented
`

Utility operations/funcitons

These are operations that we use through the UInt library. They primarily deal
with data representational properties.
`
return howManyBits(0x1ffff); // minimum number of bits needed to store value
return howManyBytes(0x1ffff); // minimum number of bytes needed to store value
return maxFromBytes(6); // maximum value storage in X bytes
return maxFromBits(48); // maximum value storage in X bits
return isBits(16); // FIXME: not implemented
``