一起读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') into 0x20 (character code of a space). If you want to convert a null character into 0x00, 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 of Buffer objects 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)

• obj Object 一个对象
• Return: Boolean 返回布尔值

    测试obj是否是一个Buffer类.

    Class Method:Buffer.isBuffer(obj)

• string String 一个字符串
• encoding String, Optional, Default: 'utf8' 编码,可选,默认'utf8'
• Return: Number 返回一个数字

    给出一个字符串的实际的字节长度.encoding默认:'utf8'.这个方法和string.prototype.length不同,后者返回一个字符串中字符的个数.

    例子:

str = '\u00bd + \u00bc = \u00be';

console.log(str + ": " + str.length + " characters, " +
  Buffer.byteLength(str, 'utf8') + " bytes");

// ½ + ¼ = ¾: 9 characters, 12 bytes

    Class Method:Buffer.concat(list,[totalLength])

• list Array List of Buffer objects to concat 一个数组,需要连接的buffer对象的一个数组.
• totalLength Number Total length of the buffers when concatenated 这个连接后的beffer对象的总长度.

    返回一个连接了整个list的buffer对象.

    如果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])

• targetBuffer Buffer object - Buffer to copy into 复制的目标buffer对象
• targetStart Number, Optional, Default: 0 在目标buffer的哪个位置开始写入
• sourceStart Number, Optional, Default: 0在原buffer的哪个位置开始读取
• sourceEnd Number, Optional, Default: buffer.length原buffer读取到哪里结束.

    在两个buffer对象之间做copy工作.原区域和目标区域可以重叠.targetStart和sourceStart默认是0,sourceEnd默认是原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])

• start Number, Optional, Default: 0 开始位置,默认0
• end Number, Optional, Default: buffer.length 结束位置,默认buffer大小.

    返回一个新的buffer对象,这个新buffer和老buffer公用一个内存.但是被start和end索引偏移缩减了.(比如,一个buffer里有1到10个字节,我们只想要4-8个字节,就可以用这个函数buf.slice(4,8),因为他们共用一个内存,所以不会消耗内存,)

    修改新的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])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的指定offset处返回一个无符号的8bit integer类型.

    设置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])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处使用指定的字节序列(le和be)返回一个无符号16bit的integer.

    设置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])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处使用指定的字节序列(le和be)返回一个无符号32bit的integer.

    设置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])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处返回一个有符号8bit的integer.

    设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.

    除了buffer的内容被看作是有正负符号的值之外,和buffer.readUInt8一样的功能.

   buf.rendInt16LE(offset,[noAssert])

   buf.rendInt16BE(offset,[noAssert])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处使用指定的字节序列(le和be)返回一个有符号16bit的integer.

    设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.

    除了buffer的内容被看作是有正负符号的值之外,和buffer.readUInt16*一样的功能.

   buf.rendInt32LE(offset,[noAssert])

   buf.rendInt32BE(offset,[noAssert])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处使用指定的字节序列(le和be)返回一个有符号32bit的integer.

    设置noAssert为true,来忽略对offset的验证.这意味着offset可以超过buffer的边界.默认为false.

    除了buffer的内容被看作是有正负符号的值之外,和buffer.readUInt32*一样的功能.

   buf.rendFloatLE(offset,[noAssert])

   buf.rendFloatBE(offset,[noAssert])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处使用指定的字节序列(le和be)返回一个有符号32bit的float.

    设置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])

• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.
• Return: Number 返回数字

    在buffer的offset处使用指定的字节序列(le和be)返回一个有符号64bit的double.

    设置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 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处写入value.注意vlaue必须是一个有效无符号的8bit integer.

    设置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 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处使用指定的字节序列(le和be)写入value.注意vlaue必须是一个有效无符号的16bit integer.

    设置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 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处使用指定的字节序列(le和be)写入value.注意vlaue必须是一个有效无符号的32bit integer.

    设置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 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处写入value.注意vlaue必须是一个有效有符号的8bit integer.

    设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.

    除非你确定正确,否则不要使用它.默认为false.

    除了buffer中被写入的内容被看作是有正负符号的值之外,和buffer.writeUInt8一样的功能.

   buf.writerInt16LE(value,offset,[noAssert])

   buf.writerInt16BE(value,offset,[noAssert])

• value Number 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处写入value.注意vlaue必须是一个有效有符号的16bit integer.

    设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.

    除非你确定正确,否则不要使用它.默认为false.

    除了buffer中被写入的内容被看作是有正负符号的值之外,和buffer.writeUInt16*一样的功能.

   buf.writerInt32LE(value,offset,[noAssert])

   buf.writerInt32BE(value,offset,[noAssert])

• value Number 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处写入value.注意vlaue必须是一个有效有符号的32bit integer.

    设置noAssert为true来忽略value和offset的验证.这意味着,value可能太大,offset可能越界,而导致value值的丢失.

    除非你确定正确,否则不要使用它.默认为false.

    除了buffer中被写入的内容被看作是有正负符号的值之外,和buffer.writeUInt32*一样的功能.

   buf.writerFloatLE(value,offset,[noAssert])

   buf.writerFloatBE(value,offset,[noAssert])

• value Number 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处写入value.注意vlaue必须是一个有效有符号的32bit float.

    设置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 数字
• offset Number 偏移量
• noAssert Boolean, Optional, Default: false 是否忽略offset验证,offset可能超出范围.

    在buffer的offset处写入value.注意vlaue必须是一个有效有符号的64bit double.

    设置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 要填充的值
• offset Number, Optional 偏移量,可选 默认0
• end Number, Optional 结束位置 可选.默认buffer大小

   使用指定的value来填充buffer.如果offset和end没有指定,将会默认填充整个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大小的块返回.