Node.js Buffer (búfer)

El lenguaje JavaScript solo tiene tipos de datos de cadena, no tiene tipos de datos binarios.

La clase Buffer en Node.js es una herramienta central para manejar datos binarios y proporciona operaciones eficientes sobre ellos.

La clase Buffer es especialmente útil en escenarios como operaciones con archivos, comunicación de red, procesamiento de imágenes, entre otros.

Características:

• Datos binarios：BufferUn objeto es una matriz de tamaño fijo que contiene datos binarios sin procesar. Cada elemento ocupa un byte (8 bits), por lo tantoBufferAdecuado para procesar datos binarios, como contenido de archivos, paquetes de red, etc.
• Inmutabilidad: aunqueBufferEl contenido de un objeto se puede modificar después de su creación, pero su longitud es fija y no se puede cambiar dinámicamente.

Buffer y codificación de caracteres

Las instancias de Buffer generalmente se utilizan para representar secuencias de caracteres codificados, como datos codificados en UTF-8, UCS2, Base64 o hexadecimal. Mediante el uso de una codificación de caracteres explícita, se puede realizar la conversión mutua entre instancias de Buffer y cadenas de JavaScript normales.

Las codificaciones de caracteres compatibles actualmente con Node.js incluyen:

• ascii- Solo admite datos ASCII de 7 bits. Si se elimina el bit alto, esta codificación es muy rápida.

• utf8- Caracteres Unicode codificados en multibyte. Muchas páginas web y otros formatos de documentos utilizan UTF-8.

• utf16le- Caracteres Unicode codificados en 2 o 4 bytes, en orden de bytes little-endian. Admite pares sustitutos (U+10000 a U+10FFFF).

• ucs2 - utf16lealias de.

• base64- Codificación Base64.

• latin1- Una forma deBuffercodificar en una cadena codificada en un byte.

• binary - latin1alias de.

• hex- Codifica cada byte como dos caracteres hexadecimales.

Crear la clase Buffer

Buffer proporciona la siguiente API para crear la clase Buffer:

• Buffer.alloc(size[, fill[, encoding]])：Crea un Buffer de longitud size bytes, equivalente a solicitar un espacio de memoria de size bytes, donde cada byte tiene el valor 0.
• Buffer.allocUnsafe(size)：Crea un Buffer de longitud size bytes, pero el Buffer puede contener datos antiguos, lo que puede afectar el resultado de la ejecución, por lo que se llama unsafe.
• Buffer.allocUnsafeSlow(size)：Se utiliza para asignar una nueva instancia de Buffer de tamaño size dado, pero no la inicializa.
• Buffer.from(array)：Devuelve una nueva instancia de Buffer inicializada con los valores de array (los elementos del array pasado solo pueden ser números, de lo contrario se sobrescriben automáticamente con 0).
• Buffer.from(arrayBuffer[, byteOffset[, length]])：Devuelve un nuevo Buffer que comparte la misma memoria con el ArrayBuffer dado.
• Buffer.from(buffer)：Copia los datos de la instancia de Buffer pasada y devuelve una nueva instancia de Buffer.
• Buffer.from(string[, encoding])：Crea un Buffer a partir de una cadena; se puede especificar la codificación, cuyo valor predeterminado es UTF-8.

Escribir en el búfer

Sintaxis

La sintaxis para escribir en un búfer de Node es la siguiente:

buf.write(string[, offset[, length]][, encoding])

Parámetros

Los parámetros se describen a continuación:

• string- La cadena que se escribe en el búfer.

• offset- El índice donde el búfer comienza a escribir; por defecto es 0.

• length- El número de bytes a escribir; por defecto es buffer.length

• encoding- La codificación utilizada. Por defecto es 'utf8'.

Escribe string en buf en la posición offset según la codificación de caracteres encoding. El parámetro length es el número de bytes a escribir. Si buf no tiene suficiente espacio para almacenar toda la cadena, solo se escribirá una parte de string. Los caracteres solo parcialmente decodificados no se escribirán.

Valor de retorno

Devuelve el tamaño realmente escrito. Si el espacio del búfer es insuficiente, solo se escribirá parte de la cadena.

Ejemplo

buf = Buffer.alloc(256);
len = buf.write("www.example.com");

console.log("写入字节数 : "+  len);

Al ejecutar el código anterior, el resultado es:

$node main.js
写入字节数 : 14

Leer datos del búfer

Sintaxis

La sintaxis para leer datos de un búfer de Node es la siguiente:

buf.toString([encoding[, start[, end]]])

Parámetros

Los parámetros se describen a continuación:

• encoding- La codificación utilizada. Por defecto es 'utf8'.

• start- Especifica la posición de índice donde comienza la lectura; por defecto es 0.

• end- La posición final; por defecto es el final del búfer.

Valor de retorno

Decodifica los datos del búfer y devuelve una cadena utilizando la codificación especificada.

Ejemplo

buf = Buffer.alloc(26);
for (var i = 0 ; i < 26 ; i++) {
  buf[i] = i + 97;
}

console.log( buf.toString('ascii'));       // 输出: abcdefghijklmnopqrstuvwxyz
console.log( buf.toString('ascii',0,5));   //使用 'ascii' 编码, 并输出: abcde
console.log( buf.toString('utf8',0,5));    // 使用 'utf8' 编码, 并输出: abcde
console.log( buf.toString(undefined,0,5)); // 使用默认的 'utf8' 编码, 并输出: abcde

