一起读nodejs(九)----缓存类(Buffer)
本文是对nodejs0.8.9版本的api开发手册解读.nodejs网址
缓存类(Buffer)
stability:3 - Stable
纯javascript对Unicode支持不叫不错,但是对二进制数据的支持就不怎么样了,当需要处理TCP流或者文件系统时,是必须要处理八进制流(octet streams).Node有几种策略来操作,创建,销毁八进制值流.
原始数据被储存在buffer类的实例中,一个buffer很想一个integer的数组,但是符合一个在v8堆栈外的原始内存分配.一个buffer是不能被改变大小的.
buffer类是全局的,尽量不要一有需要就使用require('buffer')加载.
在buffers和javascript string对象之间转换需要显示的调用一个编码函数.下面是string类型不懂的编码格式:
-
'ascii'- for 7 bit ASCII data only. This encoding method is very fast, and will strip the high bit if set. Note that this encoding converts a null character ('\0'or'\u0000') into0x20(character code of a space). If you want to convert a null character into0x00, you should use'utf8'. -
'utf8'- Multibyte encoded Unicode characters. Many web pages and other document formats use UTF-8.多字节编码的Unicode字符.很多web页面和其他文档都使用UTF-8格式. -
'utf16le'- 2 or 4 bytes, little endian encoded Unicode characters. Surrogate pairs (U+10000 to U+10FFFF) are supported.2个或者4个字节,小字节编码的Unicode字符.代理对的支持范围是10000~10FFFF. -
'ucs2'- Alias of'utf16le'.utf16le的别名 -
'base64'- Base64 string encoding.基于64的字符串编码. -
'binary'- A way of encoding raw binary data into strings by using only the first 8 bits of each character. This encoding method is deprecated and should be avoided in favor ofBufferobjects where possible. This encoding will be removed in future versions of Node.一种仅使用每个字符的前8个字节把原始二进制数据编码成strings.这个方法已经过时,应该避免在使用buffer对象时使用,这种编码将会来未来的node版本中被移除. -
'hex'- Encode each byte as two hexadecimal characters.将每一个字节编码称两个16进制字符.
Class:Buffer
Buffer类是一个直接处理二进制数据的全局类型.它可以通过多重方法被构造.
new Buffer(size)
- size number,一个表示大小的数字.
分配一个新的buffer,size个八位字节(octets).
new Buffer(array)
- array Array,一个数组.
使用一个octets的array数组来分配一个新的buffer.
new Buffer(str,[encoding])
- str String,需要编码的字符串.
- encoding String,需要使用的编码格式,可选.
分配一个新的buffer,包含给定的str,encoding默认为"utf8".
buf.write(string,[offset],[length],[encoding])
- str String,被写入buffer的数据.
- offet number,可选,默认0.数据写入到buffer的位置.
- length Number,可选,默认:buffer.length - offset,要写入数据的长度
- encoding String,需要使用的编码格式,可选,默认为"utf8".
将string使用指定的encoding写入到buffer的offset处.offset默认是0,encomding默认是'utf8',length是将要写入的字节长度.返回写入了多少个八进制字节.如果Buffer没有足够的空间来适应整个string,那么将只有string的部分被写入.length默认是buffer.length - offset.这个方法不会写入不完整的字符.
buf = new Buffer(256);
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));
写入的字符个数(可能和写入的字节数不一样)被保存在Buffer._charWritten变量中,并且将会在下次调用buf.writer()时被覆盖.
buf.toString([encoding],[start],[end])
- encoding String,optional,default:'uft8' .字符串,可选,默认:'utf8'
- start Number ,optional,default:0.数字,可选,默认:0.
- end Number,optional,default:buffer.length.数字,可选,默认:buffer.length
解码buffer中的数据,并且返回一个字符串,使用encoding(默认:'utf8')编码,在start开始,在end结束.
见上面的buffer.write()例子.
buf[index]
设置和获取在index位置的八进制字节.这个值索引了一个实体bytes,所以这个合法的范围是)0x00到0xff或者0到255.
例子:copy一个ASCII字符串到buffer中,一次一个字节:
str = "node.js";
buf = new Buffer(str.length);
for (var i = 0; i < str.length ; i++) {
buf[i] = str.charCodeAt(i);
}
console.log(buf);
// node.js
Class Method:Buffer.isBuffer(obj)
objObject 一个对象- Return: Boolean 返回布尔值
Class Method:Buffer.isBuffer(obj)
stringString 一个字符串encodingString, Optional, Default: 'utf8' 编码,可选,默认'utf8'- Return: Number 返回一个数字
例子:
Class Method:Buffer.concat(list,[totalLength])str = '\u00bd + \u00bc = \u00be';
console.log(str + ": " + str.length + " characters, " +
Buffer.byteLength(str, 'utf8') + " bytes");
// ½ + ¼ = ¾: 9 characters, 12 bytes
listArrayList of Buffer objects to concat 一个数组,需要连接的buffer对象的一个数组.totalLengthNumberTotal length of the buffers when concatenated 这个连接后的beffer对象的总长度.
如果list中没有条目,或者totallength是0,那么将返回一个0长度的buffer.
如果List中只有一个条目,那么list中的这个条目将被直接返回.
如果list中多于一个条目,那么一个衅新的Buffer将会被创建.
如果totalLength没有被提供,将会从list中的buffer对象中读取.然而这将会增加一个额外的循环到这个方法,所以明确的提供长度有更高的效率.
buf.length
- Number数字
这个buf的字节大小.注意:这不一定是buf中保存的内容的大小.length索引的是buffer对象的分配内存的总大小.当buf的content改变时length不会变.
buf = new Buffer(1234);
console.log(buf.length);
buf.write("some string", 0, "ascii");
console.log(buf.length);
// 1234
// 1234
buf.copy(targetBuffer,[targetStart],[sourceStart],[sourceEnd])
targetBufferBuffer object - Buffer to copy into 复制的目标buffer对象targetStartNumber, Optional, Default: 0 在目标buffer的哪个位置开始写入sourceStartNumber, Optional, Default: 0在原buffer的哪个位置开始读取sourceEndNumber, Optional, Default:buffer.length原buffer读取到哪里结束.
例子:创建两个buffer,然后copy buf1中的字节16到字节19的区域到buf2,buf2从第八个字节开始写入.
buf1 = new Buffer(26);
buf2 = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) {
buf1[i] = i + 97; // 97 is ASCII a
buf2[i] = 33; // ASCII !
}
buf1.copy(buf2, 8, 16, 20);
console.log(buf2.toString('ascii', 0, 25));
// !!!!!!!!qrst!!!!!!!!!!!!!
buf.slice([start],[end])
startNumber, Optional, Default: 0 开始位置,默认0endNumber, Optional, Default:buffer.length 结束位置,默认buffer大小.
修改新的buffer,老buffer的内容同样也会被修改,(因为共用内存嘛).
例子:用ASCII码字母表创建一个buffer,用一下slice函数,然后修改原buffer中的一个字节.
var buf1 = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) {
buf1[i] = i + 97; // 97 is ASCII a
}
var buf2 = buf1.slice(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));
// abc
// !bc
buf.rendUInt8(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
例子:
var buf = new Buffer(4);
buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;
for (ii = 0; ii < buf.length; ii++) {
console.log(buf.readUInt8(ii));
}
// 0x3
// 0x4
// 0x23
// 0x42
buf.rendUInt16LE(offset,[noAssert])
buf.rendUInt16BE(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
例子:
var buf = new Buffer(4);
buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;
console.log(buf.readUInt16BE(0));
console.log(buf.readUInt16LE(0));
console.log(buf.readUInt16BE(1));
console.log(buf.readUInt16LE(1));
console.log(buf.readUInt16BE(2));
console.log(buf.readUInt16LE(2));
// 0x0304
// 0x0403
// 0x0423
// 0x2304
// 0x2342
// 0x4223
buf.rendUInt32LE(offset,[noAssert])
buf.rendUInt32BE(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
例子:
var buf = new Buffer(4);
buf[0] = 0x3;
buf[1] = 0x4;
buf[2] = 0x23;
buf[3] = 0x42;
console.log(buf.readUInt32BE(0));
console.log(buf.readUInt32LE(0));
// 0x03042342
// 0x42230403
buf.rendInt8(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
除了buffer的内容被看作是有正负符号的值之外,和buffer.readUInt8一样的功能.
buf.rendInt16LE(offset,[noAssert])
buf.rendInt16BE(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
除了buffer的内容被看作是有正负符号的值之外,和buffer.readUInt16*一样的功能.
buf.rendInt32LE(offset,[noAssert])
buf.rendInt32BE(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
除了buffer的内容被看作是有正负符号的值之外,和buffer.readUInt32*一样的功能.
buf.rendFloatLE(offset,[noAssert])
buf.rendFloatBE(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
例子:
var buf = new Buffer(4);
buf[0] = 0x00;
buf[1] = 0x00;
buf[2] = 0x80;
buf[3] = 0x3f;
console.log(buf.readFloatLE(0));
// 0x01
buf.rendDoubleLE(offset,[noAssert])
buf.rendDoubleBE(offset,[noAssert])
offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.- Return: Number 返回数字
设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.
例子:
var buf = new Buffer(8);
buf[0] = 0x55;
buf[1] = 0x55;
buf[2] = 0x55;
buf[3] = 0x55;
buf[4] = 0x55;
buf[5] = 0x55;
buf[6] = 0xd5;
buf[7] = 0x3f;
console.log(buf.readDoubleLE(0));
// 0.3333333333333333
buf.writerUInt8(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
例子:
var buf = new Buffer(4);
buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);
console.log(buf);
// <Buffer 03 04 23 42>
buf.writerUInt16LE(value,offset,[noAssert])
buf.writerUInt16BE(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
例子:
var buf = new Buffer(4);
buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);
console.log(buf);
buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);
console.log(buf);
// <Buffer de ad be ef>
// <Buffer ad de ef be>
buf.writerUInt32LE(value,offset,[noAssert])
buf.writerUInt32BE(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
例子:
var buf = new Buffer(4);
buf.writeUInt32BE(0xfeedface, 0);
console.log(buf);
buf.writeUInt32LE(0xfeedface, 0);
console.log(buf);
// <Buffer fe ed fa ce>
// <Buffer ce fa ed fe>
buf.writerInt8(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
除了buffer中被写入的内容被看作是有正负符号的值之外,和buffer.writeUInt8一样的功能.
buf.writerInt16LE(value,offset,[noAssert])
buf.writerInt16BE(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
除了buffer中被写入的内容被看作是有正负符号的值之外,和buffer.writeUInt16*一样的功能.
buf.writerInt32LE(value,offset,[noAssert])
buf.writerInt32BE(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
除了buffer中被写入的内容被看作是有正负符号的值之外,和buffer.writeUInt32*一样的功能.
buf.writerFloatLE(value,offset,[noAssert])
buf.writerFloatBE(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
例子:
var buf = new Buffer(4);
buf.writeFloatBE(0xcafebabe, 0);
console.log(buf);
buf.writeFloatLE(0xcafebabe, 0);
console.log(buf);
// <Buffer 4f 4a fe bb>
// <Buffer bb fe 4a 4f>
buf.writerDoubleLE(value,offset,[noAssert])
buf.writerDoubleBE(value,offset,[noAssert])
value Number 数字offsetNumber 偏移量noAssertBoolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.
除非你确定正确,否则不要使用它.默认为false.
例子:
var buf = new Buffer(8);
buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
console.log(buf);
buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
console.log(buf);
// <Buffer 43 eb d5 b7 dd f9 5f d7>
// <Buffer d7 5f f9 dd b7 d5 eb 43>
buf.fill(value,[offset],[end])
value 要填充的值offsetNumber, Optional 偏移量,可选 默认0endNumber, Optional 结束位置 可选.默认buffer大小
var b = new Buffer(50);
b.fill("h");
buf.INSPECT_MAX_BYTES
- Number, Default: 50,数字,默认50.
当buffer.inspect()被调用时返回的字节数.这个可以被用户模块重写.
注意,这是一个通过require('buffer')获得的buffer模块的一个属性,不是全局的Buffer的一个属性,也不是一个buffer实例的属性.
Class:SlowBuffer
这个类主要是内部使用.javascript程序应该使用buffer来代替SlowBuffer.
为了避免在一个服务器中分配小模块内存的c++buffer对象的数量瓶颈.node分配的内存块一个8kb,如果一个buffer小于这个8kb,那么他将会是一个SlowBuffer的子类.如果大于8kb,node将会直接分配一个slowBuffer大小的块返回.