ref - npm Package Compare versions

Comparing version 0.0.17 to 0.0.18

History.md

 
+0.0.18 / 2012-06-21
+===================
+
+ - add the non-native-endian read+write int64 functions
+ - starting on some real (inline) documentation
+
 0.0.17 / 2012-06-05
@@ -3,0 +9,0 @@ ===================

lib/ref.js

 
+var assert = require('assert')
 var debug = require('debug')('ref')
-  , assert = require('assert')
 
@@ -16,2 +16,5 @@ exports = module.exports = require('../build/Release/binding.node')
  * ```
+ *
+ * @param {Object} type
+ * @return {Object} The new "type" object with its `indirection` incremented by 1.
  */
@@ -32,2 +35,5 @@
  * "indirection" level decremented by 1.
+ *
+ * @param {Object} type
+ * @return {Object} The new "type" object with its `indirection` decremented by 1.
  */
@@ -46,7 +52,10 @@
 /**
- * Coerces a "type" object from a String or a real "type" object.
- * So:
- *   "int" gets coerced into `ref.types.int`.
- *   "int *" gets translated into `ref.refType(ref.types.int)`
- *   `ref.types.int` gets translated into `ref.types.int` (itself)
+ * Coerces a "type" object from a String or a real "type" object. So:
+ *
+ *   * "int" gets coerced into `ref.types.int`.
+ *   * "int *" gets translated into `ref.refType(ref.types.int)`
+ *   * `ref.types.int` gets translated into `ref.types.int` (itself)
+ *
+ * @param {Object|String} type
+ * @return {Object} A "type" object
  */
@@ -64,4 +73,2 @@
       // legacy "pointer" being used :(
-      //console.warn('type of "pointer" should not be used...')
-      //console.trace()
       rtn = exports.refType(exports.types.void) // void *
@@ -95,2 +102,5 @@ } else if (rtn === 'string') {
  * Creates a default type for the buffer when none exists.
+ *
+ * @param {Buffer} buffer The Buffer instance to get the "type" object from.
+ * @return {Object} The "type" object from the given Buffer.
  */
@@ -119,2 +129,7 @@
  * Bufffer instance when necessary.
+ *
+ * @param {Buffer} buffer The Buffer instance to read from.
+ * @param {Number} offset (optional) The offset on the Buffer to start reading from. Defaults to 0.
+ * @param {Object} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
+ * @return {?} Whatever value the "type" used when reading returns.
  */
@@ -148,2 +163,8 @@
  * "type" object if present) at the given offset with the given "value" to set.
+ *
+ * @param {Buffer} buffer The Buffer instance to write to.
+ * @param {Number} offset The offset on the Buffer to start writing to.
+ * @param {?} value The value to write to the Buffer instance.
+ * @param {Object} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
+ * @return {undefined}
  */
@@ -178,2 +199,6 @@
  * ```
+ *
+ * @param {Object} type The "type" object to allocate.
+ * @param {?} value (optional) The initial value set on the returned Buffer.
+ * @return {Buffer} A new Buffer instance with it's `type` set to "type", and (optionally) "value" written to it.
  */
@@ -203,2 +228,5 @@
  * string itself, and is NUL terminated.
+ *
+ * @param {String} string The JS string to be converted to a C string.
+ * @param {String} encoding (optional) The encoding to use for the C string. Defaults to 'utf8'.
  */
@@ -222,3 +250,8 @@
  * Unlike `readCString()`, this function requires the buffer to actually have the
- * proper length
+ * proper length.
+ *
+ * @param {Buffer} buffer The Buffer instance to write to.
+ * @param {Number} offset The offset of the buffer to begin writing at.
+ * @param {String} string The JS String to write that will be written to the buffer.
+ * @param {String} encoding (optional) The encoding to read the C string as. Defaults to 'utf8'.
  */
@@ -240,2 +273,36 @@
 
