ref - npm Package Compare versions

Comparing version 0.0.19 to 0.0.20

History.md

 
+0.0.20 / 2012-06-27
+===================
+
+ - rename the `Utf8String` type to `CString` (#5)
+ - make `Utf8String` an alias to `CString` and deprecated
+ - more work on docs (not yet ready)
+
 0.0.19 / 2012-06-25
@@ -3,0 +10,0 @@ ==================

lib/ref.js

@@ -72,3 +72,3 @@
     } else if (rtn === 'string') {
-      rtn = exports.types.Utf8String // special char * type
+      rtn = exports.types.CString // special char * type
     } else {
@@ -415,2 +415,9 @@ var refCount = 0
 /**
+ * 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 private version does not "attach" the original `Buffer` to the returned
+ * `Buffer`, which could be potentially dangerous. Use with caution!
+ *
  * @private true
@@ -445,3 +452,4 @@ */
 /**
- * Types.
+ * Here are all the built-in "types" in ref's Type System. All of the built-in
+ * types read and write "native endianness" when multi-byte types are used.
  *
@@ -642,5 +650,5 @@ * @section types
 /**
- * The `Utf8String` (a.k.a `"string"`) type.
+ * The `CString` (a.k.a `"string"`) type.
  *
- * Utf8Strings are a kind of weird thing. We say it's `sizeof(char *)`, and
+ * CStrings 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
@@ -651,4 +659,5 @@ * is pointer sized, and points to a some utf8 string data, so we have to create
 
-types.Utf8String = {
+types.CString = {
     size: exports.sizeof.pointer
+  , alignment: exports.alignof.pointer
   , indirection: 1
@@ -668,3 +677,84 @@ , get: function get (buf, offset) {
 
+// alias Utf8String
+var utfstringwarned = false
+Object.defineProperty(types, 'Utf8String', {
+    enumerable: false
+  , configurable: true
+  , get: function () {
+      if (!utfstringwarned) {
+        utfstringwarned = true
+        console.error('"Utf8String" type is deprecated, use "CString" instead')
+      }
+      return types.CString
+    }
+})
 
+/**
+ * The `bool` type.
+ *
+ * Variable-length (1-byte 99% of the time) type that can hold `true` or
+ * `false` values.
+ */
+types.bool = types;
+
+/**
+ * The `byte` type.
+ */
+types.byte = types;
+
+/**
+ * The `char` type.
+ */
+types.char = types;
+
+/**
+ * The `uchar` type.
+ */
+types.uchar = types;
+
+/**
+ * The `short` type.
+ */
+types.short = types;
+
+/**
+ * The `ushort` type.
+ */
+types.ushort = types;
+
+/**
+ * The `int` type.
+ */
+types.int = types;
+
+/**
+ * The `uint` type.
+ */
+types.uint = types;
+
+/**
+ * The `long` type.
+ */
+types.long = types;
+
+/**
+ * The `ulong` type.
+ */
+types.ulong = types;
+
+/**
+ * The `longlong` type.
+ */
+types.longlong = types;
+
+/**
+ * The `ulonglong` type.
+ */
+types.ulonglong = types;
+
+/**
+ * The `size_t` type.
+ */
+types.size_t = types;
+
 // "typedef"s for the variable-sized types
@@ -695,5 +785,2 @@ ;[ 'bool', 'byte', 'char', 'uchar', 'short', 'ushort', 'int', 'uint', 'long'
 
-// make the `Utf8String` type have the correct 'alignment' property
-exports.types.Utf8String.alignment = exports.alignof.pointer
-
 // make the `bool` type work with JS true/false values
@@ -733,4 +820,4 @@ exports.types.bool.get = (function (_get) {
  * ``` c
- * char **null_pointer;
- * *null_pointer = NULL;
+ * char *null_pointer;
+ * null_pointer = NULL;
  * ```
@@ -748,3 +835,3 @@ */
 /**
- * Convenience methods added to `Buffer.prototype`.
+ * `ref` adds a few convenience methods added to `Buffer.prototype`.
  *
@@ -764,2 +851,10 @@ * @section buffer
 
+/**
+ * Calls `ref.isNull()` on the Buffer instance.
+ *
+ * @return {Boolean} `true` if the memory address of the Buffer is NULL,
+ * `false` otherwise.
+ */
+
+
 Buffer.prototype.isNull = function isNull () {
@@ -769,2 +864,8 @@ return exports.isNull(this)
 
+/**
+ * Calls `ref.ref()` on the Buffer instance.
+ *
+ * @return {Buffer} A new "pointer" `Buffer` instance pointing to this `Buffer`.
+ */
+
 Buffer.prototype.ref = function ref () {
@@ -774,2 +875,8 @@ return exports.ref(this)
 
+/**
+ * Calls `ref.deref()` on the Buffer instance.
+ *
+ * @return {?} The dereferenced value from this Buffer.
+ */
+
 Buffer.prototype.deref = function deref () {
@@ -779,2 +886,10 @@ return exports.deref(this)
 
+/**
+ * Calls `ref.readObject()` on the Buffer instance.
+ *
+ * @param {Number} offset The offset of the Buffer to read the Object from.
+ * @return {Object} The JavaScript object that was written to the specified memory
+ * address in the Buffer.
+ */
+
 Buffer.prototype.readObject = function readObject (offset) {
@@ -784,2 +899,9 @@ return exports.readObject(this, offset)
 
+/**
+ * Calls `ref.writeObject()` on the Buffer instance.
+ *
+ * @param {Object} obj The Object to write.
+ * @param {Number} offset The offet of the Buffer to write the Object at.
+ */
+
 Buffer.prototype.writeObject = function writeObject (obj, offset) {
@@ -786,0 +908,0 @@ return exports.writeObject(this, offset, obj)

package.json

@@ -19,3 +19,3 @@ { "name": "ref"
   ]
-, "version": "0.0.19"
+, "version": "0.0.20"
 , "author": "Nathan Rajlich <[e-mail]> (http://tootallnate.net)"
@@ -22,0 +22,0 @@ , "repository": { "type": "git", "url": "git://github.com/TooTallNate/ref.git" }

README.md

@@ -161,3 +161,3 @@ ref
 
-#### `Buffer#readInt64[native-endianness](Number offset)` → Number|String
+#### `Buffer#readInt64LE(Number offset)` → Number|String
 
@@ -170,3 +170,3 @@ Returns a Number or String representation of the 64-bit int read from this Buffer
 
-#### `Buffer#writeInt64[native-endianness](Number|String value, Number offset)` → undefined
+#### `Buffer#writeInt64LE(Number|String value, Number offset)` → undefined
 
@@ -180,3 +180,3 @@ Writes an value as a `int64_t` to this Buffer at the given offset. `value` may be
 
-#### `Buffer#readUInt64[native-endianness](Number offset)` → Number|String
+#### `Buffer#readUInt64LE(Number offset)` → Number|String
 
@@ -190,3 +190,3 @@ Returns a Number or String representation of the 64-bit unsigned int read from
 
-#### `Buffer#writeUInt64[native-endianness](Number|String value, Number offset)` → undefined
+#### `Buffer#writeUInt64LE(Number|String value, Number offset)` → undefined
 
@@ -200,2 +200,37 @@ Writes an value as a `int64_t` to this Buffer at the given offset. `value` may be
 
+#### `Buffer#readInt64BE(Number offset)` → Number|String
+
+Returns a Number or String representation of the 64-bit int read from this Buffer
+at the given offset. If the returned value will fit inside a Number without losing
+precision, then a Number is returned, otherwise a String is returned.
+
+---
+
+#### `Buffer#writeInt64BE(Number|String value, Number offset)` → undefined
+
+Writes an value as a `int64_t` to this Buffer at the given offset. `value` may be
+either a Number or a String representing the 64-bit int value. Ensure that at
+least `ref.sizeof.int64` (always 8) bytes are available in the Buffer after the
+given offset.
+
+---
+
+#### `Buffer#readUInt64BE(Number offset)` → Number|String
+
+Returns a Number or String representation of the 64-bit unsigned int read from
+this Buffer at the given offset. If the returned value will fit inside a
+Number without losing precision, then a Number is returned, otherwise a String
+is returned.
+
+---
+
+#### `Buffer#writeUInt64BE(Number|String value, Number offset)` → undefined
+
+Writes an value as a `int64_t` to this Buffer at the given offset. `value` may be
+either a Number or a String representing the 64-bit unsigned int value. Ensure
+that at least `ref.sizeof.uint64` (always 8) bytes are available in the Buffer
+after the given offset.
+
+---
+
 #### `Buffer#reinterpret(Number size)` → Buffer
@@ -233,3 +268,3 @@
 | `Object`     | A type capable of reading/writing references to JS objects
-| `Utf8String` | NULL-terminated String (char *)
+| `CString`    | NULL-terminated String (char *)
 
@@ -236,0 +271,0 @@ In addition to the basic types, there are type aliases for common C types.

test/string.js

@@ -62,10 +62,10 @@
 
-  describe('Utf8String', function () {
+  describe('CString', function () {
 
     it('should return JS `null` when given a pointer pointing to NULL', function () {
-      var buf = ref.alloc(ref.types.Utf8String)
+      var buf = ref.alloc(ref.types.CString)
       buf.writePointer(ref.NULL)
       assert.strictEqual(null, buf.deref())
 
-      assert.strictEqual(null, ref.get(ref.NULL_POINTER, 0, ref.types.Utf8String))
+      assert.strictEqual(null, ref.get(ref.NULL_POINTER, 0, ref.types.CString))
     })
@@ -75,3 +75,3 @@
       var str = 'hello world'
-      var buf = ref.alloc(ref.types.Utf8String)
+      var buf = ref.alloc(ref.types.CString)
       buf.writePointer(Buffer(str + '\0'))
@@ -78,0 +78,0 @@ assert.strictEqual(str, buf.deref())

No alert changes

Improved metrics

Total package byte prevSize

86507

increased by4.58%

Lines of code

1378

increased by8.16%

Number of lines in readme file

360

increased by10.77%

No dependency changes