Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/glacials/splits-io. a speedrunning data store and analysis engine splits.io
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464var assert = require('assert')var inspect = require('util').inspectvar debug = require('debug')('ref')
exports = module.exports = require('bindings')('binding')
/** * A `Buffer` that references the C NULL pointer. That is, its memory address * points to 0. Its `length` is 0 because accessing any data from this buffer * would cause a _segmentation fault_. * * ``` * console.log(ref.NULL); * <SlowBuffer@0x0 > * ``` * * @name NULL * @type Buffer */
/** * A string that represents the native endianness of the machine's processor. * The possible values are either `"LE"` or `"BE"`. * * ``` * console.log(ref.endianness); * 'LE' * ``` * * @name endianness * @type String */
/** * Accepts a `Buffer` instance and returns the memory address of the buffer * instance. * * ``` * console.log(ref.address(new Buffer(1))); * 4320233616 * * console.log(ref.address(ref.NULL))); * 0 * ``` * * @param {Buffer} buffer The buffer to get the memory address of. * @return {Number} The memory address the buffer instance. * @name address * @type method */
/** * Accepts a `Buffer` instance and returns _true_ if the buffer represents the * NULL pointer, _false_ otherwise. * * ``` * console.log(ref.isNull(new Buffer(1))); * false * * console.log(ref.isNull(ref.NULL)); * true * ``` * * @param {Buffer} buffer The buffer to check for NULL. * @return {Boolean} true or false. * @name isNull * @type method */
/** * Reads a JavaScript Object that has previously been written to the given * _buffer_ at the given _offset_. * * ``` * var obj = { foo: 'bar' }; * var buf = ref.alloc('Object', obj); * * var obj2 = ref.readObject(buf, 0); * console.log(obj === obj2); * true * ``` * * @param {Buffer} buffer The buffer to read an Object from. * @param {Number} offset The offset to begin reading from. * @return {Object} The Object that was read from _buffer_. * @name readObject * @type method */
/** * Reads a Buffer instance from the given _buffer_ at the given _offset_. * The _size_ parameter specifies the `length` of the returned Buffer instance, * which defaults to __0__. * * ``` * var buf = new Buffer('hello world'); * var pointer = ref.alloc('pointer'); * * var buf2 = ref.readPointer(pointer, 0, buf.length); * console.log(buf.toString()); * 'hello world' * ``` * * @param {Buffer} buffer The buffer to read a Buffer from. * @param {Number} offset The offset to begin reading from. * @param {Number} length (optional) The length of the returned Buffer. Defaults to 0. * @return {Buffer} The Buffer instance that was read from _buffer_. * @name readPointer * @type method */
/** * Returns a JavaScript String read from _buffer_ at the given _offset_. The * C String is read until the first NULL byte, which indicates the end of the * String. * * This function can read beyond the `length` of a Buffer. * * ``` * var buf = new Buffer('hello\0world\0'); * * var str = ref.readCString(buf, 0); * console.log(str); * 'hello' * ``` * * @param {Buffer} buffer The buffer to read a Buffer from. * @param {Number} offset The offset to begin reading from. * @return {String} The String that was read from _buffer_. * @name readCString * @type method */
/** * Returns a big-endian signed 64-bit int read from _buffer_ at the given * _offset_. * * If the returned value will fit inside a JavaScript Number without losing * precision, then a Number is returned, otherwise a String is returned. * * ``` * var buf = ref.alloc('int64'); * ref.writeInt64BE(buf, 0, '9223372036854775807'); * * var val = ref.readInt64BE(buf, 0) * console.log(val) * '9223372036854775807' * ``` * * @param {Buffer} buffer The buffer to read a Buffer from. * @param {Number} offset The offset to begin reading from. * @return {Number|String} The Number or String that was read from _buffer_. * @name readInt64BE * @type method */
/** * Returns a little-endian signed 64-bit int read from _buffer_ at the given * _offset_. * * If the returned value will fit inside a JavaScript Number without losing * precision, then a Number is returned, otherwise a String is returned. * * ``` * var buf = ref.alloc('int64'); * ref.writeInt64LE(buf, 0, '9223372036854775807'); * * var val = ref.readInt64LE(buf, 0) * console.log(val) * '9223372036854775807' * ``` * * @param {Buffer} buffer The buffer to read a Buffer from. * @param {Number} offset The offset to begin reading from. * @return {Number|String} The Number or String that was read from _buffer_. * @name readInt64LE * @type method */
/** * Returns a big-endian unsigned 64-bit int read from _buffer_ at the given * _offset_. * * If the returned value will fit inside a JavaScript Number without losing * precision, then a Number is returned, otherwise a String is returned. * * ``` * var buf = ref.alloc('uint64'); * ref.writeUInt64BE(buf, 0, '18446744073709551615'); * * var val = ref.readUInt64BE(buf, 0) * console.log(val) * '18446744073709551615' * ``` * * @param {Buffer} buffer The buffer to read a Buffer from. * @param {Number} offset The offset to begin reading from. * @return {Number|String} The Number or String that was read from _buffer_. * @name readUInt64BE * @type method */
/** * Returns a little-endian unsigned 64-bit int read from _buffer_ at the given * _offset_. * * If the returned value will fit inside a JavaScript Number without losing * precision, then a Number is returned, otherwise a String is returned. * * ``` * var buf = ref.alloc('uint64'); * ref.writeUInt64LE(buf, 0, '18446744073709551615'); * * var val = ref.readUInt64LE(buf, 0) * console.log(val) * '18446744073709551615' * ``` * * @param {Buffer} buffer The buffer to read a Buffer from. * @param {Number} offset The offset to begin reading from. * @return {Number|String} The Number or String that was read from _buffer_. * @name readUInt64LE * @type method */
/** * Writes the _input_ Number or String as a big-endian signed 64-bit int into * _buffer_ at the given _offset_. * * ``` * var buf = ref.alloc('int64'); * ref.writeInt64BE(buf, 0, '9223372036854775807'); * ``` * * @param {Buffer} buffer The buffer to write to. * @param {Number} offset The offset to begin writing from. * @param {Number|String} input This String or Number which gets written. * @name writeInt64BE * @type method */
/** * Writes the _input_ Number or String as a little-endian signed 64-bit int into * _buffer_ at the given _offset_. * * ``` * var buf = ref.alloc('int64'); * ref.writeInt64LE(buf, 0, '9223372036854775807'); * ``` * * @param {Buffer} buffer The buffer to write to. * @param {Number} offset The offset to begin writing from. * @param {Number|String} input This String or Number which gets written. * @name writeInt64LE * @type method */
/** * Writes the _input_ Number or String as a big-endian unsigned 64-bit int into * _buffer_ at the given _offset_. * * ``` * var buf = ref.alloc('uint64'); * ref.writeUInt64BE(buf, 0, '18446744073709551615'); * ``` * * @param {Buffer} buffer The buffer to write to. * @param {Number} offset The offset to begin writing from. * @param {Number|String} input This String or Number which gets written. * @name writeUInt64BE * @type method */
/** * Writes the _input_ Number or String as a little-endian unsigned 64-bit int * into _buffer_ at the given _offset_. * * ``` * var buf = ref.alloc('uint64'); * ref.writeUInt64LE(buf, 0, '18446744073709551615'); * ``` * * @param {Buffer} buffer The buffer to write to. * @param {Number} offset The offset to begin writing from. * @param {Number|String} input This String or Number which gets written. * @name writeUInt64LE * @type method */
/** * Returns a new clone of the given "type" object, with its * `indirection` level incremented by **1**. * * Say you wanted to create a type representing a `void *`: * * ``` * var voidPtrType = ref.refType(ref.types.void); * ``` * * @param {Object|String} type The "type" object to create a reference type from. Strings get coerced first. * @return {Object} The new "type" object with its `indirection` incremented by 1. */
exports.refType = function refType (type) { var _type = exports.coerceType(type) var rtn = Object.create(_type) rtn.indirection++ if (_type.name) { Object.defineProperty(rtn, 'name', { value: _type.name + '*', configurable: true, enumerable: true, writable: true }) } return rtn}
/** * Returns a new clone of the given "type" object, with its * `indirection` level decremented by 1. * * @param {Object|String} type The "type" object to create a dereference type from. Strings get coerced first. * @return {Object} The new "type" object with its `indirection` decremented by 1. */
exports.derefType = function derefType (type) { var _type = exports.coerceType(type) if (_type.indirection === 1) { throw new Error('Cannot create deref\'d type for type with indirection 1') } var rtn = Object.getPrototypeOf(_type) if (rtn.indirection !== _type.indirection - 1) { // slow case rtn = Object.create(_type) rtn.indirection-- } return rtn}
/** * Coerces a "type" object from a String or an actual "type" object. String values * are looked up from the `ref.types` 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` (returns itself) * * Throws an Error if no valid "type" object could be determined. Most `ref` * functions use this function under the hood, so anywhere a "type" object is * expected, a String may be passed as well, including simply setting the * `buffer.type` property. * * ``` * var type = ref.coerceType('int **'); * * console.log(type.indirection); * 3 * ``` * * @param {Object|String} type The "type" Object or String to coerce. * @return {Object} A "type" object */
exports.coerceType = function coerceType (type) { var rtn = type if (typeof rtn === 'string') { rtn = exports.types[type] if (rtn) return rtn
// strip whitespace rtn = type.replace(/\s+/g, '').toLowerCase() if (rtn === 'pointer') { // legacy "pointer" being used :( rtn = exports.refType(exports.types.void) // void * } else if (rtn === 'string') { rtn = exports.types.CString // special char * type } else { var refCount = 0 rtn = rtn.replace(/\*/g, function () { refCount++ return '' }) // allow string names to be passed in rtn = exports.types[rtn] if (refCount > 0) { if (!(rtn && 'size' in rtn && 'indirection' in rtn)) { throw new TypeError('could not determine a proper "type" from: ' + JSON.stringify(type)) } for (var i = 0; i < refCount; i++) { rtn = exports.refType(rtn) } } } } if (!(rtn && 'size' in rtn && 'indirection' in rtn)) { throw new TypeError('could not determine a proper "type" from: ' + JSON.stringify(type)) } return rtn}
/** * Returns the "type" property of the given Buffer. * 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. */
exports.getType = function getType (buffer) { if (!buffer.type) { debug('WARN: no "type" found on buffer, setting default "type"', buffer) buffer.type = {} buffer.type.size = buffer.length buffer.type.indirection = 1 buffer.type.get = function get () { throw new Error('unknown "type"; cannot get()') } buffer.type.set = function set () { throw new Error('unknown "type"; cannot set()') } } return exports.coerceType(buffer.type)}
/** * Calls the `get()` function of the Buffer's current "type" (or the * passed in _type_ if present) at the given _offset_. * * This function handles checking the "indirection" level and returning a * proper "dereferenced" 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|String} 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. */
exports.get = function get (buffer, offset, type) { if (!offset) { offset = 0 } if (type) { type = exports.coerceType(type) } else { type = exports.getType(buffer) } debug('get(): (offset: %d)', offset, buffer) assert(type.indirection > 0, '"indirection" level must be at least 1') if (type.indirection === 1) { // need to check "type" return type.get(buffer, offset) } else { // need to create a deref'd Buffer var size = type.indirection === 2 ? type.size : exports.sizeof.pointer var reference = exports.readPointer(buffer, offset, size) reference.type = exports.derefType(type) return reference }}
/** * Calls the `set()` function of the Buffer's current "type" (or the * passed in _type_ if present) at the given _offset_. * * This function handles checking the "indirection" level writing a pointer rather * than calling the `set()` function if the indirection is greater than 1. * * @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|String} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer. */
exports.set = function set (buffer, offset, value, type) { if (!offset) { offset = 0 } if (type) { type = exports.coerceType(type) } else { type = exports.getType(buffer) } debug('set(): (offset: %d)', offset, buffer, value) assert(type.indirection >= 1, '"indirection" level must be at least 1') if (type.indirection === 1) { type.set(buffer, offset, value) } else { exports.writePointer(buffer, offset, value) }}
/** * Returns a new Buffer instance big enough to hold `type`, * with the given `value` written to it. * * ``` js * var intBuf = ref.alloc(ref.types.int) * var int_with_4 = ref.alloc(ref.types.int, 4) * ``` * * @param {Object|String} type The "type" object to allocate. Strings get coerced first. * @param {?} value (optional) The initial value set on the returned Buffer, using _type_'s `set()` function. * @return {Buffer} A new Buffer instance with it's `type` set to "type", and (optionally) "value" written to it. */
exports.alloc = function alloc (_type, value) { var type = exports.coerceType(_type) debug('allocating Buffer for type with "size"', type.size) var size if (type.indirection === 1) { size = type.size } else { size = exports.sizeof.pointer } var buffer = new Buffer(size) buffer.type = type if (arguments.length >= 2) { debug('setting value on allocated buffer', value) exports.set(buffer, 0, value, type) } return buffer}
/** * Returns a new `Buffer` instance with the given String written to it with the * given encoding (defaults to __'utf8'__). The buffer is 1 byte longer than the * string itself, and is NUL terminated. * * ``` * var buf = ref.allocCString('hello world'); * * console.log(buf.toString()); * 'hello world\u0000' * ``` * * @param {String} string The JavaScript string to be converted to a C string. * @param {String} encoding (optional) The encoding to use for the C string. Defaults to __'utf8'__. * @return {Buffer} The new `Buffer` instance with the specified String wrtten to it, and a trailing NUL byte. */
exports.allocCString = function allocCString (string, encoding) { if (null == string || (Buffer.isBuffer(string) && exports.isNull(string))) { return exports.NULL } var size = Buffer.byteLength(string, encoding) + 1 var buffer = new Buffer(size) exports.writeCString(buffer, 0, string, encoding) buffer.type = charPtrType return buffer}
/** * Writes the given string as a C String (NULL terminated) to the given buffer * at the given offset. "encoding" is optional and defaults to __'utf8'__. * * Unlike `readCString()`, this function requires the buffer to actually have the * 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 JavaScript 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'__. */
exports.writeCString = function writeCString (buffer, offset, string, encoding) { assert(Buffer.isBuffer(buffer), 'expected a Buffer as the first argument') assert.equal('string', typeof string, 'expected a "string" as the third argument') if (!offset) { offset = 0 } if (!encoding) { encoding = 'utf8' } var size = buffer.length - offset var len = buffer.write(string, offset, size, encoding) buffer.writeUInt8(0, offset + len) // NUL terminate}
exports['readInt64' + exports.endianness] = exports.readInt64exports['readUInt64' + exports.endianness] = exports.readUInt64exports['writeInt64' + exports.endianness] = exports.writeInt64exports['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] }}
/** * `ref()` accepts a Buffer instance and returns a new Buffer * instance that is "pointer" sized and has its data pointing to the given * Buffer instance. Essentially the created Buffer is a "reference" to the * original pointer, equivalent to the following C code: * * ``` c * char *buf = buffer; * char **ref = &buf; * ``` * * @param {Buffer} buffer A Buffer instance to create a reference to. * @return {Buffer} A new Buffer instance pointing to _buffer_. */
exports.ref = function ref (buffer) { debug('creating a reference to buffer', buffer) var type = exports.refType(exports.getType(buffer)) return exports.alloc(type, buffer)}
/** * Accepts a Buffer instance and attempts to "dereference" it. * That is, first it checks the `indirection` count of _buffer_'s "type", and if * it's greater than __1__ then it merely returns another Buffer, but with one * level less `indirection`. * * When _buffer_'s indirection is at __1__, then it checks for `buffer.type` * which should be an Object with its own `get()` function. * * ``` * var buf = ref.alloc('int', 6); * * var val = ref.deref(buf); * console.log(val); * 6 * ``` * * * @param {Buffer} buffer A Buffer instance to dereference. * @return {?} The returned value after dereferencing _buffer_. */
exports.deref = function deref (buffer) { debug('dereferencing buffer', buffer) return exports.get(buffer)}
/** * Attaches _object_ to _buffer_ such that it prevents _object_ from being garbage * collected until _buffer_ does. * * @param {Buffer} buffer A Buffer instance to attach _object_ to. * @param {Object|Buffer} object An Object or Buffer to prevent from being garbage collected until _buffer_ does. * @api private */
exports._attach = function _attach (buf, obj) { if (!buf._refs) { buf._refs = [] } buf._refs.push(obj)}
/** * Same as `ref.writeObject()`, except that this version does not _attach_ the * Object to the Buffer, which is potentially unsafe if the garbage collector * runs. * * @param {Buffer} buffer A Buffer instance to write _object_ to. * @param {Number} offset The offset on the Buffer to start writing at. * @param {Object} object The Object to be written into _buffer_. * @api private */
exports._writeObject = exports.writeObject
/** * Writes a pointer to _object_ into _buffer_ at the specified _offset. * * This function "attaches" _object_ to _buffer_ to prevent it from being garbage * collected. * * ``` * var buf = ref.alloc('Object'); * ref.writeObject(buf, 0, { foo: 'bar' }); * * ``` * * @param {Buffer} buffer A Buffer instance to write _object_ to. * @param {Number} offset The offset on the Buffer to start writing at. * @param {Object} object The Object to be written into _buffer_. */
exports.writeObject = function writeObject (buf, offset, obj, persistent) { debug('writing Object to buffer', buf, offset, obj, persistent) exports._writeObject(buf, offset, obj, persistent) exports._attach(buf, obj)}
/** * Same as `ref.writePointer()`, except that this version does not attach * _pointer_ to _buffer_, which is potentially unsafe if the garbage collector * runs. * * @param {Buffer} buffer A Buffer instance to write _pointer to. * @param {Number} offset The offset on the Buffer to start writing at. * @param {Buffer} pointer The Buffer instance whose memory address will be written to _buffer_. * @api private */
exports._writePointer = exports.writePointer
/** * Writes the memory address of _pointer_ to _buffer_ at the specified _offset_. * * This function "attaches" _object_ to _buffer_ to prevent it from being garbage * collected. * * ``` * var someBuffer = new Buffer('whatever'); * var buf = ref.alloc('pointer'); * ref.writePointer(buf, 0, someBuffer); * ``` * * @param {Buffer} buffer A Buffer instance to write _pointer to. * @param {Number} offset The offset on the Buffer to start writing at. * @param {Buffer} pointer The Buffer instance whose memory address will be written to _buffer_. */
exports.writePointer = function writePointer (buf, offset, ptr) { debug('writing pointer to buffer', buf, offset, ptr) exports._writePointer(buf, offset, ptr) exports._attach(buf, ptr)}
/** * Same as `ref.reinterpret()`, except that this version does not attach * _buffer_ to the returned Buffer, which is potentially unsafe if the * garbage collector runs. * * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of. * @param {Number} size The `length` property of the returned Buffer. * @param {Number} offset The offset of the Buffer to begin from. * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and the requested _size_. * @api private */
exports._reinterpret = exports.reinterpret
/** * Returns a new Buffer instance with the specified _size_, with the same memory * address as _buffer_. * * This function "attaches" _buffer_ to the returned Buffer to prevent it from * being garbage collected. * * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of. * @param {Number} size The `length` property of the returned Buffer. * @param {Number} offset The offset of the Buffer to begin from. * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and the requested _size_. */
exports.reinterpret = function reinterpret (buffer, size, offset) { debug('reinterpreting buffer to "%d" bytes', size) var rtn = exports._reinterpret(buffer, size, offset || 0) exports._attach(rtn, buffer) return rtn}
/** * Same as `ref.reinterpretUntilZeros()`, except that this version does not * attach _buffer_ to the returned Buffer, which is potentially unsafe if the * garbage collector runs. * * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of. * @param {Number} size The number of sequential, aligned `NULL` bytes that are required to terminate the buffer. * @param {Number} offset The offset of the Buffer to begin from. * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and a variable `length` that is terminated by _size_ NUL bytes. * @api private */
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: * * ``` * function readCString (buf) { * return ref.reinterpretUntilZeros(buf, 1).toString('utf8') * } * ``` * * This function "attaches" _buffer_ to the returned Buffer to prevent it from * being garbage collected. * * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of. * @param {Number} size The number of sequential, aligned `NULL` bytes are required to terminate the buffer. * @param {Number} offset The offset of the Buffer to begin from. * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and a variable `length` that is terminated by _size_ NUL bytes. */
exports.reinterpretUntilZeros = function reinterpretUntilZeros (buffer, size, offset) { debug('reinterpreting buffer to until "%d" NULL (0) bytes are found', size) var rtn = exports._reinterpretUntilZeros(buffer, size, offset || 0) exports._attach(rtn, buffer) return rtn}
// the built-in "types"var types = exports.types = {}
/** * The `void` type. * * @section types */
types.void = { size: 0 , indirection: 1 , get: function get (buf, offset) { debug('getting `void` type (returns `null`)') return null } , set: function set (buf, offset, val) { debug('setting `void` type (no-op)') }}
/** * The `int8` type. */
types.int8 = { size: exports.sizeof.int8 , indirection: 1 , get: function get (buf, offset) { return buf.readInt8(offset || 0) } , set: function set (buf, offset, val) { if (typeof val === 'string') { val = val.charCodeAt(0) } return buf.writeInt8(val, offset || 0) }}
/** * The `uint8` type. */
types.uint8 = { size: exports.sizeof.uint8 , indirection: 1 , get: function get (buf, offset) { return buf.readUInt8(offset || 0) } , set: function set (buf, offset, val) { if (typeof val === 'string') { val = val.charCodeAt(0) } return buf.writeUInt8(val, offset || 0) }}
/** * The `int16` type. */
types.int16 = { size: exports.sizeof.int16 , indirection: 1 , get: function get (buf, offset) { return buf['readInt16' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeInt16' + exports.endianness](val, offset || 0) }}
/** * The `uint16` type. */
types.uint16 = { size: exports.sizeof.uint16 , indirection: 1 , get: function get (buf, offset) { return buf['readUInt16' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeUInt16' + exports.endianness](val, offset || 0) }}
/** * The `int32` type. */
types.int32 = { size: exports.sizeof.int32 , indirection: 1 , get: function get (buf, offset) { return buf['readInt32' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeInt32' + exports.endianness](val, offset || 0) }}
/** * The `uint32` type. */
types.uint32 = { size: exports.sizeof.uint32 , indirection: 1 , get: function get (buf, offset) { return buf['readUInt32' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeUInt32' + exports.endianness](val, offset || 0) }}
/** * The `int64` type. */
types.int64 = { size: exports.sizeof.int64 , indirection: 1 , get: function get (buf, offset) { return buf['readInt64' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeInt64' + exports.endianness](val, offset || 0) }}
/** * The `uint64` type. */
types.uint64 = { size: exports.sizeof.uint64 , indirection: 1 , get: function get (buf, offset) { return buf['readUInt64' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeUInt64' + exports.endianness](val, offset || 0) }}
/** * The `float` type. */
types.float = { size: exports.sizeof.float , indirection: 1 , get: function get (buf, offset) { return buf['readFloat' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeFloat' + exports.endianness](val, offset || 0) }}
/** * The `double` type. */
types.double = { size: exports.sizeof.double , indirection: 1 , get: function get (buf, offset) { return buf['readDouble' + exports.endianness](offset || 0) } , set: function set (buf, offset, val) { return buf['writeDouble' + exports.endianness](val, offset || 0) }}
/** * The `Object` type. This can be used to read/write regular JS Objects * into raw memory. */
types.Object = { size: exports.sizeof.Object , indirection: 1 , get: function get (buf, offset) { return buf.readObject(offset || 0) } , set: function set (buf, offset, val) { return buf.writeObject(val, offset || 0) }}
/** * The `CString` (a.k.a `"string"`) type. * * 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 * is pointer sized, and points to a some utf8 string data, so we have to create * a 2nd "in-between" buffer. */
types.CString = { size: exports.sizeof.pointer , alignment: exports.alignof.pointer , indirection: 1 , get: function get (buf, offset) { var _buf = exports.readPointer(buf, offset) if (exports.isNull(_buf)) { return null } return exports.readCString(_buf, 0) } , set: function set (buf, offset, val) { var _buf if (Buffer.isBuffer(val)) { _buf = val } else { // assume string _buf = exports.allocCString(val) } return exports.writePointer(buf, offset, _buf) }}
// alias Utf8Stringvar utfstringwarned = falseObject.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. * * Wrapper type around `types.uint8` that accepts/returns `true` or * `false` Boolean JavaScript values. * * @name bool * */
/** * The `byte` type. * * @name byte */
/** * The `char` type. * * @name char */
/** * The `uchar` type. * * @name uchar */
/** * The `short` type. * * @name short */
/** * The `ushort` type. * * @name ushort */
/** * The `int` type. * * @name int */
/** * The `uint` type. * * @name uint */
/** * The `long` type. * * @name long */
/** * The `ulong` type. * * @name ulong */
/** * The `longlong` type. * * @name longlong */
/** * The `ulonglong` type. * * @name ulonglong */
/** * The `size_t` type. * * @name size_t */
// "typedef"s for the variable-sized types;[ 'bool', 'byte', 'char', 'uchar', 'short', 'ushort', 'int', 'uint', 'long', 'ulong', 'longlong', 'ulonglong', 'size_t' ].forEach(function (name) { var unsigned = name === 'bool' || name === 'byte' || name === 'size_t' || name[0] === 'u' var size = exports.sizeof[name] assert(size >= 1 && size <= 8) var typeName = 'int' + (size * 8) if (unsigned) { typeName = 'u' + typeName } var type = exports.types[typeName] assert(type) exports.types[name] = Object.create(type)})
// set the "alignment" property on the built-in typesObject.keys(exports.alignof).forEach(function (name) { if (name === 'pointer') return exports.types[name].alignment = exports.alignof[name] assert(exports.types[name].alignment > 0)})
// make the `bool` type work with JS true/false valuesexports.types.bool.get = (function (_get) { return function get (buf, offset) { return _get(buf, offset) ? true : false }})(exports.types.bool.get)exports.types.bool.set = (function (_set) { return function set (buf, offset, val) { if (typeof val !== 'number') { val = val ? 1 : 0 } return _set(buf, offset, val) }})(exports.types.bool.set)
/*! * Set the `name` property of the types. Used for debugging... */
Object.keys(exports.types).forEach(function (name) { exports.types[name].name = name})
/*! * This `char *` type is used by "allocCString()" above. */
var charPtrType = exports.refType(exports.types.char)
/*! * Set the `type` property of the `NULL` pointer Buffer object. */
exports.NULL.type = exports.types.void
/** * `NULL_POINTER` is a pointer-sized `Buffer` instance pointing to `NULL`. * Conceptually, it's equivalent to the following C code: * * ``` c * char *null_pointer; * null_pointer = NULL; * ``` * * @type Buffer */
exports.NULL_POINTER = exports.ref(exports.NULL)
/** * All these '...' comment blocks below are for the documentation generator. * * @section buffer */
Buffer.prototype.address = function address () { return exports.address(this, 0)}
/** * ... */
Buffer.prototype.hexAddress = function hexAddress () { return exports.hexAddress(this, 0)}
/** * ... */
Buffer.prototype.isNull = function isNull () { return exports.isNull(this, 0)}
/** * ... */
Buffer.prototype.ref = function ref () { return exports.ref(this)}
/** * ... */
Buffer.prototype.deref = function deref () { return exports.deref(this)}
/** * ... */
Buffer.prototype.readObject = function readObject (offset) { return exports.readObject(this, offset)}
/** * ... */
Buffer.prototype.writeObject = function writeObject (obj, offset) { return exports.writeObject(this, offset, obj)}
/** * ... */
Buffer.prototype.readPointer = function readPointer (offset, size) { return exports.readPointer(this, offset, size)}
/** * ... */
Buffer.prototype.writePointer = function writePointer (ptr, offset) { return exports.writePointer(this, offset, ptr)}
/** * ... */
Buffer.prototype.readCString = function readCString (offset) { return exports.readCString(this, offset)}
/** * ... */
Buffer.prototype.writeCString = function writeCString (string, offset, encoding) { return exports.writeCString(this, offset, string, encoding)}
/** * ... */
Buffer.prototype.readInt64BE = function readInt64BE (offset) { return exports.readInt64BE(this, offset)}
/** * ... */
Buffer.prototype.writeInt64BE = function writeInt64BE (val, offset) { return exports.writeInt64BE(this, offset, val)}
/** * ... */
Buffer.prototype.readUInt64BE = function readUInt64BE (offset) { return exports.readUInt64BE(this, offset)}
/** * ... */
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, offset) { return exports.reinterpret(this, size, offset)}
/** * ... */
Buffer.prototype.reinterpretUntilZeros = function reinterpretUntilZeros (size, offset) { return exports.reinterpretUntilZeros(this, size, offset)}
/** * `ref` overwrites the default `Buffer#inspect()` function to include the * hex-encoded memory address of the Buffer instance when invoked. * * This is simply a nice-to-have. * * **Before**: * * ``` js * console.log(new Buffer('ref')); * <Buffer 72 65 66> * ``` * * **After**: * * ``` js * console.log(new Buffer('ref')); * <Buffer@0x103015490 72 65 66> * ``` */
var inspectSym = inspect.custom || 'inspect'Buffer.prototype[inspectSym] = overwriteInspect(Buffer.prototype[inspectSym])
// does SlowBuffer inherit from Buffer? (node >= v0.7.9)if (!(exports.NULL instanceof Buffer)) { debug('extending SlowBuffer\'s prototype since it doesn\'t inherit from Buffer.prototype')
/*! * SlowBuffer convenience methods. */
var SlowBuffer = require('buffer').SlowBuffer
SlowBuffer.prototype.address = Buffer.prototype.address SlowBuffer.prototype.hexAddress = Buffer.prototype.hexAddress SlowBuffer.prototype.isNull = Buffer.prototype.isNull SlowBuffer.prototype.ref = Buffer.prototype.ref SlowBuffer.prototype.deref = Buffer.prototype.deref SlowBuffer.prototype.readObject = Buffer.prototype.readObject SlowBuffer.prototype.writeObject = Buffer.prototype.writeObject SlowBuffer.prototype.readPointer = Buffer.prototype.readPointer SlowBuffer.prototype.writePointer = Buffer.prototype.writePointer SlowBuffer.prototype.readCString = Buffer.prototype.readCString SlowBuffer.prototype.writeCString = Buffer.prototype.writeCString SlowBuffer.prototype.reinterpret = Buffer.prototype.reinterpret SlowBuffer.prototype.reinterpretUntilZeros = Buffer.prototype.reinterpretUntilZeros 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 SlowBuffer.prototype[inspectSym] = overwriteInspect(SlowBuffer.prototype[inspectSym])}
function overwriteInspect (inspect) { if (inspect.name === 'refinspect') { return inspect } else { return function refinspect () { var v = inspect.apply(this, arguments) return v.replace('Buffer', 'Buffer@0x' + this.hexAddress()) } }}