1 // Copyright Joyent, Inc. and other Node contributors.
3 // Permission is hereby granted, free of charge, to any person obtaining a
4 // copy of this software and associated documentation files (the
5 // "Software"), to deal in the Software without restriction, including
6 // without limitation the rights to use, copy, modify, merge, publish,
7 // distribute, sublicense, and/or sell copies of the Software, and to permit
8 // persons to whom the Software is furnished to do so, subject to the
9 // following conditions:
11 // The above copyright notice and this permission notice shall be included
12 // in all copies or substantial portions of the Software.
14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
17 // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
18 // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
19 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
22 var buffer = process.binding('buffer');
23 var smalloc = process.binding('smalloc');
24 var util = require('util');
25 var alloc = smalloc.alloc;
26 var sliceOnto = smalloc.sliceOnto;
27 var kMaxLength = smalloc.kMaxLength;
30 exports.Buffer = Buffer;
31 exports.SlowBuffer = SlowBuffer;
32 exports.INSPECT_MAX_BYTES = 50;
35 Buffer.poolSize = 8 * 1024;
36 var poolSize = Buffer.poolSize;
38 var allocPool = alloc({}, poolSize);
41 function createPool() {
42 poolSize = Buffer.poolSize;
43 allocPool = alloc({}, poolSize);
48 function Buffer(subject, encoding) {
49 if (!util.isBuffer(this))
50 return new Buffer(subject, encoding);
52 if (util.isNumber(subject))
53 this.length = subject > 0 ? Math.floor(subject) : 0;
54 else if (util.isString(subject))
55 this.length = Buffer.byteLength(subject, encoding = encoding || 'utf8');
56 else if (util.isObject(subject))
57 this.length = +subject.length > 0 ? Math.floor(+subject.length) : 0;
59 throw new TypeError('must start with number, buffer, array or string');
61 if (this.length > kMaxLength)
62 throw new RangeError('length > kMaxLength');
64 if (this.length < Buffer.poolSize / 2 && this.length > 0) {
65 if (this.length > poolSize - poolOffset)
67 this.parent = sliceOnto(allocPool,
70 poolOffset + this.length);
71 poolOffset += this.length;
73 alloc(this, this.length);
76 if (!util.isNumber(subject)) {
77 if (util.isString(subject)) {
78 // FIXME: the number of bytes hasn't changed, so why change the length?
79 this.length = this.write(subject, 0, encoding);
81 if (util.isBuffer(subject))
82 subject.copy(this, 0, 0, this.length);
83 else if (util.isNumber(subject.length) || util.isArray(subject))
84 for (var i = 0; i < this.length; i++)
91 function SlowBuffer(length) {
92 length = length >>> 0;
93 if (length > kMaxLength)
94 throw new RangeError('length > kMaxLength');
95 var b = new NativeBuffer(length);
101 // Bypass all checks for instantiating unallocated Buffer required for
102 // Objects created in C++. Significantly faster than calling the Buffer
104 function NativeBuffer(length) {
105 this.length = length;
107 NativeBuffer.prototype = Buffer.prototype;
110 // add methods to Buffer prototype
111 buffer.setupBufferJS(NativeBuffer, internal);
116 Buffer.isBuffer = function isBuffer(b) {
117 return util.isBuffer(b);
121 Buffer.isEncoding = function(encoding) {
122 switch ((encoding + '').toLowerCase()) {
142 Buffer.concat = function(list, length) {
143 if (!util.isArray(list))
144 throw new TypeError('Usage: Buffer.concat(list[, length])');
146 if (util.isUndefined(length)) {
148 for (var i = 0; i < list.length; i++)
149 length += list[i].length;
154 if (length < 0) length = 0;
156 if (list.length === 0)
157 return new Buffer(0);
158 else if (list.length === 1)
161 var buffer = new Buffer(length);
163 for (var i = 0; i < list.length; i++) {
165 buf.copy(buffer, pos);
173 Buffer.byteLength = function(str, enc) {
186 ret = str.length * 2;
189 ret = str.length >>> 1;
192 ret = internal.byteLength(str, enc);
198 // pre-set for values that may exist in the future
199 Buffer.prototype.length = undefined;
200 Buffer.prototype.parent = undefined;
203 // toString(encoding, start=0, end=buffer.length)
204 Buffer.prototype.toString = function(encoding, start, end) {
205 var loweredCase = false;
208 end = util.isUndefined(end) ? this.length : end >>> 0;
210 if (!encoding) encoding = 'utf8';
211 if (start < 0) start = 0;
212 if (end > this.length) end = this.length;
213 if (end <= start) return '';
218 return this.hexSlice(start, end);
222 return this.utf8Slice(start, end);
225 return this.asciiSlice(start, end);
228 return this.binarySlice(start, end);
231 return this.base64Slice(start, end);
237 return this.ucs2Slice(start, end);
241 throw new TypeError('Unknown encoding: ' + encoding);
242 encoding = (encoding + '').toLowerCase();
250 Buffer.prototype.inspect = function inspect() {
252 var max = exports.INSPECT_MAX_BYTES;
253 if (this.length > 0) {
254 str = this.toString('hex', 0, max).match(/.{2}/g).join(' ');
255 if (this.length > max)
258 return '<' + this.constructor.name + ' ' + str + '>';
262 // XXX remove in v0.13
263 Buffer.prototype.get = util.deprecate(function get(offset) {
265 if (offset < 0 || offset >= this.length)
266 throw new RangeError('index out of range');
268 }, '.get() is deprecated. Access using array indexes instead.');
271 // XXX remove in v0.13
272 Buffer.prototype.set = util.deprecate(function set(offset, v) {
274 if (offset < 0 || offset >= this.length)
275 throw new RangeError('index out of range');
276 return this[offset] = v;
277 }, '.set() is deprecated. Set using array indexes instead.');
280 // TODO(trevnorris): fix these checks to follow new standard
281 // write(string, offset = 0, length = buffer.length, encoding = 'utf8')
282 var writeWarned = false;
283 var writeMsg = '.write(string, encoding, offset, length) is deprecated.' +
284 ' Use write(string, offset, length, encoding) instead.';
285 Buffer.prototype.write = function(string, offset, length, encoding) {
286 // allow write(string, encoding)
287 if (util.isString(offset) && util.isUndefined(length)) {
291 // allow write(string, offset[, length], encoding)
292 } else if (isFinite(offset)) {
294 if (isFinite(length)) {
301 // XXX legacy write(string, encoding, offset, length) - remove in v0.13
304 if (process.throwDeprecation)
305 throw new Error(writeMsg);
306 else if (process.traceDeprecation)
307 console.trace(writeMsg);
309 console.error(writeMsg);
319 var remaining = this.length - offset;
320 if (util.isUndefined(length) || length > remaining)
323 encoding = !!encoding ? (encoding + '').toLowerCase() : 'utf8';
325 if (string.length > 0 && (length < 0 || offset < 0))
326 throw new RangeError('attempt to write beyond buffer bounds');
331 ret = this.hexWrite(string, offset, length);
336 ret = this.utf8Write(string, offset, length);
340 ret = this.asciiWrite(string, offset, length);
344 ret = this.binaryWrite(string, offset, length);
348 // Warning: maxLength not taken into account in base64Write
349 ret = this.base64Write(string, offset, length);
356 ret = this.ucs2Write(string, offset, length);
360 throw new TypeError('Unknown encoding: ' + encoding);
367 Buffer.prototype.toJSON = function() {
370 data: Array.prototype.slice.call(this, 0)
375 // TODO(trevnorris): currently works like Array.prototype.slice(), which
376 // doesn't follow the new standard for throwing on out of range indexes.
377 Buffer.prototype.slice = function(start, end) {
378 var len = this.length;
380 end = util.isUndefined(end) ? len : ~~end;
386 } else if (start > len) {
394 } else if (end > len) {
401 var buf = new NativeBuffer();
402 sliceOnto(this, buf, start, end);
403 buf.length = end - start;
405 buf.parent = util.isUndefined(this.parent) ? this : this.parent;
411 function checkOffset(offset, ext, length) {
412 if (offset < 0 || offset + ext > length)
413 throw new RangeError('index out of range');
417 Buffer.prototype.readUInt8 = function(offset, noAssert) {
420 checkOffset(offset, 1, this.length);
425 function readUInt16(buffer, offset, isBigEndian) {
428 val = buffer[offset] << 8;
429 val |= buffer[offset + 1];
431 val = buffer[offset];
432 val |= buffer[offset + 1] << 8;
438 Buffer.prototype.readUInt16LE = function(offset, noAssert) {
441 checkOffset(offset, 2, this.length);
442 return readUInt16(this, offset, false, noAssert);
446 Buffer.prototype.readUInt16BE = function(offset, noAssert) {
449 checkOffset(offset, 2, this.length);
450 return readUInt16(this, offset, true, noAssert);
454 function readUInt32(buffer, offset, isBigEndian) {
457 val = buffer[offset + 1] << 16;
458 val |= buffer[offset + 2] << 8;
459 val |= buffer[offset + 3];
460 val = val + (buffer[offset] << 24 >>> 0);
462 val = buffer[offset + 2] << 16;
463 val |= buffer[offset + 1] << 8;
464 val |= buffer[offset];
465 val = val + (buffer[offset + 3] << 24 >>> 0);
471 Buffer.prototype.readUInt32LE = function(offset, noAssert) {
474 checkOffset(offset, 4, this.length);
475 return readUInt32(this, offset, false);
479 Buffer.prototype.readUInt32BE = function(offset, noAssert) {
482 checkOffset(offset, 4, this.length);
483 return readUInt32(this, offset, true);
488 * Signed integer types, yay team! A reminder on how two's complement actually
489 * works. The first bit is the signed bit, i.e. tells us whether or not the
490 * number should be positive or negative. If the two's complement value is
491 * positive, then we're done, as it's equivalent to the unsigned representation.
493 * Now if the number is positive, you're pretty much done, you can just leverage
494 * the unsigned translations and return those. Unfortunately, negative numbers
495 * aren't quite that straightforward.
497 * At first glance, one might be inclined to use the traditional formula to
498 * translate binary numbers between the positive and negative values in two's
499 * complement. (Though it doesn't quite work for the most negative value)
501 * - invert all the bits
502 * - add one to the result
504 * Of course, this doesn't quite work in Javascript. Take for example the value
505 * of -128. This could be represented in 16 bits (big-endian) as 0xff80. But of
506 * course, Javascript will do the following:
511 * Whoh there, Javascript, that's not quite right. But wait, according to
512 * Javascript that's perfectly correct. When Javascript ends up seeing the
513 * constant 0xff80, it has no notion that it is actually a signed number. It
514 * assumes that we've input the unsigned value 0xff80. Thus, when it does the
515 * binary negation, it casts it into a signed value, (positive 0xff80). Then
516 * when you perform binary negation on that, it turns it into a negative number.
518 * Instead, we're going to have to use the following general formula, that works
519 * in a rather Javascript friendly way. I'm glad we don't support this kind of
520 * weird numbering scheme in the kernel.
522 * (BIT-MAX - (unsigned)val + 1) * -1
524 * The astute observer, may think that this doesn't make sense for 8-bit numbers
525 * (really it isn't necessary for them). However, when you get 16-bit numbers,
526 * you do. Let's go back to our prior example and see how this will look:
528 * (0xffff - 0xff80 + 1) * -1
533 Buffer.prototype.readInt8 = function(offset, noAssert) {
536 checkOffset(offset, 1, this.length);
537 if (!(this[offset] & 0x80))
538 return (this[offset]);
539 return ((0xff - this[offset] + 1) * -1);
543 function readInt16(buffer, offset, isBigEndian) {
544 var val = readUInt16(buffer, offset, isBigEndian);
547 return (0xffff - val + 1) * -1;
551 Buffer.prototype.readInt16LE = function(offset, noAssert) {
554 checkOffset(offset, 2, this.length);
555 return readInt16(this, offset, false);
559 Buffer.prototype.readInt16BE = function(offset, noAssert) {
562 checkOffset(offset, 2, this.length);
563 return readInt16(this, offset, true);
567 function readInt32(buffer, offset, isBigEndian) {
568 var val = readUInt32(buffer, offset, isBigEndian);
569 if (!(val & 0x80000000))
571 return (0xffffffff - val + 1) * -1;
575 Buffer.prototype.readInt32LE = function(offset, noAssert) {
578 checkOffset(offset, 4, this.length);
579 return readInt32(this, offset, false);
583 Buffer.prototype.readInt32BE = function(offset, noAssert) {
586 checkOffset(offset, 4, this.length);
587 return readInt32(this, offset, true);
591 function checkInt(buffer, value, offset, ext, max, min) {
592 if (value > max || value < min)
593 throw new TypeError('value is out of bounds');
594 if (offset < 0 || offset + ext > buffer.length || buffer.length + offset < 0)
595 throw new RangeError('index out of range');
599 Buffer.prototype.writeUInt8 = function(value, offset, noAssert) {
603 checkInt(this, value, offset, 1, 0xff, 0);
604 this[offset] = value;
609 function writeUInt16(buffer, value, offset, isBigEndian) {
611 buffer[offset] = (value & 0xff00) >>> 8;
612 buffer[offset + 1] = value & 0x00ff;
614 buffer[offset + 1] = (value & 0xff00) >>> 8;
615 buffer[offset] = value & 0x00ff;
621 Buffer.prototype.writeUInt16LE = function(value, offset, noAssert) {
625 checkInt(this, value, offset, 2, 0xffff, 0);
626 return writeUInt16(this, value, offset, false);
630 Buffer.prototype.writeUInt16BE = function(value, offset, noAssert) {
634 checkInt(this, value, offset, 2, 0xffff, 0);
635 return writeUInt16(this, value, offset, true);
639 function writeUInt32(buffer, value, offset, isBigEndian) {
641 buffer[offset] = (value >>> 24) & 0xff;
642 buffer[offset + 1] = (value >>> 16) & 0xff;
643 buffer[offset + 2] = (value >>> 8) & 0xff;
644 buffer[offset + 3] = value & 0xff;
646 buffer[offset + 3] = (value >>> 24) & 0xff;
647 buffer[offset + 2] = (value >>> 16) & 0xff;
648 buffer[offset + 1] = (value >>> 8) & 0xff;
649 buffer[offset] = value & 0xff;
655 Buffer.prototype.writeUInt32LE = function(value, offset, noAssert) {
659 checkInt(this, value, offset, 4, 0xffffffff, 0);
660 return writeUInt32(this, value, offset, false);
664 Buffer.prototype.writeUInt32BE = function(value, offset, noAssert) {
668 checkInt(this, value, offset, 4, 0xffffffff, 0);
669 return writeUInt32(this, value, offset, true);
674 * We now move onto our friends in the signed number category. Unlike unsigned
675 * numbers, we're going to have to worry a bit more about how we put values into
676 * arrays. Since we are only worrying about signed 32-bit values, we're in
677 * slightly better shape. Unfortunately, we really can't do our favorite binary
678 * & in this system. It really seems to do the wrong thing. For example:
683 * What's happening above is really: 0xe0 & 0xff = 0xe0. However, the results of
684 * this aren't treated as a signed number. Ultimately a bad thing.
686 * What we're going to want to do is basically create the unsigned equivalent of
687 * our representation and pass that off to the wuint* functions. To do that
688 * we're going to do the following:
690 * - if the value is positive
691 * we can pass it directly off to the equivalent wuint
692 * - if the value is negative
693 * we do the following computation:
694 * mb + val + 1, where
695 * mb is the maximum unsigned value in that byte size
696 * val is the Javascript negative integer
699 * As a concrete value, take -128. In signed 16 bits this would be 0xff80. If
700 * you do out the computations:
706 * You can then encode this value as the signed version. This is really rather
707 * hacky, but it should work and get the job done which is our goal here.
710 Buffer.prototype.writeInt8 = function(value, offset, noAssert) {
714 checkInt(this, value, offset, 1, 0x7f, -0x80);
715 if (value < 0) value = 0xff + value + 1;
716 this[offset] = value;
721 Buffer.prototype.writeInt16LE = function(value, offset, noAssert) {
725 checkInt(this, value, offset, 2, 0x7fff, -0x8000);
726 if (value < 0) value = 0xffff + value + 1;
727 return writeUInt16(this, value, offset, false);
731 Buffer.prototype.writeInt16BE = function(value, offset, noAssert) {
735 checkInt(this, value, offset, 2, 0x7fff, -0x8000);
736 if (value < 0) value = 0xffff + value + 1;
737 return writeUInt16(this, value, offset, true);
741 Buffer.prototype.writeInt32LE = function(value, offset, noAssert) {
745 checkInt(this, value, offset, 4, 0x7fffffff, -0x80000000);
746 if (value < 0) value = 0xffffffff + value + 1;
747 return writeUInt32(this, value, offset, false);
751 Buffer.prototype.writeInt32BE = function(value, offset, noAssert) {
755 checkInt(this, value, offset, 4, 0x7fffffff, -0x80000000);
756 if (value < 0) value = 0xffffffff + value + 1;
757 return writeUInt32(this, value, offset, true);