Al ejecutar el código anterior, el resultado es:

$ node main.js
abcdefghijklmnopqrstuvwxyz
abcde
abcde
abcde

Convertir Buffer a objeto JSON

Sintaxis

El formato de sintaxis de la función para convertir un Buffer de Node a un objeto JSON es el siguiente:

buf.toJSON()

Cuando se convierte en cadena una instancia de Buffer,JSON.stringify()se llama implícitamente a estetoJSON()。

Valor de retorno

Devuelve un objeto JSON.

Ejemplo

const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);

// 输出: {"type":"Buffer","data":[1,2,3,4,5]}
console.log(json);

const copy = JSON.parse(json, (key, value) => {
  return value && value.type === 'Buffer' ?
    Buffer.from(value.data) :
    value;
});

// 输出: <Buffer 01 02 03 04 05>
console.log(copy);

Al ejecutar el código anterior, el resultado es:

{"type":"Buffer","data":[1,2,3,4,5]}
<Buffer 01 02 03 04 05>

Combinar búferes

Sintaxis

La sintaxis para combinar búferes de Node es la siguiente:

Buffer.concat(list[, totalLength])

Parámetros

Los parámetros se describen a continuación:

• list- La lista de matrices de objetos Buffer que se utilizará para la combinación.

• totalLength- Especifica la longitud total del objeto Buffer después de la combinación.

Valor de retorno

Devuelve un nuevo objeto Buffer resultante de la combinación de varios miembros.

Ejemplo

var buffer1 = Buffer.from(('Ejemplo'));
var buffer2 = Buffer.from(('www.example.com'));
var buffer3 = Buffer.concat([buffer1,buffer2]);
console.log("buffer3 内容: " + buffer3.toString());

Al ejecutar el código anterior, el resultado es:

buffer3 内容: Ejemplowww.example.com

Comparación de búferes

Sintaxis

La sintaxis de la función de comparación de Buffer en Node es la siguiente. Este método se introdujo en Node.js v0.12.2:

buf.compare(otherBuffer);

Parámetros

Los parámetros se describen a continuación:

• otherBuffer- Con elbufotro objeto Buffer que se compara con el objeto.

Valor de retorno

Devuelve un número que indica si buf estábufEnotherBufferantes, después o igual.

Ejemplo

var buffer1 = Buffer.from('ABC');
var buffer2 = Buffer.from('ABCD');
var result = buffer1.compare(buffer2);

if(result < 0) {
   console.log(buffer1 + " 在 " + buffer2 + "之前");
}else if(result == 0){
   console.log(buffer1 + " 与 " + buffer2 + "相同");
}else {
   console.log(buffer1 + " 在 " + buffer2 + "之后");
}

Al ejecutar el código anterior, el resultado es:

ABC在ABCD之前

Copiar búfer

Sintaxis

La sintaxis de copia de buffer de Node es la siguiente:

buf.copy(targetBuffer[, targetStart[, sourceStart[, sourceEnd]]])

Parámetros

Los parámetros se describen a continuación:

• targetBuffer- El objeto Buffer que se va a copiar.

• targetStart- Número, opcional, por defecto: 0

• sourceStart- Número, opcional, por defecto: 0

• sourceEnd- Número, opcional, por defecto: buffer.length

Valor de retorno

No tiene valor de retorno.

Ejemplo

var buf1 = Buffer.from('abcdefghijkl');
var buf2 = Buffer.from('EJEMPLO');

//将 buf2 插入到 buf1 指定位置上
buf2.copy(buf1, 2);

console.log(buf1.toString());

Al ejecutar el código anterior, el resultado es:

abEJEMPLOijkl

Recorte del búfer

La sintaxis de recorte de buffer de Node es la siguiente:

buf.slice([start[, end]])

Parámetros

Los parámetros se describen a continuación:

• start- Número, opcional, por defecto: 0

• end- Número, opcional, por defecto: buffer.length

Valor de retorno

Devuelve un nuevo buffer que apunta a la misma memoria que el buffer original, pero cortado desde el índice start hasta end.

Ejemplo

var buffer1 = Buffer.from('ejemplo');
// 剪切缓冲区
var buffer2 = buffer1.slice(0,2);
console.log("buffer2 content: " + buffer2.toString());

Al ejecutar el código anterior, el resultado es:

buffer2 content: ru

Longitud del búfer

Sintaxis

La sintaxis para calcular la longitud de un buffer de Node es la siguiente:

buf.length;

Valor de retorno

Devuelve la longitud de memoria ocupada por el objeto Buffer.

Ejemplo

var buffer = Buffer.from('www.example.com');
//  缓冲区长度
console.log("buffer length: " + buffer.length);

Al ejecutar el código anterior, el resultado es:

buffer length: 14

Manual de referencia de métodos

A continuación se enumeran los métodos comunes del módulo Buffer de Node.js (ten en cuenta que algunos métodos no existen en versiones antiguas):

const buf = Buffer.allocUnsafe(6);

buf.writeUIntLE(0x1234567890ab, 0, 6);

// 输出: <Buffer ab 90 78 56 34 12>
console.log(buf);

const buf = Buffer.allocUnsafe(6);

buf.writeUIntBE(0x1234567890ab, 0, 6);

// 输出: <Buffer 12 34 56 78 90 ab>
console.log(buf);