+exports['readInt64' + exports.endianness] = exports.readInt64
+exports['readUInt64' + exports.endianness] = exports.readUInt64
+exports['writeInt64' + exports.endianness] = exports.writeInt64
+exports['writeUInt64' + exports.endianness] = exports.writeUInt64
+
+var opposite = exports.endianness == 'LE' ? 'BE' : 'LE'
+var int64temp = new Buffer(exports.sizeof.int64)
+var uint64temp = new Buffer(exports.sizeof.uint64)
+
+exports['readInt64' + opposite] = function (buffer, offset) {
+  for (var i = 0; i < exports.sizeof.int64; i++) {
+    int64temp[i] = buffer[offset + exports.sizeof.int64 - i - 1]
+  }
+  return exports.readInt64(int64temp, 0)
+}
+exports['readUInt64' + opposite] = function (buffer, offset) {
+  for (var i = 0; i < exports.sizeof.uint64; i++) {
+    uint64temp[i] = buffer[offset + exports.sizeof.uint64 - i - 1]
+  }
+  return exports.readUInt64(uint64temp, 0)
+}
+exports['writeInt64' + opposite] = function (buffer, offset, value) {
+  exports.writeInt64(int64temp, 0, value)
+  for (var i = 0; i < exports.sizeof.int64; i++) {
+    buffer[offset + i] = int64temp[exports.sizeof.int64 - i - 1]
+  }
+}
+exports['writeUInt64' + opposite] = function (buffer, offset, value) {
+  exports.writeUInt64(uint64temp, 0, value)
+  for (var i = 0; i < exports.sizeof.uint64; i++) {
+    buffer[offset + i] = uint64temp[exports.sizeof.uint64 - i - 1]
+  }
+}
+
 /**
@@ -251,2 +318,5 @@ * `ref()` acceps a Buffer instance and returns a new Buffer
  * ```
+ *
+ * @param {Buffer} buffer A Buffer instance to create a reference to.
+ * @return {Buffer} A new Buffer instance pointing to "buffer".
  */
@@ -266,2 +336,5 @@
  * which should be an Object with it's own "get()" function.
+ *
+ * @param {Buffer} buffer A Buffer instance to read a reference from.
+ * @return {?} The returned value after dereferencing "buffer".
  */
@@ -275,6 +348,8 @@
 /**
- * "attach()" is meant for retaining references to Objects/Buffers in JS-land
- * from calls to "writeObject()" and "writePointer()". C-land doesn't retain the
- * source Buffer in "writePointer()", and "writeObject()" uses a weak reference
+ * `attach()` is meant for retaining references to Objects/Buffers in JS-land
+ * from calls to `_writeObject()` and `_writePointer()`. C-land doesn't retain the
+ * source Buffer in `writePointer()`, and `writeObject()` uses a weak reference
  * when writing the Object, so attaching afterwards in necessary. See below...
+ *
+ * @private true
  */
@@ -290,2 +365,12 @@
 /**
+ * The private `writeObject()` function does the actual writing of the given
+ * Object to the given Buffer instance. This version does not _attach_ the Object
+ * to the Buffer, which is potentially unsafe.
+ *
+ * @private true
+ */
+
+exports._writeObject = exports.writeObject
+
+/**
  * Overwrite the native "writeObject" function so that it keeps a ref to the
@@ -295,3 +380,2 @@ * passed in Object in JS-land by adding it to the Bufer's _refs array.
 
-exports._writeObject = exports.writeObject
 exports.writeObject = function writeObject (buf, offset, obj) {
@@ -304,2 +388,12 @@ debug('writing Object to buffer', buf, offset, obj)
 /**
+ * The private `writePointer()` function does the actual writing of the given
+ * pointer Buffer to the target Buffer instance. This version does not _attach_
+ * the pointer Buffer to the target Buffer, which is potentially unsafe.
+ *
+ * @private true
+ */
+
+exports._writePointer = exports.writePointer
+
+/**
  * Overwrite the native "writePointer" function so that it keeps a ref to the
@@ -309,3 +403,2 @@ * passed in Buffer in JS-land by adding it to the Bufer's _refs array.
 
-exports._writePointer = exports.writePointer
 exports.writePointer = function writePointer (buf, offset, ptr) {
@@ -321,5 +414,12 @@ debug('writing pointer to buffer', buf, offset, ptr)
  * the reinterpreted buffer is still watching it.
+ *
+ * @private true
  */
 
 exports._reinterpret = exports.reinterpret
