Буфер¶
Стабильность: 2 – Стабильная
АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.
Объекты Buffer
используются для представления последовательности байтов фиксированной длины. Многие API Node.js поддерживают Buffer
.
Класс Buffer
является подклассом класса JavaScript Uint8Array
и расширяет его методами, которые охватывают дополнительные случаи использования. API Node.js принимают обычные Uint8Array
, где также поддерживаются Buffer
.
Хотя класс Buffer
доступен в глобальной области видимости, все же рекомендуется явно ссылаться на него с помощью оператора import или require.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
Буферы и кодировки символов¶
При преобразовании между Buffer
и строками может быть указана кодировка символов. Если кодировка не указана, по умолчанию будет использоваться UTF-8.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Буферы Node.js принимают все варианты кодировки строк, которые они получают. Например, UTF-8 может быть указана как utf8
, UTF8
, или uTf8
.
В настоящее время Node.js поддерживает следующие кодировки символов:
-
utf8
(псевдоним:utf-8
): Многобайтовая кодировка символов Unicode. Многие веб-страницы и другие форматы документов используют UTF-8. Это кодировка символов по умолчанию. При декодированииBuffer
в строку, которая содержит не только допустимые данные UTF-8, для представления ошибок будет использоваться символ замены UnicodeU+FFFD
�
. -
utf16le
(псевдоним:utf-16le
): Многобайтовые кодированные символы Юникода. В отличие отutf8
, каждый символ в строке будет закодирован с помощью 2 или 4 байт. Node.js поддерживает только little-endian вариант UTF-16. -
latin1
: Latin-1 обозначает ISO-8859-1. Эта кодировка поддерживает только символы Unicode отU+0000
доU+00FF
. Каждый символ кодируется с помощью одного байта. Символы, которые не вписываются в этот диапазон, усекаются и отображаются на символы этого диапазона.
Преобразование Buffer
в строку с помощью одного из вышеперечисленных способов называется декодированием, а преобразование строки в Buffer
- кодированием.
Node.js также поддерживает следующие двоично-текстовые кодировки. Для двоично-текстовых кодировок соглашение об именовании является обратным: Преобразование Buffer
в строку обычно называется кодированием, а преобразование строки в Buffer
- декодированием.
-
base64
: Base64 кодирование. При созданииBuffer
из строки эта кодировка также корректно принимает "Безопасный алфавит URL и имен файлов", как указано в RFC 4648, раздел 5. Символы пробелов, такие как пробелы, табуляции и новые строки, содержащиеся в строке в base64-кодировке, игнорируются. -
base64url
: base64url кодировка, как указано в RFC 4648, Section 5. При созданииBuffer
из строки эта кодировка также будет правильно воспринимать обычные строки в base64-кодировке. При кодированииBuffer
в строку, эта кодировка будет опускать вставку. -
hex
: Кодировать каждый байт как два шестнадцатеричных символа. При декодировании строк, состоящих не только из четного числа шестнадцатеричных символов, может произойти усечение данных. Пример см. ниже.
Также поддерживаются следующие устаревшие кодировки символов:
-
ascii
: Только для 7-битных данных ASCII. При кодировании строки вBuffer
это эквивалентно использованиюlatin1
. При декодированииBuffer
в строку использование этой кодировки дополнительно снимет старший бит каждого байта перед декодированием какlatin1
. Как правило, нет причин использовать эту кодировку, посколькуutf8
(или, если известно, что данные всегда будут только ASCII,latin1
) будет лучшим выбором при кодировании или декодировании только ASCII текста. Он предоставляется только для совместимости с предыдущими версиями. -
binary
: Псевдоним дляlatin1
. Дополнительную информацию по этому вопросу см. в binary strings. Название этой кодировки может ввести в заблуждение, поскольку все перечисленные здесь кодировки конвертируют между строками и двоичными данными. Для преобразования между строками иBuffer
, как правило, подходитutf8
. -
ucs2
,ucs-2
: Псевдонимыutf16le
. UCS-2 - это вариант UTF-16, который не поддерживал символы с кодовыми точками больше, чемU+FFFF
. В Node.js эти кодовые точки поддерживаются всегда.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Современные веб-браузеры следуют WHATWG Encoding Standard, который псевдонимы latin1
и ISO-8859-1
на win-1252
. Это означает, что при выполнении чего-то вроде http.get()
, если возвращаемая кодовая система является одной из тех, что перечислены в спецификации WHATWG, возможно, что сервер действительно вернул данные в кодировке win-1252
, а использование кодировки latin1
может неправильно декодировать символы.
Буферы и TypedArrays¶
Экземпляры Buffer
также являются экземплярами JavaScript Uint8Array
и TypedArray
. Все методы TypedArray
доступны для Buffer
. Однако между API Buffer
и API TypedArray
существуют тонкие несовместимости.
В частности:
- В то время как
TypedArray.prototype.slice()
создает копию частиTypedArray
,Buffer.prototype.slice()
создает представление над существующимBuffer
без копирования. Такое поведение может удивить, и существует только для совместимости с наследием.TypedArray.prototype.subarray()
может быть использован для достижения поведенияBuffer.prototype.slice()
как наBuffer
, так и на другихTypedArray
и должен быть предпочтительным. buf.toString()
несовместим со своим эквивалентомTypedArray
.- Ряд методов, например,
buf.indexOf()
, поддерживают дополнительные аргументы.
Существует два способа создания новых экземпляров TypedArray
из Buffer
:
- Передача
Buffer
конструкторуTypedArray
скопирует содержимоеBuffer
, интерпретируемое как массив целых чисел, а не как последовательность байтов целевого типа.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
- Передача
Buffer
, лежащего в основеArrayBuffer
, создастTypedArray
, который разделит свою память сBuffer
.
1 2 3 4 5 6 7 8 9 10 11 12 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Можно создать новый Buffer
, который разделяет ту же выделенную память, что и экземпляр TypedArray
, используя свойство .buffer
объекта TypedArray
таким же образом. Buffer.from()
в этом контексте ведет себя как new Uint8Array()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
При создании Buffer
с помощью .buffer
TypedArray
можно использовать только часть базового ArrayBuffer
, передавая параметры byteOffset
и length
.
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 |
|
Варианты Buffer.from()
и TypedArray.from()
имеют разные сигнатуры и реализации. В частности, варианты TypedArray
принимают второй аргумент, который является функцией отображения, вызываемой для каждого элемента типизированного массива:
TypedArray.from(source[, mapFn[, thisArg]])
.
Метод Buffer.from()
, однако, не поддерживает использование функции отображения:
Buffer.from(array)
Buffer.from(buffer)
Buffer.from(arrayBuffer[, byteOffset[, length]])
Buffer.from(string[, encoding])
Буферы и итерация¶
Экземпляры Buffer
можно итерировать, используя синтаксис for..of
:
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Кроме того, для создания итераторов можно использовать методы buf.values()
, buf.keys()
и buf.entries()
.
Класс: Blob
¶
В Blob
заключены неизменяемые, необработанные данные, которые могут безопасно использоваться несколькими рабочими потоками.
new Buffer.Blob()
¶
1 |
|
sources
<string[]>
|<ArrayBuffer[]>
|<TypedArray[]>
|<DataView[]>
|<Blob[]>
Массив строк,<ArrayBuffer>
,<TypedArray>
,<DataView>
или<Blob>
объектов, или любая смесь таких объектов, которые будут храниться вBlob
.options
<Object>
endings
<string>
Одно из значенийtransparent
илиnative
. Если установлено значение'native'
, окончания строк в строковых исходных частях будут преобразованы к родному для платформы окончанию строк, как указано вrequire('node:os').EOL
.type
<string>
Тип содержимого блоба. Цельtype
- передать тип MIME-медиа данных, однако проверка формата типа не выполняется.
Создает новый объект Blob
, содержащий конкатенацию заданных источников.
Источники <ArrayBuffer>
, <TypedArray>
, <DataView>
и <Buffer>
копируются в 'Blob' и поэтому могут быть безопасно изменены после создания 'Blob'.
Источники строк кодируются как последовательности байтов UTF-8 и копируются в блоб. Несовпадающие суррогатные пары в каждой части строки будут заменены символами замены Unicode U+FFFD.
blob.arrayBuffer()
¶
- Возвращает:
<Promise>
Возвращает обещание, которое выполняется с <ArrayBuffer>
, содержащим копию данных Blob
.
blob.size
¶
Общий размер блоба
в байтах.
blob.slice()
¶
1 |
|
start
<number>
Начальный индекс.end
<number>
Конечный индекс.type
<string>
Тип содержимого для новогоBlob
.
Создает и возвращает новый Blob
, содержащий подмножество данных объектов этого Blob
. Исходный Blob
не изменяется.
blob.stream()
¶
- Возвращает:
<ReadableStream>
Возвращает новый ReadableStream
, который позволяет читать содержимое Blob
.
blob.text()
¶
- Возвращает:
<Promise>
Возвращает обещание, которое выполняется с содержимым Blob
, декодированным как строка UTF-8.
blob.type
¶
- Тип:
<string>
Тип содержимого blob
.
Blob
объекты и MessageChannel
¶
После создания объекта <Blob>
он может быть отправлен через MessagePort
в несколько пунктов назначения без передачи или немедленного копирования данных. Данные, содержащиеся в Blob
, копируются только при вызове методов arrayBuffer()
или text()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
Класс: Buffer
¶
Класс Buffer
- это глобальный тип для работы с двоичными данными напрямую. Он может быть построен различными способами.
Buffer.alloc()
¶
Статический метод:
1 |
|
size
<integer>
Желаемая длина новогоBuffer
.fill
<string>
|<Buffer>
|<Uint8Array>
|<integer>
Значение для предварительного заполнения новогоBuffer
. По умолчанию:0
.encoding
<string>
Еслиfill
является строкой, то это ее кодировка. По умолчанию:'utf8'
.
Выделяет новый Buffer
размером size
байт. Если fill
- undefined
, Buffer
будет заполнен нулями.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
Если size
больше чем buffer.constants.MAX_LENGTH
или меньше 0
, то будет выброшено ERR_INVALID_ARG_VALUE
.
Если указано fill
, выделенный Buffer
будет инициализирован вызовом buf.fill(fill)
.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
Если указаны и fill
, и encoding
, выделенный Buffer
будет инициализирован вызовом buf.fill(fill, encoding)
.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
Вызов Buffer.alloc()
может быть ощутимо медленнее альтернативы Buffer.allocUnsafe()
, но гарантирует, что содержимое вновь созданного экземпляра Buffer
никогда не будет содержать конфиденциальных данных из предыдущих распределений, включая данные, которые могли быть выделены не для Buffer
.
Если size
не является числом, будет выдана ошибка TypeError
.
Buffer.allocUnsafe()
¶
Статический метод:
1 |
|
size
<integer>
Желаемая длина новогоBuffer
.
Выделяет новый Buffer
размером size
байт. Если size
больше чем buffer.constants.MAX_LENGTH
или меньше чем 0
, то происходит выброс ERR_INVALID_ARG_VALUE
.
Базовая память для экземпляров Buffer
, созданных таким образом, не инициализируется. Содержимое вновь созданного Buffer
неизвестно и может содержать конфиденциальные данные. Вместо этого используйте Buffer.alloc()
для инициализации экземпляров Buffer
нулями.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Если size
не является числом, будет выдана ошибка TypeError
.
Модуль Buffer
предварительно выделяет внутренний экземпляр Buffer
размером Buffer.poolSize
, который используется как пул для быстрого выделения новых экземпляров Buffer
, созданных с помощью Buffer.allocUnsafe()
, Buffer. from(array)
, Buffer.concat()
, и устаревшего конструктора new Buffer(size)
, только если size
меньше или равен Buffer.poolSize >> 1
(пол Buffer.poolSize
деленное на два).
Использование этого предварительно распределенного внутреннего пула памяти является ключевым отличием между вызовом Buffer.alloc(size, fill)
и Buffer.allocUnsafe(size).fill(fill)
. В частности, Buffer.alloc(size, fill)
никогда не будет использовать внутренний пул Buffer
, в то время как Buffer.allocUnsafe(size).fill(fill)
будет использовать внутренний пул Buffer
, если size
меньше или равен половине Buffer.poolSize
. Разница едва заметна, но может быть важна, когда приложению требуется дополнительная производительность, которую обеспечивает Buffer.allocUnsafe()
.
Buffer.allocUnsafeSlow()
¶
Статический метод:
1 |
|
size
<integer>
Желаемая длина новогоBuffer
.
Выделяет новый Буфер
размером size
байт. Если size
больше чем buffer.constants.MAX_LENGTH
или меньше 0, то будет выброшен ERR_INVALID_ARG_VALUE
. Буфер нулевой длины Buffer
создается, если size
равен 0.
Базовая память для экземпляров Buffer
, созданных таким образом, не инициализируется. Содержимое вновь созданного Buffer
неизвестно и может содержать конфиденциальные данные. Используйте buf.fill(0)
для инициализации таких экземпляров Buffer
нулями.
При использовании Buffer.allocUnsafe()
для выделения новых экземпляров Buffer
, выделения размером менее 4 КиБ вырезаются из одного предварительно выделенного Buffer
. Это позволяет приложениям избежать накладных расходов на сборку мусора при создании множества отдельно выделенных экземпляров Buffer
. Такой подход улучшает производительность и использование памяти за счет отсутствия необходимости отслеживать и очищать множество отдельных объектов ArrayBuffer
.
Однако в случае, когда разработчику может понадобиться сохранить небольшой участок памяти из пула на неопределенное время, может быть целесообразно создать экземпляр Buffer
без пула, используя Buffer.allocUnsafeSlow()
и затем скопировать соответствующие биты.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
Если size
не является числом, будет выдана ошибка TypeError
.
Buffer.byteLength()
¶
Статический метод:
1 |
|
string
<string>
|<Buffer>
|<TypedArray>
|<DataView>
|<ArrayBuffer>
|<SharedArrayBuffer>
Значение для вычисления длины.encoding
<string>
Еслиstring
является строкой, то это ее кодировка. По умолчанию:'utf8'
.- Возвращает:
<integer>
Количество байтов, содержащихся вstring
.
Возвращает длину байта строки при кодировании с помощью encoding
. Это не то же самое, что String.prototype.length
, который не учитывает кодировку, используемую для преобразования строки в байты.
Для 'base64'
, 'base64url'
и 'hex'
эта функция предполагает корректный ввод. Для строк, которые содержат данные не base64/hex-кодировки (например, пробелы), возвращаемое значение может быть больше, чем длина буфера
, созданного из строки.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
Если string
является Buffer
/DataView
/TypedArray
/ArrayBuffer
/ SharedArrayBuffer
, возвращается длина байта, сообщенная .byteLength
.
Buffer.compare()
¶
Статический метод:
1 |
|
buf1
<Buffer>
|<Uint8Array>
buf2
<Buffer>
|<Uint8Array>
- Возвращает:
<integer>
Либо-1
,0
, либо1
, в зависимости от результата сравнения. Подробности смотрите вbuf.compare()
.
Сравнивает buf1
с buf2
, обычно для сортировки массивов экземпляров Buffer
. Это эквивалентно вызову buf1.compare(buf2)
.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
Buffer.concat()
¶
Статический метод:
1 |
|
list
<Buffer[]>
|<Uint8Array[]>
Список экземпляровBuffer
илиUint8Array
для конкатенации.totalLength
<integer>
Общая длина экземпляровBuffer
всписке
при конкатенации.- Возвращает:
<Buffer>
Возвращает новый Buffer
, который является результатом объединения всех экземпляров Buffer
в list
.
Если в списке нет элементов или если totalLength
равна 0, то возвращается новый Buffer
нулевой длины.
Если totalLength
не указана, то она вычисляется из экземпляров Buffer
в list
путем сложения их длин.
Если totalLength
указана, она приводится к целому числу без знака. Если суммарная длина Buffer
в list
превышает totalLength
, результат усекается до totalLength
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Buffer.concat()
может также использовать внутренний пул Buffer
, как это делает Buffer.allocUnsafe()
.
Buffer.copyBytesFrom()
¶
Статический метод:
1 |
|
view
<TypedArray>
<TypedArray>
для копирования.offset
<integer>
Начальное смещение вview
. По умолчанию::0
.length
<integer>
Количество элементов изview
для копирования. По умолчанию:view.length - offset
.
Копирует базовую память view
в новый Buffer
.
1 2 3 4 5 6 |
|
Buffer.from()
¶
Статический метод:
1 |
|
array
<integer[]>
Выделяет новый Буфер
, используя массив
байтов в диапазоне 0
- 255
. Записи массива за пределами этого диапазона будут усечены, чтобы поместиться в него.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Если array
не является Array
или другим типом, подходящим для вариантов Buffer.from()
, то будет выдан TypeError
.
Buffer.from(array)
и Buffer.from(string)
могут также использовать внутренний пул Buffer
, как это делает Buffer.allocUnsafe()
.
Статический метод:
1 |
|
arrayBuffer
<ArrayBuffer>
|<SharedArrayBuffer>
ArrayBuffer
,SharedArrayBuffer
, например, свойство.buffer
дляTypedArray
.byteOffset
<integer>
Индекс первого байта для раскрытия. По умолчанию:0
.length
<integer>
Количество байтов для раскрытия. По умолчанию:arrayBuffer.byteLength - byteOffset
.
Это создает представление ArrayBuffer
без копирования основной памяти. Например, при передаче ссылки на свойство .buffer
экземпляра TypedArray
, вновь созданный Buffer
будет использовать ту же выделенную память, что и основной ArrayBuffer
TypedArray
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Необязательные аргументы byteOffset
и length
задают диапазон памяти в arrayBuffer
, который будет совместно использоваться Buffer
.
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 |
|
Если arrayBuffer
не является ArrayBuffer
или SharedArrayBuffer
или другим типом, подходящим для вариантов Buffer.from()
, то будет выдан TypeError
.
Важно помнить, что резервный ArrayBuffer
может охватывать диапазон памяти, выходящий за границы представления TypedArray
. Новый Buffer
, созданный с помощью свойства buffer
представления TypedArray
:
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
1 |
|
buffer
<Buffer>
|<Uint8Array>
СуществующийBuffer
илиUint8Array
, из которого нужно скопировать данные.
Копирует переданные данные buffer
в новый экземпляр Buffer
.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
Если buffer
не является Buffer
или другим типом, подходящим для вариантов Buffer.from()
, то будет выдан TypeError
.
1 |
|
object
<Object>
Объект, поддерживающийSymbol.toPrimitive
илиvalueOf()
.offsetOrEncoding
<integer>
|<string>
Смещение байтов или кодировка.length
<integer>
Длина.
Для объектов, чья функция valueOf()
возвращает значение, не равное строго object
, возвращает Buffer.from(object.valueOf(), offsetOrEncoding, length)
.
1 2 3 4 |
|
1 2 3 4 |
|
Для объектов, поддерживающих Symbol.toPrimitive
, возвращает Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding)
.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
Если object
не имеет упомянутых методов или не является другим типом, подходящим для вариантов Buffer.from()
, будет выброшен TypeError
.
1 |
|
Создает новый Buffer
, содержащий string
. Параметр encoding
определяет кодировку символов, которая будет использоваться при преобразовании string
в байты.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Если string
не является строкой или другим типом, подходящим для вариантов Buffer.from()
, будет выдан TypeError
.
Buffer.isBuffer()
¶
Статический метод:
1 |
|
Возвращает true
, если obj
является Buffer
, false
в противном случае.
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 |
|
Buffer.isEncoding()
¶
Статический метод:
1 |
|
Возвращает true
, если encoding
является именем поддерживаемой кодировки символов, или false
в противном случае.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Buffer.poolSize
¶
<integer>
По умолчанию:8192
.
Это размер (в байтах) предварительно выделенных внутренних экземпляров Buffer
, используемых для объединения в пул. Это значение может быть изменено.
buf[index]
¶
index
<integer>
Оператор индекса [index]
может использоваться для получения и установки октета в позиции index
в buf
. Значения относятся к отдельным байтам, поэтому допустимый диапазон значений находится между 0x00
и 0xFF
(шестнадцатеричный) или 0
и 255
(десятичный).
Этот оператор унаследован от Uint8Array
, поэтому его поведение при доступе за пределы границ такое же, как и у Uint8Array
. Другими словами, buf[index]
возвращает undefined
, когда index
отрицателен или больше или равен buf.length
, а buf[index] = value
не изменяет буфер, если index
отрицателен или >= buf.length
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
buf.buffer
¶
<ArrayBuffer>
Основной объектArrayBuffer
, на основе которого создается данный объектBuffer
.
Не гарантируется, что этот ArrayBuffer
будет точно соответствовать исходному Buffer
. Подробности смотрите в примечаниях к buf.byteOffset
.
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 |
|
buf.byteOffset
¶
<integer>
БайтОффсет" объектаBuffer
, лежащего в основеArrayBuffer
.
При установке byteOffset
в Buffer.from(ArrayBuffer, byteOffset, length)
, или иногда при выделении Buffer
меньшего размера, чем Buffer.poolSize
, буфер не начинается с нулевого смещения на нижележащем ArrayBuffer
.
Это может вызвать проблемы при прямом доступе к базовому ArrayBuffer
с помощью buf.buffer
, поскольку другие части ArrayBuffer
могут быть не связаны с самим объектом Buffer
.
Частая проблема при создании объекта TypedArray
, который разделяет свою память с Buffer
, заключается в том, что в этом случае необходимо правильно указать byteOffset
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
buf.compare()
¶
1 |
|
target
<Buffer>
|<Uint8Array>
Буфер
илиUint8Array
, с которым нужно сравнитьbuf
.targetStart
<integer>
Смещение внутриtarget
, с которого следует начать сравнение. По умолчанию:0
.targetEnd
<integer>
Смещение в пределахцели
, на котором заканчивается сравнение (не включительно). По умолчанию:target.length
.sourceStart
<integer>
Смещение вbuf
, с которого следует начать сравнение. По умолчанию:0
.sourceEnd
<integer>
Смещение вbuf
, на котором заканчивается сравнение (не включительно). По умолчанию:buf.length
.- Возвращает:
<integer>
Сравнивает buf
с target
и возвращает число, указывающее, находится ли buf
перед, после или совпадает с target
в порядке сортировки. Сравнение основано на фактической последовательности байтов в каждом буфере
.
0
возвращается, еслицель
совпадает сbuf
.1
возвращается, еслицель
должна быть передbuf
при сортировке.-1
возвращается, еслицель
должна быть послеbuf
при сортировке.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
Дополнительные аргументы targetStart
, targetEnd
, sourceStart
и sourceEnd
могут быть использованы для ограничения сравнения определенными диапазонами в пределах target
и buf
соответственно.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
ERR_OUT_OF_RANGE
выбрасывается, если targetStart < 0
, sourceStart < 0
, targetEnd > target.byteLength
, или sourceEnd > source.byteLength
.
buf.copy()
¶
1 |
|
target
<Buffer>
|<Uint8Array>
Буфер илиUint8Array
для копирования.targetStart
<integer>
Смещение внутриtarget
, с которого следует начать запись. По умолчанию:0
.sourceStart
<integer>
Смещение вbuf
, с которого начинается копирование. По умолчанию:0
.sourceEnd
<integer>
Смещение вbuf
, с которого следует прекратить копирование (не включительно). По умолчанию:buf.length
.- Возвращает:
<integer>
Количество скопированных байт.
Копирует данные из области buf
в область target
, даже если область памяти target
перекрывается с buf
.
TypedArray.prototype.set()
выполняет ту же операцию и доступен для всех TypedArray, включая Node.js Buffer
, хотя принимает разные аргументы функции.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
buf.entries()
¶
- Возвращает:
<Iterator>
Создает и возвращает итератор пар [индекс, байт]
из содержимого buf
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
buf.equals(otherBuffer)
¶
otherBuffer
<Buffer>
|<Uint8Array>
Буфер илиUint8Array
, с которым сравниваетсяbuf
.- Возвращает:
<boolean>
Возвращает true
, если и buf
и otherBuffer
имеют одинаковые байты, false
в противном случае. Эквивалентно buf.compare(otherBuffer) === 0
.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
buf.fill(value[, offset[, end]][, encoding])
¶
value
<string>
|<Buffer>
|<Uint8Array>
|<integer>
Значение, которым заполняетсяbuf
. Пустое значение (string, Uint8Array, Buffer) принудительно записывается в0
.offset
<integer>
Количество байт, которое нужно пропустить перед началом заполненияbuf
. По умолчанию:0
.end
<integer>
Где остановить заполнениеbuf
(не включительно). По умолчанию:buf.length
.encoding
<string>
Кодировка дляvalue
, еслиvalue
является строкой. По умолчанию:'utf8'
.- Возвращает:
<Buffer>
Ссылка наbuf
.
Заполняет buf
указанным значением
. Если offset
и end
не указаны, то заполняется весь buf
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Значение value
приводится к значению uint32
, если оно не является строкой, Buffer
или целым числом. Если полученное целое число больше 255
(десятичное), buf
будет заполнен value & 255
.
Если финальная запись операции fill()
приходится на многобайтовый символ, то записываются только те байты этого символа, которые помещаются в buf
:
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
Если value
содержит недопустимые символы, оно усекается; если не остается допустимых данных для заполнения, выбрасывается исключение:
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
buf.includes(value[, byteOffset][, encoding])
¶
value
<string>
|<Buffer>
|<Uint8Array>
|<integer>
Что искать.byteOffset
<integer>
С чего начать поиск вbuf
. Если отрицательно, то смещение отсчитывается от концаbuf
. По умолчанию:0
.encoding
<string>
Еслиvalue
является строкой, то это ее кодировка. По умолчанию:'utf8'
.- Возвращает:
<boolean>
true
, еслизначение
было найдено вbuf
,false
в противном случае.
Эквивалентно buf.indexOf() !== -1
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
buf.indexOf(value[, byteOffset][, encoding])
¶
value
<string>
|<Buffer>
|<Uint8Array>
|<integer>
Что искать.byteOffset
<integer>
С чего начать поиск вbuf
. Если отрицательно, то смещение отсчитывается от концаbuf
. По умолчанию:0
.encoding
<string>
Еслиvalue
является строкой, то это кодировка, используемая для определения двоичного представления строки, которая будет искаться вbuf
. По умолчанию:'utf8'
.- Возвращает:
<integer>
Индекс первого вхождениязначения
вbuf
, или-1
, еслиbuf
не содержитзначения
.
Если value
является:
- строка,
value
интерпретируется в соответствии с кодировкой символов вencoding
. Buffer
илиUint8Array
,value
будет использовано полностью. Для сравнения частичногоBuffer
используйтеbuf.subarray
.- число,
value
будет интерпретировано как беззнаковое 8-битное целое значение от0
до255
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
|
Если value
не является строкой, числом или Buffer
, этот метод выдаст TypeError
. Если value
является числом, оно будет приведено к допустимому значению байта, целому числу от 0 до 255.
Если byteOffset
не является числом, оно будет приведено к числу. Если результатом когеренции является NaN
или 0
, то будет произведен поиск во всем буфере. Это поведение соответствует String.prototype.indexOf()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Если value
- пустая строка или пустой Buffer
и byteOffset
меньше buf.length
, то будет возвращен byteOffset
. Если value
пустое и byteOffset
не меньше buf.length
, будет возвращена buf.length
.
buf.keys()
¶
- Возвращает:
<Iterator>
Создает и возвращает итератор ключей (индексов) buf
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
buf.lastIndexOf(value[, byteOffset][, encoding])
¶
value
<string>
|<Buffer>
|<Uint8Array>
|<integer>
Что искать.byteOffset
<integer>
С чего начать поиск вbuf
. Если отрицательно, то смещение рассчитывается от концаbuf
. По умолчанию:buf.length - 1
.encoding
<string>
Еслиvalue
является строкой, то это кодировка, используемая для определения двоичного представления строки, которая будет искаться вbuf
. По умолчанию:'utf8'
.- Возвращает:
<integer>
Индекс последнего вхождениязначения
вbuf
, или-1
, еслиbuf
не содержитзначения
.
Идентично buf.indexOf()
, за исключением того, что находится последнее вхождение значения
, а не первое.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
|
Если value
не является строкой, числом или Buffer
, этот метод выдаст TypeError
. Если value
- число, оно будет приведено к допустимому значению байта, целому числу от 0 до 255.
Если byteOffset
не является числом, оно будет приведено к числу. Любые аргументы, которые приводятся к NaN
, такие как {}
или undefined
, будут искать во всем буфере. Это поведение соответствует String.prototype.lastIndexOf()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Если value
- пустая строка или пустой Buffer
, будет возвращен byteOffset
.
buf.length
¶
Возвращает количество байт в buf
.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
buf.parent
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Вместо этого используйте buf.buffer
.
Свойство buf.parent
является устаревшим псевдонимом для buf.buffer
.
buf.readBigInt64BE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<bigint>
Читает знаковое, big-endian 64-битное целое число из buf
по указанному смещению
.
Целое число, считанное из буфера
, интерпретируется как знаковое значение с двумя дополнениями.
buf.readBigInt64LE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<bigint>
Читает знаковое, little-endian 64-битное целое число из buf
по указанному смещению
.
Целочисленные значения, считанные из буфера
, интерпретируются как знаковое число с двойным дополнением.
buf.readBigUInt64BE([offset])
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<bigint>
Читает беззнаковое, big-endian 64-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readBigUint64BE
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
buf.readBigUInt64LE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<bigint>
Читает беззнаковое, little-endian 64-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readBigUint64LE
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
buf.readDoubleBE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<number>
Читает 64-битное, big-endian двойное число из buf
по указанному смещению
.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
buf.readDoubleLE([offset])
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<number>
Читает 64-битное, little-endian двойное число из buf
по указанному смещению
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.readFloatBE([offset])
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<number>
Читает 32-битное, big-endian float из buf
по указанному смещению
.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
buf.readFloatLE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<number>
Читает 32-битное, little-endian float из buf
по указанному смещению
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.readInt8([offset])
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 1
. По умолчанию:0
.- Возвращает:
<integer>
Читает знаковое 8-битное целое число из buf
по указанному смещению
.
Целое число, считанное из буфера
, интерпретируется как два знаковых дополнения.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
buf.readInt16BE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
Читает знаковое, big-endian 16-битное целое число из buf
по указанному смещению
.
Целочисленные значения, считанные из буфера
, интерпретируются как два дополнения к знаковым значениям.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
buf.readInt16LE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
Читает знаковое, little-endian 16-битное целое число из buf
по указанному смещению
.
Целочисленные значения, считанные из буфера
, интерпретируются как два дополнения к знаковым значениям.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.readInt32BE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
Читает знаковое, big-endian 32-битное целое число из buf
по указанному смещению
.
Целочисленные значения, считанные из буфера
, интерпретируются как два дополнения к знаковым значениям.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
buf.readInt32LE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
Читает знаковое, little-endian 32-битное целое число из buf
по указанному смещению
.
Целочисленные значения, считанные из буфера
, интерпретируются как два дополнения к знаковым значениям.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.readIntBE(offset, byteLength)
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для чтения. Должно удовлетворять0 < byteLength <= 6
.- Возвращает:
<integer>
Считывает byteLength
количество байт из buf
по указанному смещению
и интерпретирует результат как знаковое значение с большой точностью до 48 бит.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
buf.readIntLE(offset, byteLength)
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для чтения. Должно удовлетворять0 < byteLength <= 6
.- Возвращает:
<integer>
Считывает byteLength
количество байт из buf
по указанному смещению
и интерпретирует результат как знаковое значение с точностью до 48 бит.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
buf.readUInt8([offset])
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 1
. По умолчанию:0
.- Возвращает:
<integer>
Читает беззнаковое 8-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readUint8
.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
buf.readUInt16BE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
Читает беззнаковое, big-endian 16-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readUint16BE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.readUInt16LE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
Читает беззнаковое, little-endian 16-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readUint16LE
.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
buf.readUInt32BE([offset])
¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
Читает беззнаковое, big-endian 32-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readUint32BE
.
1 2 3 4 5 6 |
|
1 2 3 4 5 6 |
|
buf.readUInt32LE([offset])
¶
offset
<integer>
Количество байт, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
Читает беззнаковое, little-endian 32-битное целое число из buf
по указанному смещению
.
Эта функция также доступна под псевдонимом readUint32LE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.readUIntBE(offset, byteLength)
.¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для чтения. Должно удовлетворять0 < byteLength <= 6
.- Возвращает:
<integer>
Считывает byteLength
количество байт из buf
по указанному смещению
и интерпретирует результат как целое число без знака big-endian, поддерживающее точность до 48 бит.
Эта функция также доступна под псевдонимом readUintBE
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
buf.readUIntLE(offset, byteLength)
.¶
offset
<integer>
Количество байтов, которые нужно пропустить перед началом чтения. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для чтения. Должно удовлетворять0 < byteLength <= 6
.- Возвращает:
<integer>
Считывает byteLength
количество байт из buf
по указанному смещению
и интерпретирует результат как беззнаковое, little-endian целое число, поддерживающее точность до 48 бит.
Эта функция также доступна под псевдонимом readUintLE
.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
buf.subarray([start[, end]])
¶
start
<integer>
С чего будет начинаться новыйбуфер
. По умолчанию:0
.end
<integer>
Где закончится новыйбуфер
(не включительно). По умолчанию:buf.length
.- Возвращает:
<Buffer>
Возвращает новый Буфер
, который ссылается на ту же память, что и исходный, но смещен и обрезан по индексам start
и end
.
Указание end
больше чем buf.length
вернет тот же результат, что и end
равный buf.length
.
Этот метод унаследован от TypedArray.prototype.subarray()
.
Модификация нового фрагмента Buffer
приведет к изменению памяти в исходном Buffer
, поскольку выделенная память двух объектов перекрывается.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
Указание отрицательных индексов заставляет генерировать фрагмент относительно конца buf
, а не начала.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
buf.slice([start[, end]])
¶
start
<integer>
Место начала новогобуфера
. По умолчанию:0
.end
<integer>
Где закончится новыйбуфер
(не включительно). По умолчанию:buf.length
.- Возвращает:
<Buffer>
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Вместо этого используйте buf.subarray
.
Возвращает новый Буфер
, который ссылается на ту же память, что и оригинал, но смещен и обрезан по индексам start
и end
.
Этот метод не совместим с Uint8Array.prototype.slice()
, который является суперклассом Buffer
. Чтобы скопировать срез, используйте Uint8Array.prototype.slice()
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
buf.swap16()
¶
- Возвращает:
<Buffer>
Ссылка наbuf
.
Интерпретирует buf
как массив беззнаковых 16-битных целых чисел и меняет порядок байтов на месте. Выбрасывает ERR_INVALID_BUFFER_SIZE
, если buf.length
не кратно 2.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
Одним из удобных применений buf.swap16()
является быстрое преобразование на месте между UTF-16 little-endian и UTF-16 big-endian:
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 |
|
buf.swap32()
¶
- Возвращает:
<Buffer>
Ссылка наbuf
.
Интерпретирует buf
как массив беззнаковых 32-битных целых чисел и меняет порядок байтов на месте. Выбрасывает ERR_INVALID_BUFFER_SIZE
, если buf.length
не кратно 4.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
buf.swap64()
¶
- Возвращает:
<Buffer>
Ссылка наbuf
.
Интерпретирует buf
как массив 64-битных чисел и меняет порядок байтов на месте. Выбрасывает ERR_INVALID_BUFFER_SIZE
, если buf.length
не кратен 8.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
buf.toJSON()
¶
- Возвращает:
<Object>
Возвращает JSON-представление buf
. JSON.stringify()
неявно вызывает эту функцию при структурировании экземпляра Buffer
.
Buffer.from()
принимает объекты в формате, возвращаемом этим методом. В частности, Buffer.from(buf.toJSON())
работает как Buffer.from(buf)
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
buf.toString([encoding[, start[, end]]])
¶
encoding
<string>
Используемая кодировка символов. По умолчанию:'utf8'
.start
<integer>
Смещение байта, с которого следует начать декодирование. По умолчанию:0
.end
<integer>
Смещение байта для остановки декодирования (не включительно). По умолчанию:buf.length
.- Возвращает:
<string>
Декодирует buf
в строку в соответствии с указанной кодировкой символов в encoding
. Можно передать start
и end
, чтобы декодировать только часть buf
.
Если encoding
имеет значение 'utf8'
и последовательность байтов во входных данных не является правильной UTF-8, то каждый неправильный байт заменяется символом замены U+FFFD
.
Максимальная длина экземпляра строки (в единицах кода UTF-16) доступна как buffer.constants.MAX_STRING_LENGTH
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
|
buf.values()
¶
- Возвращает:
<Iterator>
Создает и возвращает итератор для значений buf
(байтов). Эта функция вызывается автоматически, когда Buffer
используется в операторе for..of
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
buf.write(string[, offset[, length]][, encoding])
¶
string
<string>
Строка для записи вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записистроки
. По умолчанию:0
.length
<integer>
Максимальное количество байт для записи (записываемые байты не должны превышатьbuf.length - offset
). По умолчанию:buf.length - offset
.encoding
<string>
Кодировка символовстроки
. По умолчанию:'utf8'
.- Возвращает:
<integer>
Количество записанных байт.
Записывает string
в buf
по адресу offset
в соответствии с кодировкой символов в encoding
. Параметр length
- это количество байт для записи. Если buf
не содержит достаточно места, чтобы вместить всю строку, будет записана только часть string
. Однако частично закодированные символы не будут записаны.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
buf.writeBigInt64BE(value[, offset])
¶
value
<bigint>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<number>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как big-endian.
Значение value
интерпретируется и записывается как целое знаковое число с двойным дополнением.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeBigInt64LE(value[, offset])
¶
value
<bigint>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<number>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian.
Значение value
интерпретируется и записывается как целое знаковое число с двойным дополнением.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeBigUInt64BE(value[, offset])
¶
value
<bigint>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<number>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как big-endian.
Эта функция также доступна под псевдонимом writeBigUint64BE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeBigUInt64LE(value[, offset])
¶
value
<bigint>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять:0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<number>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
Эта функция также доступна под псевдонимом writeBigUint64LE
.
buf.writeDoubleBE(value[, offset])
¶
value
<number>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как big-endian. Значение value
должно быть числом JavaScript. Поведение не определено, если значение
не является числом JavaScript.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeDoubleLE(value[, offset])
¶
value
<number>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 8
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian. Значение value
должно быть числом JavaScript. Поведение не определено, если значение
не является числом JavaScript.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeFloatBE(value[, offset])
¶
value
<number>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как big-endian. Поведение не определено, если значение
не является числом JavaScript.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeFloatLE(value[, offset])
¶
value
<number>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian. Поведение не определено, если значение
не является числом JavaScript.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeInt8(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 1
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
. Значение
должно быть правильным знаковым 8-битным целым числом. Поведение не определено, если значение
не является знаковым 8-битным целым числом.
value
интерпретируется и записывается как целое число с двумя знаками дополнения.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
buf.writeInt16BE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
в порядке big-endian. Значение value
должно быть правильным подписанным 16-битным целым числом. Поведение не определено, если значение
не является 16-разрядным целым числом.
Значение value
интерпретируется и записывается как целое число с двойным дополнением.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeInt16LE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian. Значение value
должно быть правильным подписанным 16-битным целым числом. Поведение не определено, если значение
не является значащим 16-битным целым числом.
Значение value
интерпретируется и записывается как целое число с двойным дополнением.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeInt32BE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
в порядке big-endian. Значение value
должно быть правильным знаковым 32-битным целым числом. Поведение не определено, если значение
не является знаковым 32-битным целым числом.
Значение value
интерпретируется и записывается как знаковое целое число с двойным дополнением.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeInt32LE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian. Значение value
должно быть правильным знаковым 32-битным целым числом. Поведение не определено, если значение
не является знаковым 32-битным целым числом.
Значение value
интерпретируется и записывается как знаковое целое число с двойным дополнением.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeIntBE(value, offset, byteLength)
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байтов, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для записи. Должно удовлетворять0 < byteLength <= 6
.- Возвращает: {бесконечное число}
смещение
плюс количество записанных байт.
Записывает byteLength
байт значения
в buf
по указанному смещению
как big-endian. Поддерживает точность до 48 бит. Поведение не определено, если значение
не является знаковым целым числом.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeIntLE(value, offset, byteLength)
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байтов, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для записи. Должно удовлетворять0 < byteLength <= 6
.- Возвращает: {бесконечное число}
смещение
плюс количество записанных байт.
Записывает byteLength
байт значения
в buf
по указанному смещению
как little-endian. Поддерживает точность до 48 бит. Поведение не определено, если значение
не является знаковым целым числом.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeUInt8(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 1
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
. Значение
должно быть правильным беззнаковым 8-битным целым числом. Поведение функции не определено, если значение
не является беззнаковым 8-битным целым числом.
Эта функция также доступна под псевдонимом writeUint8
.
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
buf.writeUInt16BE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
в порядке big-endian. Значение value
должно быть правильным беззнаковым 16-битным целым числом. Поведение не определено, если значение
не является беззнаковым 16-битным целым числом.
Эта функция также доступна под псевдонимом writeUint16BE
.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
buf.writeUInt16LE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 2
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian. Значение value
должно быть правильным беззнаковым 16-битным целым числом. Поведение не определено, если значение
не является беззнаковым 16-битным целым числом.
Эта функция также доступна под псевдонимом writeUint16LE
.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 |
|
buf.writeUInt32BE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
в порядке big-endian. Значение value
должно быть правильным беззнаковым 32-битным целым числом. Поведение функции не определено, если значение
не является беззнаковым 32-битным целым числом.
Эта функция также доступна под псевдонимом writeUint32BE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeUInt32LE(value[, offset])
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байт, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - 4
. По умолчанию:0
.- Возвращает:
<integer>
offset
плюс количество записанных байт.
Записывает значение
в buf
по указанному смещению
как little-endian. Значение value
должно быть правильным беззнаковым 32-битным целым числом. Поведение функции не определено, если значение
не является беззнаковым 32-битным целым числом.
Эта функция также доступна под псевдонимом writeUint32LE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeUIntBE(value, offset, byteLength)
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байтов, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для записи. Должно удовлетворять0 < byteLength <= 6
.- Возвращает: {бесконечное число}
смещение
плюс количество записанных байт.
Записывает byteLength
байт значения
в buf
по указанному смещению
как big-endian. Поддерживает точность до 48 бит. Поведение не определено, если значение
не является целым числом без знака.
Эта функция также доступна под псевдонимом writeUintBE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
buf.writeUIntLE(value, offset, byteLength)
¶
value
<integer>
Число, которое будет записано вbuf
.offset
<integer>
Количество байтов, которое нужно пропустить перед началом записи. Должно удовлетворять условию0 <= offset <= buf.length - byteLength
.byteLength
<integer>
Количество байтов для записи. Должно удовлетворять0 < byteLength <= 6
.- Возвращает: {бесконечное число}
смещение
плюс количество записанных байт.
Записывает byteLength
байт значения
в buf
по указанному смещению
как little-endian. Поддерживает точность до 48 бит. Поведение не определено, если значение
не является целым числом без знака.
Эта функция также доступна под псевдонимом writeUintLE
.
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 |
|
new Buffer(array)
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.from(array)
вместо этого.
array
{integer[]} Массив байтов для копирования.
См. Buffer.from(array)
.
new Buffer(arrayBuffer[, byteOffset[, length]])
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.from(arrayBuffer[, byteOffset[, length]])
вместо этого.
arrayBuffer
<ArrayBuffer>
|<SharedArrayBuffer>
ArrayBuffer
,SharedArrayBuffer
или свойство.buffer
изTypedArray
.byteOffset
<integer>
Индекс первого байта для раскрытия. По умолчанию:0
.length
<integer>
Количество байтов для раскрытия. По умолчанию:arrayBuffer.byteLength - byteOffset
.
См. Buffer.from(arrayBuffer[, byteOffset[, length]])
.
new Buffer(buffer)
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.from(buffer)
вместо этого.
buffer
<Buffer>
|<Uint8Array>
СуществующийBuffer
илиUint8Array
, из которого нужно скопировать данные.
См. Buffer.from(buffer)
.
new Buffer(size)
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.alloc()
вместо этого (также смотрите Buffer.allocUnsafe()
).
size
<integer>
Желаемая длина новогобуфера
.
См. Buffer.alloc()
и Buffer.allocUnsafe()
. Этот вариант конструктора эквивалентен Buffer.alloc()
.
new Buffer(string[, encoding])
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.from(string[, encoding])
вместо этого.
См. Buffer.from(string[, encoding])
.
Класс: File
¶
Стабильность: 1 – Экспериментальная
Фича изменяется и не допускается флагом командной строки. Может быть изменена или удалена в последующих версиях.
- Расширяет:
<Blob>
File
предоставляет информацию о файлах.
новый буфер.File(sources, fileName[, options])
¶
sources
{string[]|ArrayBuffer[]|TypedArray[]|DataView[]|Blob[]|File[]} Массив объектов string,<ArrayBuffer>
,<TypedArray>
,<DataView>
, {File} или<Blob>
, или любая смесь таких объектов, которые будут храниться вфайле
.fileName
<string>
Имя файла.options
<Object>
endings
<string>
Одно из значений'transparent'
или'native'
. Если установлено значение'native'
, окончания строк в строковых исходных частях будут преобразованы к родному для платформы окончанию строк, как указано вrequire('node:os').EOL
.type
<string>
Тип содержимого файла.lastModified
<number>
Дата последнего изменения файла. По умолчанию:Date.now()
.
file.name
¶
- Тип:
<string>
Имя файла
.
file.lastModified
¶
- Тип:
<number>
Дата последнего изменения файла
.
API модуля node:buffer
¶
Хотя объект Buffer
доступен как глобальный, существуют дополнительные API, связанные с Buffer
, которые доступны только через модуль node:buffer
, доступ к которому осуществляется с помощью require('node:buffer')
.
buffer.atob(data)
¶
Стабильность: 3 – Закрыто
Принимаются только фиксы, связанные с безопасностью, производительностью или баг-фиксы. Пожалуйста, не предлагайте изменений АПИ в разделе с таким индикатором, они будут отклонены.
Вместо этого используйте Buffer.from(data, 'base64')
.
data
<any>
Входная строка в Base64-кодировке.
Декодирует строку данных в Base64-кодировке в байты и кодирует эти байты в строку с использованием Latin-1 (ISO-8859-1).
В качестве данных
может выступать любое JavaScript-значение, которое может быть преобразовано в строку.
Эта функция предоставляется только для совместимости с устаревшими API веб-платформ и никогда не должна использоваться в новом коде, поскольку они используют строки для представления двоичных данных и предшествуют внедрению типизированных массивов в JavaScript. Для кода, работающего с использованием API Node.js, преобразование между строками в кодировке base64 и двоичными данными должно выполняться с помощью Buffer.from(str, 'base64')
и buf.toString('base64')
.
buffer.btoa(data)
¶
Стабильность: 3 – Закрыто
Принимаются только фиксы, связанные с безопасностью, производительностью или баг-фиксы. Пожалуйста, не предлагайте изменений АПИ в разделе с таким индикатором, они будут отклонены.
Вместо этого используйте buf.toString('base64')
.
data
<any>
Строка ASCII (Latin1).
Декодирует строку в байты, используя Latin-1 (ISO-8859), и кодирует эти байты в строку, используя Base64.
В качестве data
может выступать любое JavaScript-значение, которое может быть преобразовано в строку.
Эта функция предоставляется только для совместимости с устаревшими API веб-платформ и никогда не должна использоваться в новом коде, поскольку они используют строки для представления двоичных данных и предшествуют внедрению типизированных массивов в JavaScript. Для кода, работающего с использованием API Node.js, преобразование между строками в кодировке base64 и двоичными данными должно выполняться с помощью Buffer.from(str, 'base64')
и buf.toString('base64')
..
buffer.isAscii(input)
¶
- input {Buffer | ArrayBuffer | TypedArray} Входные данные для проверки.
- Возвращает:
<boolean>
Эта функция возвращает true
, если input
содержит только правильные данные в ASCII-кодировке, включая случай, когда input
пуст.
Выбрасывается, если input
является отделенным буфером массива.
buffer.isUtf8(input)
¶
- input {Buffer | ArrayBuffer | TypedArray} Входные данные для проверки.
- Возвращает:
<boolean>
Эта функция возвращает true
, если input
содержит только правильные данные в кодировке UTF-8, включая случай, когда input
пуст.
Выбрасывается, если input
является отделенным буфером массива.
buffer.INSPECT_MAX_BYTES
¶
<integer>
По умолчанию:50
.
Возвращает максимальное количество байт, которое будет возвращено при вызове buf.inspect()
. Это значение может быть переопределено пользовательскими модулями. Смотрите util.inspect()
для более подробной информации о поведении buf.inspect()
.
buffer.kMaxLength
¶
<integer>
Наибольший размер, допустимый для одного экземпляраBuffer
.
Псевдоним для buffer.constants.MAX_LENGTH
.
buffer.kStringMaxLength
¶
<integer>
Наибольшая длина, допустимая для одного экземпляраstring
.
Псевдоним для buffer.constants.MAX_STRING_LENGTH
.
buffer.resolveObjectURL(id)
¶
Стабильность: 1 – Экспериментальная
Фича изменяется и не допускается флагом командной строки. Может быть изменена или удалена в последующих версиях.
id
<string>
Строка URL'blob:nodedata:...
, возвращенная предыдущим вызовомURL.createObjectURL()
.- Возвращает:
<Blob>
Разрешает 'blob:nodedata:...'
связанный объект <Blob>
, зарегистрированный с помощью предыдущего вызова URL.createObjectURL()
.
buffer.transcode(source, fromEnc, toEnc)
¶
source
<Buffer>
|<Uint8Array>
Экземплярбуфера
илиUint8Array
.fromEnc
<string>
Текущая кодировка.toEnc
<string>
Целевая кодировка.- Возвращает:
<Buffer>
Перекодирует заданный экземпляр Buffer
или Uint8Array
из одной кодировки в другую. Возвращает новый экземпляр Buffer
.
Выбрасывается, если в fromEnc
или toEnc
указаны неверные кодировки символов или если преобразование из fromEnc
в toEnc
недопустимо.
Кодировки, поддерживаемые buffer.transcode()
, следующие: ascii
, utf8
, utf16le
, ucs2
, latin1
и binary
.
Процесс транскодирования будет использовать подстановочные символы, если заданная последовательность байтов не может быть адекватно представлена в целевой кодировке. Например:
1 2 3 4 5 |
|
1 2 3 4 5 |
|
Поскольку знак евро (€
) не может быть представлен в US-ASCII, он заменяется на ?
в транскодированном буфере
.
Класс: SlowBuffer
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.allocUnsafeSlow()
вместо этого.
См. Buffer.allocUnsafeSlow()
. Это никогда не был класс в том смысле, что конструктор всегда возвращал экземпляр Buffer
, а не экземпляр SlowBuffer
.
new SlowBuffer(size)
¶
Стабильность: 0 – устарело или набрало много негативных отзывов
Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.
Используйте Buffer.allocUnsafeSlow()
вместо этого.
size
<integer>
Желаемая длина новогоSlowBuffer
.
См. Buffer.allocUnsafeSlow()
.
Буферные константы¶
buffer.constants.MAX_LENGTH
¶
<integer>
Наибольший размер, допустимый для одного экземпляраBuffer
.
На 32-битных архитектурах это значение в настоящее время составляет 230 - 1 (около 1 GiB).
На 64-битных архитектурах это значение в настоящее время составляет 232 (около 4 GiB).
Он отражает v8::TypedArray::kMaxLength
под капотом.
Это значение также доступно как buffer.kMaxLength
.
buffer.constants.MAX_STRING_LENGTH
¶
<integer>
Наибольшая длина, допустимая для одного экземплярастроки
.
Представляет собой наибольшую длину
, которую может иметь примитив строка
, подсчитанную в единицах кода UTF-16.
Это значение может зависеть от используемого JS-движка.
Buffer.from()
, Buffer.alloc()
и Buffer.allocUnsafe()
¶
В версиях Node.js до 6.0.0 экземпляры Buffer
создавались с помощью функции конструктора Buffer
, которая распределяет возвращаемый Buffer
по-разному в зависимости от того, какие аргументы были предоставлены:
- Передача числа в качестве первого аргумента в
Buffer()
(например,new Buffer(10)
) выделяет новый объектBuffer
указанного размера. До версии Node.js 8.0.0 память, выделенная для таких экземпляровBuffer
, не инициализируется и может содержать конфиденциальные данные. Такие экземплярыBuffer
должны быть впоследствии инициализированы с помощьюbuf.fill(0)
или путем записи во весьBuffer
перед чтением данных изBuffer
. Хотя такое поведение преднамеренно направлено на повышение производительности, опыт разработки показал, что требуется более явное различие между созданием быстрого, но неинициализированногоБуфера
и созданием более медленного, но безопасногоБуфера
. Начиная с Node.js 8.0.0,Buffer(num)
иnew Buffer(num)
возвращаютBuffer
с инициализированной памятью. - Передача строки, массива или
Buffer
в качестве первого аргумента копирует данные переданного объекта вBuffer
. - Передача
ArrayBuffer
илиSharedArrayBuffer
возвращаетБуфер
, который делит выделенную память с данным буфером массива.
Поскольку поведение new Buffer()
отличается в зависимости от типа первого аргумента, проблемы безопасности и надежности могут быть непреднамеренно внесены в приложения, когда не выполняется проверка аргументов или инициализация Buffer
.
Например, если злоумышленник может заставить приложение получить число, когда ожидается строка, приложение может вызвать new Buffer(100)
вместо new Buffer("100")
, что приведет к выделению 100-байтного буфера вместо выделения 3-байтного буфера с содержимым "100"
. Это обычно возможно при использовании вызовов JSON API. Поскольку JSON различает числовые и строковые типы, он позволяет вводить числа там, где наивно написанное приложение, которое не проверяет свой ввод в достаточной степени, могло бы ожидать всегда получать строку. До версии Node.js 8.0.0 100-байтовый буфер мог содержать произвольные данные в памяти, поэтому его можно было использовать для раскрытия секретов памяти удаленному злоумышленнику. Начиная с Node.js 8.0.0.0, раскрытие памяти невозможно, поскольку данные заполняются нулями. Однако другие атаки все еще возможны, например, заставить сервер выделять очень большие буферы, что приведет к снижению производительности или аварийному завершению работы при исчерпании памяти.
Чтобы сделать создание экземпляров Buffer
более надежным и менее подверженным ошибкам, различные формы конструктора new Buffer()
были удалены и заменены отдельными методами Buffer.from()
, Buffer.alloc()
и Buffer.allocUnsafe()
.
Разработчикам следует перенести все существующие варианты использования конструкторов new Buffer()
на один из этих новых API.
Buffer.from(array)
возвращает новыйBuffer
, который содержит копию предоставленных октетов.Buffer.from(arrayBuffer[, byteOffset[, length]]]
возвращает новыйБуфер
, который разделяет ту же выделенную память, что и данныйArrayBuffer
.Buffer.from(buffer)
возвращает новыйBuffer
, который содержит копию содержимого данногоBuffer
.Buffer.from(string[, encoding])
возвращает новыйБуфер
, который содержит копию предоставленной строки.Buffer.alloc(size[, fill[, encoding]])
возвращает новый инициализированныйБуфер
указанного размера. Этот метод медленнее, чемBuffer.allocUnsafe(size)
, но гарантирует, что вновь созданные экземплярыBuffer
никогда не будут содержать старые данные, которые потенциально могут быть конфиденциальными. Еслиsize
не является числом, будет выдана ошибкаTypeError
.Buffer.allocUnsafe(size)
иBuffer.allocUnsafeSlow(size)
каждый возвращает новый неинициализированныйБуфер
указанногоsize
. ПосколькуБуфер
является неинициализированным, выделенный участок памяти может содержать старые данные, которые потенциально могут быть конфиденциальными.
Экземпляры Буфера
, возвращаемые Buffer.allocUnsafe()
и Buffer.from(array)
могут быть выделены из общего внутреннего пула памяти, если size
меньше или равен половине Buffer.poolSize
. Экземпляры, возвращаемые Buffer.allocUnsafeSlow()
никогда не используют общий внутренний пул памяти.
Опция командной строки --zero-fill-buffers
¶
Node.js может быть запущен с использованием опции командной строки --zero-fill-buffers
, чтобы все вновь выделенные экземпляры Buffer
по умолчанию заполнялись нулями при создании. Без этой опции буферы, созданные с помощью Buffer.allocUnsafe()
, Buffer.allocUnsafeSlow()
и new SlowBuffer(size)
не заполняются нулем. Использование этого флага может оказать ощутимое негативное влияние на производительность. Используйте опцию --zero-fill-buffers
только в случае необходимости, чтобы убедиться, что вновь выделенные экземпляры Buffer
не могут содержать старые данные, которые являются потенциально конфиденциальными.
1 2 3 |
|
Что делает Buffer.allocUnsafe()
и Buffer.allocUnsafeSlow()
"небезопасными"?¶
При вызове Buffer.allocUnsafe()
и Buffer.allocUnsafeSlow()
сегмент выделенной памяти неинициализируется (не обнуляется). Хотя такая конструкция делает выделение памяти довольно быстрым, выделенный сегмент памяти может содержать старые данные, которые потенциально могут быть конфиденциальными. Использование буфера
, созданного с помощью Buffer.allocUnsafe()
без полной перезаписи памяти, может привести к утечке этих старых данных при чтении памяти буфера
.
Хотя использование Buffer.allocUnsafe()
имеет очевидные преимущества в производительности, необходимо соблюдать особую осторожность, чтобы избежать появления уязвимостей в безопасности приложения.