You are currently viewing Node.js Buffer Complete Reference (Полная ссылка на Буфер)

Node.js Buffer Complete Reference (Полная ссылка на Буфер)

Буферы — это экземпляры класса Buffer в Node.js. Буферы предназначены для обработки двоичных необработанных данных. Буферы выделяют необработанную память за пределами кучи V8. Класс буфера является глобальным классом, поэтому его можно использовать без импорта модуля буфера в приложение.

Полный список Node.js методы буферного модуля:

Buffer (Буфер)

Buffer объекты используются для представления последовательности байтов фиксированной длины. Многие Node.js Поддержка API Buffer s. Buffer Этот класс является подклассом JavaScript Uint8Array класс и расширяет его методами, которые охватывают дополнительные варианты использования. Node.js API принимают простые Uint8Arrayс где угодно Buffers также поддерживаются. Buffer. Класс находится в глобальной области, что делает маловероятным, что когда-либо потребуется использовать require('buffer').Buffer.

// Creates a zero-filled Buffer of length 10.
const buf1 = Buffer.alloc(10);

// Creates a Buffer of length 10,
// filled with bytes which all have the value `1`.
const buf2 = Buffer.alloc(10, 1);

// Creates an uninitialized buffer of length 10.
// This is faster than calling Buffer.alloc() but the returned
// Buffer instance might contain old data that needs to be
// overwritten using fill(), write(), or other functions that fill the Buffer's
// contents.
const buf3 = Buffer.allocUnsafe(10);

// Creates a Buffer containing the bytes [1, 2, 3].
const buf4 = Buffer.from([1, 2, 3]);

// Creates a Buffer containing the bytes [1, 1, 1, 1] – the entries
// are all truncated using `(value & 255)` to fit into the range 0–255.
const buf5 = Buffer.from([257, 257.5, -255, '1']);

// Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
// [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
// [116, 195, 169, 115, 116] (in decimal notation)
const buf6 = Buffer.from('tést');

// Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74].
const buf7 = Buffer.from('tést', 'latin1');

Буферы и кодировки символов

ВерсияИзменения
v6.4.0Представил latin1 в качестве псевдонима для binary.
v5.0.0Удалил устаревшие raw и raws кодировки.

При преобразовании между Buffers и строками может быть указана кодировка символов. Если кодировка символов не указана, по умолчанию будет использоваться UTF-8.

const buf = Buffer.from('hello world', 'utf8');

console.log(buf.toString('hex'));
// Prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));
// Prints: aGVsbG8gd29ybGQ=

console.log(Buffer.from('fhqwhgads', 'utf8'));
// Prints: <Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'));
// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>

Кодировки символов, поддерживаемые в настоящее время Node.js являются ли следующие:

  • 'utf8': Многобайтовые кодированные символы Юникода. Многие веб-страницы и другие форматы документов используют UTF-8. Это кодировка символов по умолчанию. При декодировании a Buffer в строку, которая не содержит исключительно допустимые данные UTF-8, U+FFFD для представления этих ошибок будет использоваться символ замены Юникода �.
  • 'utf16le': Многобайтовые кодированные символы Юникода. В отличие 'utf8'от этого , каждый символ в строке будет закодирован с использованием 2 или 4 байтов. Node.js поддерживает только вариант UTF-16 с малым концом.
  • 'latin1': Латинский-1 означает ISO-8859-1. Эта кодировка символов поддерживает только символы Юникода от U+0000до U+00FF. Каждый символ кодируется с использованием одного байта. Символы, которые не вписываются в этот диапазон, усекаются и будут сопоставлены с символами в этом диапазоне.

Преобразование a Buffer в строку с использованием одного из вышеперечисленных способов называется декодированием, а преобразование строки в a Buffer называется кодированием.

Node.js также поддерживает следующие две кодировки двоичного кода в текст. Для кодировок двоичного кода в текст соглашение об именовании отменяется: преобразование a Buffer в строку обычно называется кодированием, а преобразование строки в a Buffer — декодированием.

  • 'base64': Кодировка Base64. При создании a Buffer из строки эта кодировка также будет правильно принимать «Безопасный алфавит URL и имени файла», как указано в RFC 4648, раздел 5. Пробелы, такие как пробелы, вкладки и новые строки, содержащиеся в строке с кодировкой base64, игнорируются.
  • 'hex': Кодируйте каждый байт как два шестнадцатеричных символа. Усечение данных может произойти при декодировании строк, которые содержат только допустимые шестнадцатеричные символы. Пример см. ниже.