+
+/**
+ * Returns a new Buffer instance with the specified size.
+ */
+
 exports.reinterpret = function reinterpret (buffer, size) {
@@ -333,5 +433,23 @@ debug('reinterpreting buffer to "%d" bytes', size)
 /**
+ * @private true
  */
 
 exports._reinterpretUntilZeros = exports.reinterpretUntilZeros
+
+/**
+ * Accepts a `Buffer` instance and a number of `NULL` bytes to read from the
+ * pointer. This function will scan past the boundary of the Buffer's `length`
+ * until it finds `size` number of aligned `NULL` bytes.
+ *
+ * This is useful for finding the end of NUL-termintated array or C string. For
+ * example, the `readCString()` function _could_ be implemented like:
+ *
+ * ``` js
+ * function readCString (buf) {
+ *   return ref.reinterpretUntilZeros(buf, 1).toString('utf8')
+ * }
+ * ```
+ *
+ */
+
 exports.reinterpretUntilZeros = function reinterpretUntilZeros (buffer, size) {
@@ -344,9 +462,15 @@ debug('reinterpreting buffer to until "%d" NULL (0) bytes are found', size)
 
-
 /**
  * Types.
+ *
+ * @section types
  */
 
-exports.types = {}
-exports.types.void = {
+var types = exports.types = {}
+
+/**
+ * The `void` type.
+ */
+
+types.void = {
     size: 0
@@ -362,3 +486,8 @@ , indirection: 1
 }
-exports.types.int8 = {
+
+/**
+ * The `int8` type.
+ */
+
+types.int8 = {
     size: exports.sizeof.int8
@@ -376,3 +505,8 @@ , indirection: 1
 }
-exports.types.uint8 = {
+
+/**
+ * The `uint8` type.
+ */
+
+types.uint8 = {
     size: exports.sizeof.uint8
@@ -390,3 +524,8 @@ , indirection: 1
 }
-exports.types.int16 = {
+
+/**
+ * The `int16` type.
+ */
+
+types.int16 = {
     size: exports.sizeof.int16
@@ -401,3 +540,8 @@ , indirection: 1
 }
-exports.types.uint16 = {
+
+/**
+ * The `uint16` type.
+ */
+
+types.uint16 = {
     size: exports.sizeof.uint16
@@ -412,3 +556,8 @@ , indirection: 1
 }
-exports.types.int32 = {
+
+/**
+ * The `int32` type.
+ */
+
+types.int32 = {
     size: exports.sizeof.int32
@@ -423,3 +572,8 @@ , indirection: 1
 }
-exports.types.uint32 = {
+
+/**
+ * The `uint32` type.
+ */
+
+types.uint32 = {
     size: exports.sizeof.uint32
@@ -434,3 +588,8 @@ , indirection: 1
 }
-exports.types.int64 = {
+
+/**
+ * The `int64` type.
+ */
+
+types.int64 = {
     size: exports.sizeof.int64
@@ -445,3 +604,8 @@ , indirection: 1
 }
-exports.types.uint64 = {
+
+/**
+ * The `uint64` type.
+ */
+
+types.uint64 = {
     size: exports.sizeof.uint64
@@ -456,3 +620,8 @@ , indirection: 1
 }
-exports.types.float = {
+
+/**
+ * The `float` type.
+ */
+
+types.float = {
     size: exports.sizeof.float
@@ -467,3 +636,8 @@ , indirection: 1
 }
-exports.types.double = {
+
+/**
+ * The `double` type.
+ */
+
+types.double = {
     size: exports.sizeof.double
@@ -478,3 +652,9 @@ , indirection: 1
 }
-exports.types.Object = {
+
+/**
+ * The `Object` type. This can be used to read/write regular JS Objects
+ * into raw memory.
+ */
+
+types.Object = {
     size: exports.sizeof.Object
@@ -491,11 +671,11 @@ , indirection: 1
 /**
- * Utf8Strings are a kind of weird thing. We say it's a sizeof(char *),
- * so that means that we have to return a Buffer that is pointer sized, and points
- * to a some utf8 string data, so we have to create a 2nd "in-between" buffer.
+ * The `Utf8String` (a.k.a `"string"`) type.
  *
- * Really, people should just use a proper `char *` type.
- * This is only here for legacy purposes...
+ * Utf8Strings are a kind of weird thing. We say it's `sizeof(char *)`, and
+ * `indirection` level of 1, which means that we have to return a Buffer that
+ * is pointer sized, and points to a some utf8 string data, so we have to create
+ * a 2nd "in-between" buffer.
  */
 
-exports.types.Utf8String = {
+types.Utf8String = {
     size: exports.sizeof.pointer
@@ -560,4 +740,4 @@ , indirection: 1
 
-/**
- * Set the "name" of the types. Used for debugging...
+/*!
+ * Set the `name` property of the types. Used for debugging...
  */
@@ -569,5 +749,11 @@
 
+/*!
+ * Set the `type` property of the `NULL` pointer Buffer object.
+ */
 
+exports.NULL.type = exports.types.void
+
 /**
- * NULL_POINTER is essentially:
+ * `NULL_POINTER` is a Buffer pointing to `NULL`. So it's equivalent to the
+ * following C code:
  *
@@ -580,6 +766,5 @@ * ``` c
 
-exports.NULL.type = exports.types.void
 exports.NULL_POINTER = exports.ref(exports.NULL)
 
-/**
+/*!
  * This `char *` type is used by "allocCString()" above.
@@ -590,5 +775,12 @@ */
 
+/**
+ * Convenience methods added to `Buffer.prototype`.
+ *
+ * @section buffer
+ */
 
 /**
- * Buffer convenience methods.
+ * Calls `ref.address()` on the Buffer instance.
+ *
+ * @return {Number} The memory address of the Buffer.
  */
@@ -636,18 +828,34 @@
 
-Buffer.prototype['readInt64' + exports.endianness] = function readInt64 (offset) {
-  return exports.readInt64(this, offset)
+Buffer.prototype.readInt64BE = function readInt64BE (offset) {
+  return exports.readInt64BE(this, offset)
 }
 
-Buffer.prototype['writeInt64' + exports.endianness] = function writeInt64 (val, offset) {
-  return exports.writeInt64(this, offset, val)
+Buffer.prototype.writeInt64BE = function writeInt64BE (val, offset) {
+  return exports.writeInt64BE(this, offset, val)
 }
 
-Buffer.prototype['readUInt64' + exports.endianness] = function readUInt64 (offset) {
-  return exports.readUInt64(this, offset)
+Buffer.prototype.readUInt64BE = function readUInt64BE (offset) {
+  return exports.readUInt64BE(this, offset)
 }
 
-Buffer.prototype['writeUInt64' + exports.endianness] = function writeUInt64 (val, offset) {
-  return exports.writeUInt64(this, offset, val)
+Buffer.prototype.writeUInt64BE = function writeUInt64BE (val, offset) {
+  return exports.writeUInt64BE(this, offset, val)
 }
 
+Buffer.prototype.readInt64LE = function readInt64LE (offset) {
+  return exports.readInt64LE(this, offset)
+}
+
+Buffer.prototype.writeInt64LE = function writeInt64LE (val, offset) {
+  return exports.writeInt64LE(this, offset, val)
+}
+
+Buffer.prototype.readUInt64LE = function readUInt64LE (offset) {
+  return exports.readUInt64LE(this, offset)
+}
+
+Buffer.prototype.writeUInt64LE = function writeUInt64LE (val, offset) {
+  return exports.writeUInt64LE(this, offset, val)
+}
+
 Buffer.prototype.reinterpret = function reinterpret (size) {
@@ -665,3 +873,3 @@ return exports.reinterpret(this, size)
 
-  /**
+  /*!
    * SlowBuffer convenience methods.
@@ -684,6 +892,10 @@ */
   SlowBuffer.prototype.reinterpretUntilZeros = Buffer.prototype.reinterpretUntilZeros
-  SlowBuffer.prototype['readInt64' + exports.endianness] = Buffer.prototype['readInt64' + exports.endianness]
-  SlowBuffer.prototype['writeInt64' + exports.endianness] = Buffer.prototype['writeInt64' + exports.endianness]
-  SlowBuffer.prototype['readUInt64' + exports.endianness] = Buffer.prototype['readUInt64' + exports.endianness]
-  SlowBuffer.prototype['writeUInt64' + exports.endianness] = Buffer.prototype['writeUInt64' + exports.endianness]
+  SlowBuffer.prototype.readInt64BE = Buffer.prototype.readInt64BE
+  SlowBuffer.prototype.writeInt64BE = Buffer.prototype.writeInt64BE
+  SlowBuffer.prototype.readUInt64BE = Buffer.prototype.readUInt64BE
+  SlowBuffer.prototype.writeUInt64BE = Buffer.prototype.writeUInt64BE
+  SlowBuffer.prototype.readInt64LE = Buffer.prototype.readInt64LE
+  SlowBuffer.prototype.writeInt64LE = Buffer.prototype.writeInt64LE
+  SlowBuffer.prototype.readUInt64LE = Buffer.prototype.readUInt64LE
+  SlowBuffer.prototype.writeUInt64LE = Buffer.prototype.writeUInt64LE
 }

package.json

@@ -19,3 +19,3 @@ { "name": "ref"
   ]
-, "version": "0.0.17"
+, "version": "0.0.18"
 , "author": "Nathan Rajlich <[e-mail]> (http://tootallnate.net)"
@@ -25,3 +25,4 @@ , "repository": { "type": "git", "url": "git://github.com/TooTallNate/ref.git" }
 , "scripts": {
-      "test": "mocha -gc --reporter spec"
+      "docs": "jade docs/index.jade --obj \"{ dox: $(dox < lib/ref.js) }\""
+    , "test": "mocha -gc --reporter spec"
   }
@@ -34,4 +35,6 @@ , "dependencies": {
     , "weak": "*"
+    , "dox": "*"
+    , "jade": "*"
   }
 , "engines": { "node": "*" }
 }

test/int64.js

@@ -81,2 +81,24 @@
 
+  ;['LE', 'BE'].forEach(function (endianness) {
+
+    describe(endianness, function () {
+
+      it('should read and write a signed ' + endianness + ' 64-bit integer', function () {
+        var val = -123456789
+        var buf = new Buffer(ref.sizeof.int64)
+        ref['writeInt64' + endianness](buf, 0, val)
+        assert.equal(val, ref['readInt64' + endianness](buf, 0))
+      })
+
+      it('should read and write an unsigned ' + endianness + ' 64-bit integer', function () {
+        var val = 123456789
+        var buf = new Buffer(ref.sizeof.uint64)
+        ref['writeUInt64' + endianness](buf, 0, val)
+        assert.equal(val, ref['readUInt64' + endianness](buf, 0))
+      })
+
+    })
+
+  })
+
 })

test/object.js

@@ -55,2 +55,18 @@
 
+  describe('offset', function () {
+
+    it('should read two Objects next to each other in memory', function () {
+      var buf = new Buffer(ref.sizeof.pointer * 2)
+      var a = {}
+      var b = {}
+      buf.writeObject(a, 0 * ref.sizeof.pointer)
+      buf.writeObject(b, 1 * ref.sizeof.pointer)
+      var _a = buf.readObject(0 * ref.sizeof.pointer)
+      var _b = buf.readObject(1 * ref.sizeof.pointer)
+      assert.strictEqual(a, _a)
+      assert.strictEqual(b, _b)
+    })
+
+  })
+
 })

test/pointer.js

@@ -54,2 +54,18 @@
 
+  describe('offset', function () {
+
+    it('should read two pointers next to each other in memory', function () {
+      var buf = new Buffer(ref.sizeof.pointer * 2)
+      var a = new Buffer('hello')
+      var b = new Buffer('world')
+      buf.writePointer(a, 0 * ref.sizeof.pointer)
+      buf.writePointer(b, 1 * ref.sizeof.pointer)
+      var _a = buf.readPointer(0 * ref.sizeof.pointer)
+      var _b = buf.readPointer(1 * ref.sizeof.pointer)
+      assert.equal(a.address(), _a.address())
+      assert.equal(b.address(), _b.address())
+    })
+
+  })
+
 })

New alerts

Non-existent author

Supply chain risk

The package was published by an npm account that no longer exists.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

82645

11.91%

Number of package files

22

4.76%

Lines of code

1274

20.3%

Worsened metrics

Dev dependency count

4

100%

Number of high supply chain risk alerts

1

Infinity%

No dependency changes