Также поддерживаются следующие устаревшие кодировки символов:

  • 'ascii': Только для 7-разрядных данных ASCII. При кодировании строки в a Buffer это эквивалентно использованию 'latin1'. При декодировании a Buffer в строку использование этой кодировки дополнительно отменит значение старшего бита каждого байта перед декодированием as 'latin1'. Как правило, не должно быть причин использовать эту кодировку, так как 'utf8'(или, если известно, что данные всегда содержат только ASCII 'latin1') будет лучшим выбором при кодировании или декодировании текста, содержащего только ASCII. Это предусмотрено только для совместимости с устаревшими версиями.
  • 'binary': Псевдоним для 'latin1'. Дополнительные сведения по этой теме см. в разделе Двоичные строки. Название этой кодировки может ввести в заблуждение, так как все перечисленные здесь кодировки преобразуются между строками и двоичными данными. Для преобразования между строками и Buffers, как правило'utf-8', правильный выбор.
  • 'ucs2': Псевдоним 'utf16le'. UCS-2 использовался для обозначения варианта UTF-16, который не поддерживал символы, кодовые точки которых превышали U+FFFF. В Node.js, эти точки кода всегда поддерживаются.
Buffer.from('1ag', 'hex');
// Prints <Buffer 1a>, data truncated when first non-hexadecimal value
// ('g') encountered.

Buffer.from('1a7g', 'hex');
// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').

Buffer.from('1634', 'hex');
// Prints <Buffer 16 34>, all data represented.

Современные веб-браузеры следуют стандарту кодирования WHATWG, который 'latin1' использует псевдонимы и 'ISO-8859-1'для 'win-1252'. Это означает , что при выполнении чего-то подобного http.get(), если возвращаемая кодировка является одной из перечисленных в спецификации WHATWG, возможно, что сервер действительно вернул 'win-1252'-закодированные данные, и использование 'latin1' кодировки может привести к неправильному декодированию символов.

Буферы и типоразмеры

ВерсияИзменения
v3.0.0То Buffer класс s теперь наследует от Uint8Array.

Buffer экземпляры также являются JavaScript Uint8Array и TypedArray экземплярами. Все TypedArray методы доступны на Buffer s. Однако существуют тонкие несоответствия между Buffer API и TypedArray API.

В частности:

  • В то время TypedArray#slice() как создается копия части TypedArrayBuffer#slice() создается представление над существующим Buffer без копирования. Такое поведение может быть неожиданным и существует только для совместимости с устаревшими версиями. TypedArray#subarray() может использоваться для достижения поведения Buffer#slice() как Buffer на s, так и на других TypedArray s.
  • buf.toString() несовместимо с его TypedArray эквивалентом.
  • Ряд методов, например buf.indexOf(), поддерживают дополнительные аргументы.

Существует два способа создания новых TypedArray экземпляров из Buffer:

  • Передача a BufferTypedArray конструктору скопирует содержимое Buffer s, интерпретируемое как массив целых чисел, а не как последовательность байтов целевого типа.
const buf = Buffer.from([1, 2, 3, 4]);
const uint32array = new Uint32Array(buf);

console.log(uint32array);

// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]
  • Передача Buffers, лежащего ArrayBuffer в основе, создаст a TypedArray, который делится своей памятью с Buffer.
const buf = Buffer.from('hello', 'utf16le');
const uint16arr = new Uint16Array(
  buf.buffer,
  buf.byteOffset,
  buf.length / Uint16Array.BYTES_PER_ELEMENT);

console.log(uint16array);

// Prints: Uint16Array(5) [ 104, 101, 108, 108, 111 ]

Можно создать новый Buffer, который использует ту же выделенную память, TypedArray что и экземпляр, используя TypedArray объект .buffer собственность таким же образом. Buffer.from() ведет себя new Uint8Array() так же в этом контексте.

const arr = new Uint16Array(2);

arr[0] = 5000;
arr[1] = 4000;

// Copies the contents of `arr`.
const buf1 = Buffer.from(arr);

// Shares memory with `arr`.
const buf2 = Buffer.from(arr.buffer);

console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 a0 0f>

arr[1] = 6000;

console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 70 17>

При создании с Buffer использованием a TypedArray ‘s .buffer можно использовать только часть базового ArrayBuffer, передав byteOffset и length параметры.

const arr = new Uint16Array(20);
const buf = Buffer.from(arr.buffer, 0, 16);

console.log(buf.length);
// Prints: 16

Buffer.from() и TypedArray.from() имеют разные подписи и реализации. В частности, TypedArray варианты принимают второй аргумент, представляющий собой функцию сопоставления, которая вызывается для каждого элемента типизированного массива:

  • TypedArray.from(source[, mapFn[, thisArg]])

Буферы и итерация

Buffer экземпляры могут быть повторены с использованием for..of синтаксиса:

const buf = Buffer.from([1, 2, 3]);

for (const b of buf) {
  console.log(b);
}
// Prints:
//   1
//   2
//   3