بافر

[مستقر: 2 - مستقر]

مستقر: 2 استقرار: 2 - مستقر

رمز المصدر: lib/buffer.js

تُستخدم كائنات Buffer لتمثيل تسلسل ثابت الطول من البايتات. تدعم العديد من واجهات برمجة التطبيقات في Node.js كائنات Buffer.

تُعد فئة Buffer فئة فرعية من فئة Uint8Array في جافاسكريبت Uint8Array وتوسعها بطرق تغطي حالات استخدام إضافية. تقبل واجهات برمجة التطبيقات في Node.js مصفوفات Uint8Array العادية في كل مكان تُدعم فيه كائنات Buffer أيضًا.

على الرغم من أن فئة Buffer متاحة ضمن النطاق العام، إلا أنه لا يزال من المستحسن الرجوع إليها صراحةً عبر عبارة استيراد أو require.

ESM

import { Buffer } from 'node:buffer'

//  يُنشئ بافرًا ممتلئًا بالأصفار بطول 10.
const buf1 = Buffer.alloc(10)

//  يُنشئ بافرًا بطول 10،
//  مملوءًا ببايتات قيمة كل منها `1`.
const buf2 = Buffer.alloc(10, 1)

//  يُنشئ بافرًا غير مُهيأ بطول 10.
//  هذا أسرع من استدعاء Buffer.alloc() ولكن مثيل بافر المُرجَع
//  قد يحتوي على بيانات قديمة تحتاج إلى
//  الكَتابة فوقها باستخدام fill()، أو write()، أو وظائف أخرى تملأ محتويات البافر.
const buf3 = Buffer.allocUnsafe(10)

//  يُنشئ بافرًا يحتوي على البايتات [1، 2، 3].
const buf4 = Buffer.from([1, 2, 3])

//  يُنشئ بافرًا يحتوي على البايتات [1، 1، 1، 1] – يتم اقتطاع جميع الإدخالات
//  باستخدام `(value & 255)` لتناسب النطاق من 0 إلى 255.
const buf5 = Buffer.from([257, 257.5, -255, '1'])

//  يُنشئ بافرًا يحتوي على البايتات المُشفرة بترميز UTF-8 لسلسلة 'tést':
//  [0x74، 0xc3، 0xa9، 0x73، 0x74] (بالتدوين السداسي عشري)
//  [116، 195، 169، 115، 116] (بالتدوين العشري)
const buf6 = Buffer.from('tést')

//  يُنشئ بافرًا يحتوي على البايتات اللاتينية-1 [0x74، 0xe9، 0x73، 0x74].
const buf7 = Buffer.from('tést', 'latin1')

CJS

const { Buffer } = require('node:buffer')

//  يُنشئ بافرًا ممتلئًا بالأصفار بطول 10.
const buf1 = Buffer.alloc(10)

//  يُنشئ بافرًا بطول 10،
//  مملوءًا ببايتات قيمة كل منها `1`.
const buf2 = Buffer.alloc(10, 1)

//  يُنشئ بافرًا غير مُهيأ بطول 10.
//  هذا أسرع من استدعاء Buffer.alloc() ولكن مثيل بافر المُرجَع
//  قد يحتوي على بيانات قديمة تحتاج إلى
//  الكَتابة فوقها باستخدام fill()، أو write()، أو وظائف أخرى تملأ محتويات البافر.
const buf3 = Buffer.allocUnsafe(10)

//  يُنشئ بافرًا يحتوي على البايتات [1، 2، 3].
const buf4 = Buffer.from([1, 2, 3])

//  يُنشئ بافرًا يحتوي على البايتات [1، 1، 1، 1] – يتم اقتطاع جميع الإدخالات
//  باستخدام `(value & 255)` لتناسب النطاق من 0 إلى 255.
const buf5 = Buffer.from([257, 257.5, -255, '1'])

//  يُنشئ بافرًا يحتوي على البايتات المُشفرة بترميز UTF-8 لسلسلة 'tést':
//  [0x74، 0xc3، 0xa9، 0x73، 0x74] (بالتدوين السداسي عشري)
//  [116، 195، 169، 115، 116] (بالتدوين العشري)
const buf6 = Buffer.from('tést')

//  يُنشئ بافرًا يحتوي على البايتات اللاتينية-1 [0x74، 0xe9، 0x73، 0x74].
const buf7 = Buffer.from('tést', 'latin1')

المخازن وتشفير الأحرف

[التاريخ]

الإصدار	التغييرات
v15.7.0، v14.18.0	تم تقديم ترميز base64url.
v6.4.0	تم تقديم latin1 كاسم مستعار لـ binary.
v5.0.0	تمت إزالة ترميزات raw و raws التي عفا عليها الزمن.

عند التحويل بين Buffer والأسطر، يمكن تحديد تشفير الأحرف. إذا لم يتم تحديد تشفير الأحرف، فسيتم استخدام UTF-8 كقيمة افتراضية.

ESM

import { Buffer } from 'node:buffer'

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

console.log(buf.toString('hex'))
// يطبع: 68656c6c6f20776f726c64
console.log(buf.toString('base64'))
// يطبع: aGVsbG8gd29ybGQ=

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

CJS

const { Buffer } = require('node:buffer')

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

console.log(buf.toString('hex'))
// يطبع: 68656c6c6f20776f726c64
console.log(buf.toString('base64'))
// يطبع: aGVsbG8gd29ybGQ=

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

تقبل مخازن Node.js جميع أشكال الأحرف الكبيرة والصغيرة لسلاسل ترميز التشفير التي تتلقاها. على سبيل المثال، يمكن تحديد UTF-8 كـ 'utf8' أو 'UTF8' أو 'uTf8'.

تشفير الأحرف المدعومة حاليًا بواسطة Node.js هي:

• 'utf8' (اسم مستعار: 'utf-8'): أحرف Unicode المشفرة متعددة البايت. تستخدم العديد من صفحات الويب وتنسيقات المستندات الأخرى UTF-8. هذا هو تشفير الأحرف الافتراضي. عند فك تشفير Buffer إلى سلسلة لا تحتوي حصريًا على بيانات UTF-8 صالحة، سيتم استخدام حرف الاستبدال Unicode U+FFFD � لتمثيل تلك الأخطاء.
• 'utf16le' (اسم مستعار: 'utf-16le'): أحرف Unicode المشفرة متعددة البايت. على عكس '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، القسم 5. عند إنشاء Buffer من سلسلة، سيتقبل هذا التشفير أيضًا بشكل صحيح السلاسل المشفرة بـ base64 العادية. عند تشفير Buffer إلى سلسلة، سيُهمل هذا التشفير الحشو.
• 'hex': قم بتشفير كل بايت كحرفين سداسيين عشريين. قد يحدث اقتطاع للبيانات عند فك تشفير السلاسل التي لا تتكون حصريًا من عدد زوجي من الأحرف السداسية عشرية. انظر أدناه للحصول على مثال.

يتم أيضًا دعم ترميزات تشفير الأحرف القديمة التالية:

• 'ascii': لبيانات ASCII ذات 7 بت فقط. عند تشفير سلسلة إلى Buffer، يكون هذا مكافئًا لاستخدام 'latin1'. عند فك تشفير Buffer إلى سلسلة، سيؤدي استخدام هذا التشفير إلى إلغاء تعيين البت الأعلى لكل بايت قبل فك التشفير كـ 'latin1'. بشكل عام، لا ينبغي أن يكون هناك سبب لاستخدام هذا التشفير، حيث أن 'utf8' (أو، إذا كان من المعروف أن البيانات ASCII فقط، 'latin1') سيكون خيارًا أفضل عند تشفير أو فك تشفير نص ASCII فقط. يتم توفيره فقط للتوافق مع الإصدارات القديمة.
• 'binary': اسم مستعار لـ 'latin1'. قد يكون اسم هذا التشفير مضللاً للغاية، حيث تقوم جميع ترميزات التشفير المدرجة هنا بالتحويل بين السلاسل والبيانات الثنائية. لتحويل السلاسل وBuffer، عادةً ما يكون 'utf8' هو الخيار الصحيح.
• 'ucs2', 'ucs-2': أسماء مستعارة لـ 'utf16le'. كان UCS-2 يشير إلى متغير من UTF-16 لم يدعم الأحرف التي تحتوي على نقاط رمز أكبر من U+FFFF. في Node.js، يتم دائمًا دعم نقاط الرمز هذه.

ESM

import { Buffer } from 'node:buffer'

Buffer.from('1ag123', 'hex')
// يطبع <Buffer 1a>، بيانات مقطوعة عندما يتم مواجهة أول قيمة غير سداسية عشرية
// ('g').

Buffer.from('1a7', 'hex')
// يطبع <Buffer 1a>، بيانات مقطوعة عندما تنتهي البيانات برقم واحد ('7').

Buffer.from('1634', 'hex')
// يطبع <Buffer 16 34>، جميع البيانات ممثلة.

CJS

const { Buffer } = require('node:buffer')

Buffer.from('1ag123', 'hex')
// يطبع <Buffer 1a>، بيانات مقطوعة عندما يتم مواجهة أول قيمة غير سداسية عشرية
// ('g').

Buffer.from('1a7', 'hex')
// يطبع <Buffer 1a>، بيانات مقطوعة عندما تنتهي البيانات برقم واحد ('7').

Buffer.from('1634', 'hex')
// يطبع <Buffer 16 34>، جميع البيانات ممثلة.

تتبع متصفحات الويب الحديثة معيار ترميز WHATWG الذي يُعطي أسماءً مستعارة لكل من 'latin1' و 'ISO-8859-1' إلى 'win-1252'. هذا يعني أنه عند القيام بشيء مثل http.get()، إذا كانت مجموعة الأحرف المعادة هي واحدة من المدرجة في مواصفات WHATWG، فمن الممكن أن يكون الخادم قد أعاد بالفعل بيانات مشفرة بـ 'win-1252'، وقد يؤدي استخدام ترميز 'latin1' إلى فك تشفير الأحرف بشكل غير صحيح.

المخازن المؤقتة وTypedArrays

[السجل]

الإصدار	التغييرات
v3.0.0	فئة Buffer ترث الآن من Uint8Array.

تُعدّ مثيلات Buffer أيضًا مثيلات من Uint8Array وTypedArray في جافا سكريبت. تتوفر جميع طرق TypedArray على Buffers. ومع ذلك، هناك عدم توافقات طفيفة بين واجهة برمجة التطبيقات Buffer وواجهة برمجة التطبيقات TypedArray.

على وجه الخصوص:

• بينما يقوم TypedArray.prototype.slice() بإنشاء نسخة من جزء من TypedArray، يقوم Buffer.prototype.slice() بإنشاء عرض على Buffer الموجود دون نسخ. يمكن أن يكون هذا السلوك مفاجئًا، ولا يوجد إلا للتوافق مع الإصدارات القديمة. يمكن استخدام TypedArray.prototype.subarray() لتحقيق سلوك Buffer.prototype.slice() على كل من Buffers وTypedArrays الأخرى ويجب أن يكون هو المفضل.
• buf.toString() غير متوافق مع نظيره في TypedArray.
• يدعم عدد من الطرق، مثل buf.indexOf()، حججًا إضافية.

هناك طريقتان لإنشاء مثيلات جديدة من TypedArray من Buffer:

• يؤدي تمرير Buffer إلى مُنشئ TypedArray إلى نسخ محتويات Buffer، مُفسّرة كمصفوفة من الأعداد الصحيحة، وليس كتسلسل بايت من النوع الهدف.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([1, 2, 3, 4])
const uint32array = new Uint32Array(buf)

console.log(uint32array)

// يطبع: Uint32Array(4) [ 1, 2, 3, 4 ]

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([1, 2, 3, 4])
const uint32array = new Uint32Array(buf)

console.log(uint32array)

// يطبع: Uint32Array(4) [ 1, 2, 3, 4 ]

• يؤدي تمرير ArrayBuffer الأساسي لـBuffer إلى إنشاء TypedArray يشارك ذاكرته مع Buffer.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('hello', 'utf16le')
const uint16array = new Uint16Array(buf.buffer, buf.byteOffset, buf.length / Uint16Array.BYTES_PER_ELEMENT)

console.log(uint16array)

// يطبع: Uint16Array(5) [ 104, 101, 108, 108, 111 ]

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('hello', 'utf16le')
const uint16array = new Uint16Array(buf.buffer, buf.byteOffset, buf.length / Uint16Array.BYTES_PER_ELEMENT)

console.log(uint16array)

// يطبع: Uint16Array(5) [ 104, 101, 108, 108, 111 ]

من الممكن إنشاء Buffer جديد يشارك نفس الذاكرة المخصصة مع مثيل TypedArray باستخدام خاصية .buffer لكائن TypedArray بنفس الطريقة. يتصرف Buffer.from() مثل new Uint8Array() في هذا السياق.

ESM

import { Buffer } from 'node:buffer'

const arr = new Uint16Array(2)

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

// ينسخ محتويات `arr`.
const buf1 = Buffer.from(arr)

// يشارك الذاكرة مع `arr`.
const buf2 = Buffer.from(arr.buffer)

console.log(buf1)
// يطبع: <Buffer 88 a0>
console.log(buf2)
// يطبع: <Buffer 88 13 a0 0f>

arr[1] = 6000

console.log(buf1)
// يطبع: <Buffer 88 a0>
console.log(buf2)
// يطبع: <Buffer 88 13 70 17>

CJS

const { Buffer } = require('node:buffer')

const arr = new Uint16Array(2)

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

// ينسخ محتويات `arr`.
const buf1 = Buffer.from(arr)

// يشارك الذاكرة مع `arr`.
const buf2 = Buffer.from(arr.buffer)

console.log(buf1)
// يطبع: <Buffer 88 a0>
console.log(buf2)
// يطبع: <Buffer 88 13 a0 0f>

arr[1] = 6000

console.log(buf1)
// يطبع: <Buffer 88 a0>
console.log(buf2)
// يطبع: <Buffer 88 13 70 17>

عند إنشاء Buffer باستخدام .buffer لـTypedArray، من الممكن استخدام جزء فقط من ArrayBuffer الأساسي عن طريق تمرير معلمات byteOffset وlength.

ESM

import { Buffer } from 'node:buffer'

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

console.log(buf.length)
// يطبع: 16

CJS

const { Buffer } = require('node:buffer')

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

console.log(buf.length)
// يطبع: 16

لـ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:

ESM

import { Buffer } from 'node:buffer'

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

for (const b of buf) {
  console.log(b)
}
// يطبع:
//   1
//   2
//   3

CJS

const { Buffer } = require('node:buffer')

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

for (const b of buf) {
  console.log(b)
}
// يطبع:
//   1
//   2
//   3

بالإضافة إلى ذلك، يمكن استخدام طرق buf.values()، وbuf.keys()، وbuf.entries() لإنشاء مُكررات.

الفئة: Blob

[السجل]

الإصدار	التغييرات
v18.0.0، v16.17.0	لم يعد تجريبيًا.
v15.7.0، v14.18.0	تمت الإضافة في: v15.7.0، v14.18.0

يكبس كائن Blob بيانات خام ثابتة يمكن مشاركتها بأمان عبر العديد من خيوط العامل.

new buffer.Blob([sources[, options]])

[السجل]

الإصدار	التغييرات
v16.7.0	تمت إضافة خيار endings القياسي لاستبدال نهايات الأسطر، وإزالة خيار encoding غير القياسي.
v15.7.0، v14.18.0	تمت الإضافة في: v15.7.0، v14.18.0

• sources <string[]> | <ArrayBuffer[]> | <TypedArray[]> | <DataView[]> | <Blob[]> مصفوفة من سلاسل، <ArrayBuffer>، <TypedArray>، <DataView>، أو <Blob> كائنات، أو أي مزيج من هذه الكائنات، سيتم تخزينها داخل Blob.
• options <Object>
  • endings <string> أحد 'transparent' أو 'native'. عند تعيينه على 'native'، سيتم تحويل نهايات الأسطر في أجزاء المصدر السلسلة إلى نهاية السطر الأصلية للمنصة كما هو محدد بواسطة require('node:os').EOL.
  • type <string> نوع محتوى Blob. الهدف من type هو نقل نوع وسائط MIME للبيانات، ومع ذلك، لا يتم إجراء أي التحقق من صحة تنسيق النوع.

يُنشئ كائن Blob جديدًا يحتوي على سلسلة من المصادر المعطاة.

يتم نسخ مصادر <ArrayBuffer>، <TypedArray>، <DataView>، و <Buffer> في 'Blob' وبالتالي يمكن تعديلها بأمان بعد إنشاء 'Blob'.

يتم ترميز مصادر السلاسل كمتواليات بايت UTF-8 ونسخها في Blob. سيتم استبدال أزواج الوكيل غير المتطابقة داخل كل جزء سلسلة بأحرف استبدال Unicode U+FFFD.

blob.arrayBuffer()

أضيف في: v15.7.0، v14.18.0

• القيمة المُرجعة: <Promise>

يرجع وعدًا يُنجز بـ <ArrayBuffer> يحتوي على نسخة من بيانات Blob.

blob.bytes()

أضيف في: v22.3.0، v20.16.0

ترجع طريقة blob.bytes() بايتات كائن Blob كـ Promise\<Uint8Array\>.

const blob = new Blob(['hello'])
blob.bytes().then(bytes => {
  console.log(bytes) // يُخرج: Uint8Array(5) [ 104, 101, 108, 108, 111 ]
})

blob.size

أضيف في: v15.7.0، v14.18.0

الحجم الإجمالي لـ Blob بالبايت.

blob.slice([start[, end[, type]]])

أضيف في: v15.7.0، v14.18.0

• start <number> مؤشر البداية.
• end <number> مؤشر النهاية.
• type <string> نوع المحتوى لـ Blob الجديد.

يُنشئ ويرجع Blob جديدًا يحتوي على مجموعة فرعية من بيانات كائن Blob هذا. لا يتغير Blob الأصلي.

blob.stream()

أضيف في: v16.7.0

• القيمة المُرجعة: <ReadableStream>

يرجع ReadableStream جديدًا يسمح بقراءة محتوى Blob.

blob.text()

أضيف في: v15.7.0، v14.18.0

• القيمة المُرجعة: <Promise>

يرجع وعدًا يُنجز بمحتويات Blob المُشفّرة كسلسلة نصية UTF-8.

blob.type

أضيف في: v15.7.0، v14.18.0

• النوع: <string>

نوع محتوى Blob.

كائنات Blob و MessageChannel

بمجرد إنشاء كائن <Blob> ، يمكن إرساله عبر MessagePort إلى وجهات متعددة دون نقل أو نسخ البيانات على الفور. لا يتم نسخ البيانات الموجودة في Blob إلا عند استدعاء طرق arrayBuffer() أو text().

ESM

import { Blob } from 'node:buffer'
import { setTimeout as delay } from 'node:timers/promises'

const blob = new Blob(['hello there'])

const mc1 = new MessageChannel()
const mc2 = new MessageChannel()

mc1.port1.onmessage = async ({ data }) => {
  console.log(await data.arrayBuffer())
  mc1.port1.close()
}

mc2.port1.onmessage = async ({ data }) => {
  await delay(1000)
  console.log(await data.arrayBuffer())
  mc2.port1.close()
}

mc1.port2.postMessage(blob)
mc2.port2.postMessage(blob)

// لا يزال بإمكان استخدام Blob بعد النشر.
blob.text().then(console.log)

CJS

const { Blob } = require('node:buffer')
const { setTimeout: delay } = require('node:timers/promises')

const blob = new Blob(['hello there'])

const mc1 = new MessageChannel()
const mc2 = new MessageChannel()

mc1.port1.onmessage = async ({ data }) => {
  console.log(await data.arrayBuffer())
  mc1.port1.close()
}

mc2.port1.onmessage = async ({ data }) => {
  await delay(1000)
  console.log(await data.arrayBuffer())
  mc2.port1.close()
}

mc1.port2.postMessage(blob)
mc2.port2.postMessage(blob)

// لا يزال بإمكان استخدام Blob بعد النشر.
blob.text().then(console.log)

الفئة: Buffer

الفئة Buffer هي نوع عام للتعامل مع البيانات الثنائية مباشرة. يمكن إنشاؤها بطرق متنوعة.

طريقة ثابتة: Buffer.alloc(size[, fill[, encoding]])

[History]

الإصدار	التغييرات
v20.0.0	طرح ERR_INVALID_ARG_TYPE أو ERR_OUT_OF_RANGE بدلاً من ERR_INVALID_ARG_VALUE للحجج المدخلة غير الصالحة.
v15.0.0	طرح ERR_INVALID_ARG_VALUE بدلاً من ERR_INVALID_OPT_VALUE للحجج المدخلة غير الصالحة.
v10.0.0	محاولة ملء مُخزن مؤقت غير صفري بطول صفري تُؤدي إلى استثناء مُطرح.
v10.0.0	تحديد سلسلة غير صالحة لـ fill يُؤدي إلى استثناء مُطرح.
v8.9.3	تحديد سلسلة غير صالحة لـ fill يُؤدي الآن إلى مُخزن مؤقت مُملوء بالأصفار.
v5.10.0	تمت الإضافة في: v5.10.0

• size <integer> الطول المطلوب للمُخزن المؤقت الجديد Buffer.
• fill <string> | <Buffer> | <Uint8Array> | <integer> قيمة لملء المُخزن المؤقت الجديد Buffer مسبقًا. الافتراضي: 0.
• encoding <string> إذا كان fill سلسلة، فهذا هو ترميزها. الافتراضي: 'utf8'.
• الإرجاع: <Buffer>

يخصص مُخزنًا مؤقتًا جديدًا من نوع Buffer بحجم size بايت. إذا كان fill غير مُعرّف، فسيتم ملء Buffer بالأصفار.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.alloc(5)

console.log(buf)
// يُطبع: <Buffer 00 00 00 00 00>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(5)

console.log(buf)
// يُطبع: <Buffer 00 00 00 00 00>

إذا كان size أكبر من buffer.constants.MAX_LENGTH أو أصغر من 0، فسيتم طرح ERR_OUT_OF_RANGE.

إذا تم تحديد fill، فسيتم تهيئة Buffer المُخصص من خلال استدعاء buf.fill(fill).

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.alloc(5, 'a')

console.log(buf)
// يُطبع: <Buffer 61 61 61 61 61>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(5, 'a')

console.log(buf)
// يُطبع: <Buffer 61 61 61 61 61>

إذا تم تحديد كل من fill و encoding، فسيتم تهيئة Buffer المُخصص من خلال استدعاء buf.fill(fill, encoding).

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64')

console.log(buf)
// يُطبع: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64')

console.log(buf)
// يُطبع: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>

قد يكون استدعاء Buffer.alloc() أبطأ بشكل ملحوظ من البديل Buffer.allocUnsafe() ولكنه يضمن ألا تحتوي محتويات مثيل Buffer المُنشأ حديثًا أبدًا على بيانات حساسة من التخصيصات السابقة، بما في ذلك البيانات التي قد لا تكون مُخصصة لـ Buffers.

سيتم طرح TypeError إذا لم يكن size رقمًا.

طريقة ثابتة: Buffer.allocUnsafe(size)

[السجل]

الإصدار	التغييرات
v20.0.0	يُطرح ERR_INVALID_ARG_TYPE أو ERR_OUT_OF_RANGE بدلاً من ERR_INVALID_ARG_VALUE للحجج المدخلة غير الصالحة.
v15.0.0	يُطرح ERR_INVALID_ARG_VALUE بدلاً من ERR_INVALID_OPT_VALUE للحجج المدخلة غير الصالحة.
v7.0.0	سيلقي تمرير size سالب الآن خطأ.
v5.10.0	تمت الإضافة في: v5.10.0

• size <عدد صحيح> الطول المطلوب لـ Buffer الجديد.
• المُرجَع: <Buffer>

يُخصّص Buffer جديدًا بحجم size بايت. إذا كان size أكبر من buffer.constants.MAX_LENGTH أو أصغر من 0، فسيتم طرح ERR_OUT_OF_RANGE.

الذاكرة الأساسية لمعتمدات Buffer المُنشأة بهذه الطريقة ليست مُهيّأة. محتوى Buffer المُنشأ حديثًا غير معروف وقد يحتوي على بيانات حساسة. استخدم Buffer.alloc() بدلاً من ذلك لتهيئة مُعتمدات Buffer بالأصفار.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(10)

console.log(buf)
// يُطبع (قد يختلف المحتوى): <Buffer a0 8b 28 3f 01 00 00 00 50 32>

buf.fill(0)

console.log(buf)
// يُطبع: <Buffer 00 00 00 00 00 00 00 00 00 00>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(10)

console.log(buf)
// يُطبع (قد يختلف المحتوى): <Buffer a0 8b 28 3f 01 00 00 00 50 32>

buf.fill(0)

console.log(buf)
// يُطبع: <Buffer 00 00 00 00 00 00 00 00 00 00>

سيتم طرح TypeError إذا لم يكن size رقمًا.

تُخصّص وحدة Buffer مُسبقًا مُعتمد Buffer داخليًا بحجم Buffer.poolSize يُستخدم كمجموعة لتخصيص مُعتمدات Buffer الجديدة بسرعة المُنشأة باستخدام Buffer.allocUnsafe()، Buffer.from(array)، Buffer.from(string)، وBuffer.concat() فقط عندما يكون 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(size)

[السجل]

الإصدار	التغييرات
v20.0.0	طرح ERR_INVALID_ARG_TYPE أو ERR_OUT_OF_RANGE بدلاً من ERR_INVALID_ARG_VALUE للحجج المدخلة غير الصالحة.
v15.0.0	طرح ERR_INVALID_ARG_VALUE بدلاً من ERR_INVALID_OPT_VALUE للحجج المدخلة غير الصالحة.
v5.12.0	تمت الإضافة في: v5.12.0

• size <عدد صحيح> الطول المطلوب لـ Buffer الجديد.
• الإرجاع: <Buffer>

يُخصص Buffer جديدًا بحجم size بايت. إذا كان حجم size أكبر من buffer.constants.MAX_LENGTH أو أصغر من 0، فسيتم طرح ERR_OUT_OF_RANGE. يتم إنشاء Buffer بطول صفري إذا كان size يساوي 0.

الذاكرة الأساسية لمعطيات Buffer التي تم إنشاؤها بهذه الطريقة ليست مُهيأة. محتوى Buffer الذي تم إنشاؤه حديثًا غير معروف وقد يحتوي على بيانات حساسة. استخدم buf.fill(0) لتهيئة معطيات Buffer هذه بالأصفار.

عند استخدام Buffer.allocUnsafe() لتخصيص معطيات Buffer جديدة، يتم تقطيع التخصيصات الأقل من Buffer.poolSize \>\>\> 1 (4 كيلوبايت عندما يتم استخدام poolSize الافتراضي) من Buffer مُخصص مسبقًا واحد. يسمح هذا للتطبيقات بتجنب عبء جمع القمامة الناتج عن إنشاء العديد من معطيات Buffer المُخصصة بشكل فردي. يحسّن هذا النهج الأداء واستخدام الذاكرة من خلال القضاء على الحاجة إلى تتبع وتنظيف العديد من كائنات ArrayBuffer الفردية.

ومع ذلك، في حالة احتياج المطور إلى الاحتفاظ بجزء صغير من الذاكرة من مجموعة مؤقتة لفترة زمنية غير محددة، قد يكون من المناسب إنشاء مثيل Buffer غير مُجمّع باستخدام Buffer.allocUnsafeSlow() ثم نسخ البيانات ذات الصلة.

ESM

import { Buffer } from 'node:buffer'

// تحتاج إلى الاحتفاظ ببعض القطع الصغيرة من الذاكرة.
const store = []

socket.on('readable', () => {
  let data
  while (null !== (data = readable.read())) {
    // تخصيص للبيانات المُحتفظ بها.
    const sb = Buffer.allocUnsafeSlow(10)

    // نسخ البيانات إلى التخصيص الجديد.
    data.copy(sb, 0, 0, 10)

    store.push(sb)
  }
})

CJS

const { Buffer } = require('node:buffer')

// تحتاج إلى الاحتفاظ ببعض القطع الصغيرة من الذاكرة.
const store = []

socket.on('readable', () => {
  let data
  while (null !== (data = readable.read())) {
    // تخصيص للبيانات المُحتفظ بها.
    const sb = Buffer.allocUnsafeSlow(10)

    // نسخ البيانات إلى التخصيص الجديد.
    data.copy(sb, 0, 0, 10)

    store.push(sb)
  }
})

سيتم طرح TypeError إذا لم يكن size رقمًا.

طريقة ثابتة: Buffer.byteLength(string[, encoding])

[السجل]

الإصدار	التغييرات
v7.0.0	إدخال بيانات غير صالحة سيؤدي الآن إلى ظهور خطأ.
v5.10.0	يمكن أن تكون معلمة string الآن أي من TypedArray أو DataView أو ArrayBuffer.
v0.1.90	تمت الإضافة في: v0.1.90

• string <سلسلة> | <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <SharedArrayBuffer> قيمة لحساب طولها.
• encoding <سلسلة> إذا كانت string سلسلة، فهذا هو ترميزها. الافتراضي: 'utf8'.
• القيمة المُرجعة: <عدد صحيح> عدد البايتات الموجودة داخل string.

يُرجع طول البايت لسلسلة عند ترميزها باستخدام encoding. هذا ليس هو نفسه String.prototype.length، والذي لا يأخذ في الاعتبار الترميز المستخدم لتحويل السلسلة إلى بايتات.

بالنسبة إلى 'base64' و'base64url' و'hex'، تفترض هذه الدالة إدخالًا صحيحًا. بالنسبة للسلاسل التي تحتوي على بيانات غير مشفرة بـ base64/hex (مثل المسافات البيضاء)، قد تكون القيمة المُرجعة أكبر من طول Buffer المُنشأ من السلسلة.

ESM

import { Buffer } from 'node:buffer'

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

console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`)
// يطبع: ½ + ¼ = ¾: 9 characters, 12 bytes

CJS

const { Buffer } = require('node:buffer')

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

console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`)
// يطبع: ½ + ¼ = ¾: 9 characters, 12 bytes

عندما تكون string عبارة عن Buffer/ DataView/TypedArray/ArrayBuffer/SharedArrayBuffer، يتم إرجاع طول البايت كما هو مُبلغ عنه بواسطة .byteLength.

طريقة ثابتة: Buffer.compare(buf1, buf2)

[السجل]

الإصدار	التغييرات
v8.0.0	يمكن الآن أن تكون الوسيطات عبارة عن Uint8Arrays.
v0.11.13	تمت الإضافة في: v0.11.13

• buf1 <Buffer> | <Uint8Array>
• buf2 <Buffer> | <Uint8Array>
• القيمة المُرجعة: <عدد صحيح> إما -1، أو 0، أو 1، بناءً على نتيجة المقارنة. راجع buf.compare() للحصول على التفاصيل.

يقارن buf1 مع buf2، عادةً لغرض فرز مصفوفات مثيلات Buffer. هذا ما يعادل استدعاء buf1.compare(buf2).

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('1234')
const buf2 = Buffer.from('0123')
const arr = [buf1, buf2]

console.log(arr.sort(Buffer.compare))
// يُطبع: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (هذه النتيجة تساوي: [buf2, buf1].)

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('1234')
const buf2 = Buffer.from('0123')
const arr = [buf1, buf2]

console.log(arr.sort(Buffer.compare))
// يُطبع: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (هذه النتيجة تساوي: [buf2, buf1].)

طريقة ثابتة: Buffer.concat(list[, totalLength])

[السجل]

الإصدار	التغييرات
v8.0.0	يمكن الآن أن تكون عناصر list عبارة عن Uint8Arrays.
v0.7.11	تمت الإضافة في: v0.7.11

• list <Buffer[]> | <Uint8Array[]> قائمة بمثيلات Buffer أو Uint8Array ليتم دمجها.
• totalLength <عدد صحيح> الطول الإجمالي لمعطيات Buffer في list عند دمجها.
• القيمة المُرجعة: <Buffer>

يُرجع Buffer جديدًا وهو نتيجة دمج جميع مثيلات Buffer في list معًا.

إذا لم تحتوي القائمة على أي عناصر، أو إذا كان totalLength يساوي 0، فسيتم إرجاع Buffer جديد بطول صفري.

إذا لم يتم توفير totalLength، فسيتم حسابه من مثيلات Buffer في list عن طريق إضافة أطوالها.

إذا تم توفير totalLength، فسيتم تحويله إلى عدد صحيح غير سالب. إذا تجاوز الطول المجمع لمعطيات Buffer في list قيمة totalLength، فسيتم اقتطاع النتيجة إلى totalLength. إذا كان الطول المجمع لمعطيات Buffer في list أقل من totalLength، فسيتم ملء المساحة المتبقية بالأصفار.

ESM

import { Buffer } from 'node:buffer'

// إنشاء `Buffer` واحد من قائمة بثلاث مثيلات `Buffer`.

const buf1 = Buffer.alloc(10)
const buf2 = Buffer.alloc(14)
const buf3 = Buffer.alloc(18)
const totalLength = buf1.length + buf2.length + buf3.length

console.log(totalLength)
// يُطبع: 42

const bufA = Buffer.concat([buf1, buf2, buf3], totalLength)

console.log(bufA)
// يُطبع: <Buffer 00 00 00 00 ...>
console.log(bufA.length)
// يُطبع: 42

CJS

const { Buffer } = require('node:buffer')

// إنشاء `Buffer` واحد من قائمة بثلاث مثيلات `Buffer`.

const buf1 = Buffer.alloc(10)
const buf2 = Buffer.alloc(14)
const buf3 = Buffer.alloc(18)
const totalLength = buf1.length + buf2.length + buf3.length

console.log(totalLength)
// يُطبع: 42

const bufA = Buffer.concat([buf1, buf2, buf3], totalLength)

console.log(bufA)
// يُطبع: <Buffer 00 00 00 00 ...>
console.log(bufA.length)
// يُطبع: 42

قد تستخدم Buffer.concat() أيضًا تجمع Buffer الداخلي مثل Buffer.allocUnsafe().

طريقة ثابتة: Buffer.copyBytesFrom(view[, offset[, length]])

مضاف في: v19.8.0، v18.16.0

• view <TypedArray> <TypedArray> المراد نسخه.
• offset <integer> الإزاحة الأولية داخل view. افتراضي: 0.
• length <integer> عدد العناصر المراد نسخها من view. افتراضي: view.length - offset.
• القيمة المُرجعة: <Buffer>

ينسخ الذاكرة الأساسية لـ view إلى Buffer جديد.

const u16 = new Uint16Array([0, 0xffff])
const buf = Buffer.copyBytesFrom(u16, 1, 1)
u16[1] = 0
console.log(buf.length) // 2
console.log(buf[0]) // 255
console.log(buf[1]) // 255

طريقة ثابتة: Buffer.from(array)

مضاف في: v5.10.0

• array <integer[]>
• القيمة المُرجعة: <Buffer>

يخصص Buffer جديدًا باستخدام مُصفوفة من البايتات في النطاق 0 – 255. سيتم اقتصاص مُدخَلات المصفوفة خارج هذا النطاق لتلائمه.

ESM

import { Buffer } from 'node:buffer'

// يقوم بإنشاء Buffer جديد يحتوي على بايتات UTF-8 لسلسلة "buffer".
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72])

CJS

const { Buffer } = require('node:buffer')

// يقوم بإنشاء Buffer جديد يحتوي على بايتات UTF-8 لسلسلة "buffer".
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72])

إذا كان array كائنًا شبيهًا بمصفوفة (أي، كائن له خاصية length من نوع number)، فسيتم التعامل معه كما لو كان مصفوفة، ما لم يكن Buffer أو Uint8Array. وهذا يعني أن جميع المتغيرات الأخرى لـ TypedArray تُعامل كمصفوفة. لإنشاء Buffer من البايتات الأساسية لـ TypedArray، استخدم Buffer.copyBytesFrom().

سيتم إرسال TypeError إذا لم يكن array مصفوفة أو نوعًا آخر مناسبًا لمتغيرات Buffer.from().

قد يستخدم Buffer.from(array) و Buffer.from(string) أيضًا مجموعة Buffer الداخلية مثلما تفعل Buffer.allocUnsafe().

طريقة ثابتة: Buffer.from(arrayBuffer[, byteOffset[, length]])

مضاف في: v5.10.0

• arrayBuffer <ArrayBuffer> | <SharedArrayBuffer> ArrayBuffer أو SharedArrayBuffer، مثل خاصية .buffer لـ TypedArray.
• byteOffset <عدد صحيح> مؤشر أول بايت ليتم عرضه. افتراضي: 0.
• length <عدد صحيح> عدد البايتات التي سيتم عرضها. افتراضي: arrayBuffer.byteLength - byteOffset.
• مُخرجات: <Buffer>

يقوم هذا بإنشاء عرض لـ ArrayBuffer بدون نسخ الذاكرة الأساسية. على سبيل المثال، عند تمرير مرجع إلى خاصية .buffer لمثيل TypedArray، فإن Buffer المُنشأ حديثًا سيتشارك نفس الذاكرة المُخصصة مع TypedArraysArrayBuffer` الأساسي.

ESM

import { Buffer } from 'node:buffer'

const arr = new Uint16Array(2)

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

// يشارك الذاكرة مع `arr`.
const buf = Buffer.from(arr.buffer)

console.log(buf)
// يُطبع: <Buffer 88 13 a0 0f>

// تغيير `Uint16Array` الأصلي يُغيّر `Buffer` أيضًا.
arr[1] = 6000

console.log(buf)
// يُطبع: <Buffer 88 13 70 17>

CJS

const { Buffer } = require('node:buffer')

const arr = new Uint16Array(2)

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

// يشارك الذاكرة مع `arr`.
const buf = Buffer.from(arr.buffer)

console.log(buf)
// يُطبع: <Buffer 88 13 a0 0f>

// تغيير `Uint16Array` الأصلي يُغيّر `Buffer` أيضًا.
arr[1] = 6000

console.log(buf)
// يُطبع: <Buffer 88 13 70 17>

تحدد وسيطتا byteOffset و length الاختياريان نطاق ذاكرة داخل arrayBuffer سيتشاركه Buffer.

ESM

import { Buffer } from 'node:buffer'

const ab = new ArrayBuffer(10)
const buf = Buffer.from(ab, 0, 2)

console.log(buf.length)
// يُطبع: 2

CJS

const { Buffer } = require('node:buffer')

const ab = new ArrayBuffer(10)
const buf = Buffer.from(ab, 0, 2)

console.log(buf.length)
// يُطبع: 2

سيتم طرح TypeError إذا لم يكن arrayBuffer ArrayBuffer أو SharedArrayBuffer أو نوع آخر مناسب لمتغيرات Buffer.from().

من المهم أن تتذكر أن ArrayBuffer الداعم يمكن أن يغطي نطاقًا من الذاكرة يتجاوز حدود عرض TypedArray. قد يتجاوز Buffer جديد تم إنشاؤه باستخدام خاصية buffer لـ TypedArray نطاق TypedArray:

ESM

import { Buffer } from 'node:buffer'

const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]) // 4 عناصر
const arrB = new Uint8Array(arrA.buffer, 1, 2) // 2 عناصر
console.log(arrA.buffer === arrB.buffer) // true

const buf = Buffer.from(arrB.buffer)
console.log(buf)
// يُطبع: <Buffer 63 64 65 66>

CJS

const { Buffer } = require('node:buffer')

const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]) // 4 عناصر
const arrB = new Uint8Array(arrA.buffer, 1, 2) // 2 عناصر
console.log(arrA.buffer === arrB.buffer) // true

const buf = Buffer.from(arrB.buffer)
console.log(buf)
// يُطبع: <Buffer 63 64 65 66>

طريقة ثابتة: Buffer.from(buffer)

مضاف في: v5.10.0

• buffer <Buffer> | <Uint8Array> Buffer موجود أو Uint8Array لنسخ البيانات منه.
• قيمة الإرجاع: <Buffer>

ينسخ بيانات buffer المُمرّرة إلى مثيل جديد من Buffer.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('buffer')
const buf2 = Buffer.from(buf1)

buf1[0] = 0x61

console.log(buf1.toString())
// يُطبع: auffer
console.log(buf2.toString())
// يُطبع: buffer

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('buffer')
const buf2 = Buffer.from(buf1)

buf1[0] = 0x61

console.log(buf1.toString())
// يُطبع: auffer
console.log(buf2.toString())
// يُطبع: buffer

سيتم إرسال TypeError إذا لم يكن buffer Buffer أو نوعًا آخر مناسبًا لمتغيرات Buffer.from().

طريقة ثابتة: Buffer.from(object[, offsetOrEncoding[, length]])

مضاف في: v8.2.0

• object <Object> كائن يدعم Symbol.toPrimitive أو valueOf().
• offsetOrEncoding <integer> | <string> إزاحة بايت أو ترميز.
• length <integer> طول.
• قيمة الإرجاع: <Buffer>

بالنسبة للكائنات التي تُرجع دالة valueOf() الخاصة بها قيمة لا تساوي تمامًا object، تُرجع Buffer.from(object.valueOf(), offsetOrEncoding, length).

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from(new String('this is a test'))
// يُطبع: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from(new String('this is a test'))
// يُطبع: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

بالنسبة للكائنات التي تدعم Symbol.toPrimitive، تُرجع Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding).

ESM

import { Buffer } from 'node:buffer'

class Foo {
  [Symbol.toPrimitive]() {
    return 'this is a test'
  }
}

const buf = Buffer.from(new Foo(), 'utf8')
// يُطبع: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

CJS

const { Buffer } = require('node:buffer')

class Foo {
  [Symbol.toPrimitive]() {
    return 'this is a test'
  }
}

const buf = Buffer.from(new Foo(), 'utf8')
// يُطبع: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>

سيتم إرسال TypeError إذا لم يكن للكائن object الطرق المذكورة أو لم يكن من نوع آخر مناسب لمتغيرات Buffer.from().

طريقة ثابتة: Buffer.from(string[, encoding])

مضاف في: v5.10.0

• string <string> سلسلة نصية للترميز.
• encoding <string> ترميز string. الافتراضي: 'utf8'.
• الإرجاع: <Buffer>

يُنشئ Buffer جديدًا يحتوي على string. يُحدد مُعامل encoding ترميز الأحرف الذي سيتم استخدامه عند تحويل string إلى بايتات.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('this is a tést')
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex')

console.log(buf1.toString())
// يطبع: this is a tést
console.log(buf2.toString())
// يطبع: this is a tést
console.log(buf1.toString('latin1'))
// يطبع: this is a tést

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('this is a tést')
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex')

console.log(buf1.toString())
// يطبع: this is a tést
console.log(buf2.toString())
// يطبع: this is a tést
console.log(buf1.toString('latin1'))
// يطبع: this is a tést

سيتم طرح TypeError إذا لم يكن string سلسلة نصية أو نوعًا آخر مناسبًا لمتغيرات Buffer.from().

قد يستخدم Buffer.from(string) أيضًا تجمع Buffer الداخلي مثلما يفعل Buffer.allocUnsafe().

طريقة ثابتة: Buffer.isBuffer(obj)

مضاف في: v0.1.101

• obj <Object>
• الإرجاع: <boolean>

يُعيد true إذا كان obj عبارة عن Buffer، وfalse خلاف ذلك.

ESM

import { Buffer } from 'node:buffer'

Buffer.isBuffer(Buffer.alloc(10)) // true
Buffer.isBuffer(Buffer.from('foo')) // true
Buffer.isBuffer('a string') // false
Buffer.isBuffer([]) // false
Buffer.isBuffer(new Uint8Array(1024)) // false

CJS

const { Buffer } = require('node:buffer')

Buffer.isBuffer(Buffer.alloc(10)) // true
Buffer.isBuffer(Buffer.from('foo')) // true
Buffer.isBuffer('a string') // false
Buffer.isBuffer([]) // false
Buffer.isBuffer(new Uint8Array(1024)) // false

طريقة ثابتة: Buffer.isEncoding(encoding)

مضاف في: v0.9.1

• encoding <string> اسم ترميز أحرف للتحقق منه.
• قيمة الإرجاع: <boolean>

يرجع true إذا كان encoding اسم ترميز أحرف مدعوم، أو false خلاف ذلك.

ESM

import { Buffer } from 'node:buffer'

console.log(Buffer.isEncoding('utf8'))
// يطبع: true

console.log(Buffer.isEncoding('hex'))
// يطبع: true

console.log(Buffer.isEncoding('utf/8'))
// يطبع: false

console.log(Buffer.isEncoding(''))
// يطبع: false

CJS

const { Buffer } = require('node:buffer')

console.log(Buffer.isEncoding('utf8'))
// يطبع: true

console.log(Buffer.isEncoding('hex'))
// يطبع: true

console.log(Buffer.isEncoding('utf/8'))
// يطبع: false

console.log(Buffer.isEncoding(''))
// يطبع: false

خاصية الفئة: Buffer.poolSize

مضاف في: v0.11.3

• <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.

ESM

import { Buffer } from 'node:buffer'

// نسخ سلسلة ASCII إلى `Buffer` بايت واحد في كل مرة.
// (هذا يعمل فقط لسلاسل ASCII فقط. بشكل عام، يجب استخدام
// `Buffer.from()` لإجراء هذا التحويل.)

const str = 'Node.js'
const buf = Buffer.allocUnsafe(str.length)

for (let i = 0; i < str.length; i++) {
  buf[i] = str.charCodeAt(i)
}

console.log(buf.toString('utf8'))
// يطبع: Node.js

CJS

const { Buffer } = require('node:buffer')

// نسخ سلسلة ASCII إلى `Buffer` بايت واحد في كل مرة.
// (هذا يعمل فقط لسلاسل ASCII فقط. بشكل عام، يجب استخدام
// `Buffer.from()` لإجراء هذا التحويل.)

const str = 'Node.js'
const buf = Buffer.allocUnsafe(str.length)

for (let i = 0; i < str.length; i++) {
  buf[i] = str.charCodeAt(i)
}

console.log(buf.toString('utf8'))
// يطبع: Node.js

buf.buffer

• <ArrayBuffer> كائن ArrayBuffer الأساسي الذي تم إنشاء كائن Buffer هذا بناءً عليه.

لا يُضمن أن يتطابق هذا ArrayBuffer تمامًا مع Buffer الأصلي. راجع الملاحظات حول buf.byteOffset للحصول على التفاصيل.

ESM

import { Buffer } from 'node:buffer'

const arrayBuffer = new ArrayBuffer(16)
const buffer = Buffer.from(arrayBuffer)

console.log(buffer.buffer === arrayBuffer)
// Prints: true

CJS

const { Buffer } = require('node:buffer')

const arrayBuffer = new ArrayBuffer(16)
const buffer = Buffer.from(arrayBuffer)

console.log(buffer.buffer === arrayBuffer)
// Prints: true

buf.byteOffset

• <integer> byteOffset لكائن ArrayBuffer الأساسي لـ Buffer.

عند تعيين byteOffset في Buffer.from(ArrayBuffer, byteOffset, length)، أو في بعض الأحيان عند تخصيص Buffer أصغر من Buffer.poolSize، لا يبدأ المخزن المؤقت من إزاحة صفرية على ArrayBuffer الأساسي.

قد يتسبب هذا في حدوث مشكلات عند الوصول إلى ArrayBuffer الأساسي مباشرةً باستخدام buf.buffer، حيث قد تكون أجزاء أخرى من ArrayBuffer غير مرتبطة بكائن Buffer نفسه.

تُعد مشكلة شائعة عند إنشاء كائن TypedArray يشارك ذاكرته مع Buffer هي أنه في هذه الحالة، يحتاج المرء إلى تحديد byteOffset بشكل صحيح:

ESM

import { Buffer } from 'node:buffer'

// إنشاء مخزن مؤقت أصغر من `Buffer.poolSize`.
const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

// عند تحويل Node.js Buffer إلى Int8Array، استخدم byteOffset
// للإشارة فقط إلى جزء من `nodeBuffer.buffer` الذي يحتوي على الذاكرة
// لـ `nodeBuffer`.
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length)

CJS

const { Buffer } = require('node:buffer')

// إنشاء مخزن مؤقت أصغر من `Buffer.poolSize`.
const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

// عند تحويل Node.js Buffer إلى Int8Array، استخدم byteOffset
// للإشارة فقط إلى جزء من `nodeBuffer.buffer` الذي يحتوي على الذاكرة
// لـ `nodeBuffer`.
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length)

buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])

[History]

الإصدار	التغييرات
v8.0.0	يمكن أن يكون المُعامل target الآن مصفوفة Uint8Array.
v5.11.0	يتم دعم معلمات إضافية لتحديد الإزاحات الآن.
v0.11.13	تمت الإضافة في: v0.11.13

• target <Buffer> | <Uint8Array> مُخزن مؤقت Buffer أو مصفوفة Uint8Array للمقارنة مع buf.
• targetStart <integer> الإزاحة داخل target التي تبدأ عندها المقارنة. الافتراضي: 0.
• targetEnd <integer> الإزاحة داخل target التي تنتهي عندها المقارنة (غير شاملة). الافتراضي: target.length.
• sourceStart <integer> الإزاحة داخل buf التي تبدأ عندها المقارنة. الافتراضي: 0.
• sourceEnd <integer> الإزاحة داخل buf التي تنتهي عندها المقارنة (غير شاملة). الافتراضي: buf.length.
• القيمة المُرجعة: <integer>

تقارن buf مع target وتُرجع رقمًا يُشير إلى ما إذا كان buf يأتي قبل أو بعد أو يساوي target في ترتيب الفرز. تستند المقارنة إلى التسلسل الفعلي للبايتات في كل مُخزن مؤقت Buffer.

• يتم إرجاع 0 إذا كان target مساويًا لـ buf
• يتم إرجاع 1 إذا كان يجب أن يأتي target قبل buf عند الفرز.
• يتم إرجاع -1 إذا كان يجب أن يأتي target بعد buf عند الفرز.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('ABC')
const buf2 = Buffer.from('BCD')
const buf3 = Buffer.from('ABCD')

console.log(buf1.compare(buf1))
// يُطبع: 0
console.log(buf1.compare(buf2))
// يُطبع: -1
console.log(buf1.compare(buf3))
// يُطبع: -1
console.log(buf2.compare(buf1))
// يُطبع: 1
console.log(buf2.compare(buf3))
// يُطبع: 1
console.log([buf1, buf2, buf3].sort(Buffer.compare))
// يُطبع: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// (هذه النتيجة تساوي: [buf1, buf3, buf2].)

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('ABC')
const buf2 = Buffer.from('BCD')
const buf3 = Buffer.from('ABCD')

console.log(buf1.compare(buf1))
// يُطبع: 0
console.log(buf1.compare(buf2))
// يُطبع: -1
console.log(buf1.compare(buf3))
// يُطبع: -1
console.log(buf2.compare(buf1))
// يُطبع: 1
console.log(buf2.compare(buf3))
// يُطبع: 1
console.log([buf1, buf2, buf3].sort(Buffer.compare))
// يُطبع: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// (هذه النتيجة تساوي: [buf1, buf3, buf2].)

يمكن استخدام الوسيطات الاختيارية targetStart, targetEnd, sourceStart, و sourceEnd للحد من المقارنة إلى نطاقات محددة داخل target و buf على التوالي.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9])
const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4])

console.log(buf1.compare(buf2, 5, 9, 0, 4))
// يُطبع: 0
console.log(buf1.compare(buf2, 0, 6, 4))
// يُطبع: -1
console.log(buf1.compare(buf2, 5, 6, 5))
// يُطبع: 1

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9])
const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4])

console.log(buf1.compare(buf2, 5, 9, 0, 4))
// يُطبع: 0
console.log(buf1.compare(buf2, 0, 6, 4))
// يُطبع: -1
console.log(buf1.compare(buf2, 5, 6, 5))
// يُطبع: 1

يتم طرح الخطأ ERR_OUT_OF_RANGE إذا كان targetStart < 0, sourceStart < 0, targetEnd > target.byteLength, أو sourceEnd > source.byteLength.

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

مضاف في: v0.1.90

• target <Buffer> | <Uint8Array> Buffer أو Uint8Array للنسخ إليه.
• targetStart <integer> الإزاحة داخل target التي يبدأ عندها الكتابة. افتراضي: 0.
• sourceStart <integer> الإزاحة داخل buf التي يبدأ عندها النسخ. افتراضي: 0.
• sourceEnd <integer> الإزاحة داخل buf التي يتوقف عندها النسخ (غير شامل). افتراضي: buf.length.
• المُرجّع: <integer> عدد البايتات المُنسوخة.

ينسخ البيانات من منطقة في buf إلى منطقة في target، حتى لو كانت منطقة الذاكرة target تتداخل مع buf.

TypedArray.prototype.set() يؤدي نفس العملية، وهو متوفر لجميع TypedArray، بما في ذلك Buffer في Node.js، على الرغم من أنه يأخذ وسيطات دالة مختلفة.

ESM

import { Buffer } from 'node:buffer'

// إنشاء مثيلين من `Buffer`.
const buf1 = Buffer.allocUnsafe(26)
const buf2 = Buffer.allocUnsafe(26).fill('!')

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf1[i] = i + 97
}

// نسخ بايتات `buf1` من 16 إلى 19 إلى `buf2` بدءًا من البايت 8 من `buf2`.
buf1.copy(buf2, 8, 16, 20)
// هذا ما يعادل:
// buf2.set(buf1.subarray(16, 20), 8);

console.log(buf2.toString('ascii', 0, 25))
// يُطبع: !!!!!!!!qrst!!!!!!!!!!!!!

CJS

const { Buffer } = require('node:buffer')

// إنشاء مثيلين من `Buffer`.
const buf1 = Buffer.allocUnsafe(26)
const buf2 = Buffer.allocUnsafe(26).fill('!')

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf1[i] = i + 97
}

// نسخ بايتات `buf1` من 16 إلى 19 إلى `buf2` بدءًا من البايت 8 من `buf2`.
buf1.copy(buf2, 8, 16, 20)
// هذا ما يعادل:
// buf2.set(buf1.subarray(16, 20), 8);

console.log(buf2.toString('ascii', 0, 25))
// يُطبع: !!!!!!!!qrst!!!!!!!!!!!!!

ESM

import { Buffer } from 'node:buffer'

// إنشاء `Buffer` ونسخ البيانات من منطقة إلى منطقة متداخلة
// داخل نفس `Buffer`.

const buf = Buffer.allocUnsafe(26)

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf[i] = i + 97
}

buf.copy(buf, 0, 4, 10)

console.log(buf.toString())
// يُطبع: efghijghijklmnopqrstuvwxyz

CJS

const { Buffer } = require('node:buffer')

// إنشاء `Buffer` ونسخ البيانات من منطقة إلى منطقة متداخلة
// داخل نفس `Buffer`.

const buf = Buffer.allocUnsafe(26)

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf[i] = i + 97
}

buf.copy(buf, 0, 4, 10)

console.log(buf.toString())
// يُطبع: efghijghijklmnopqrstuvwxyz

buf.entries()

أضيف في: v1.1.0

• مُخرجات: <Iterator>

يقوم بإنشاء وإرجاع مُكرر iterator من أزواج [index, byte] من محتويات buf.

ESM

import { Buffer } from 'node:buffer'

// تسجيل محتويات `Buffer` بالكامل.

const buf = Buffer.from('buffer')

for (const pair of buf.entries()) {
  console.log(pair)
}
// يُطبع:
//   [0, 98]
//   [1, 117]
//   [2, 102]
//   [3, 102]
//   [4, 101]
//   [5, 114]

CJS

const { Buffer } = require('node:buffer')

// تسجيل محتويات `Buffer` بالكامل.

const buf = Buffer.from('buffer')

for (const pair of buf.entries()) {
  console.log(pair)
}
// يُطبع:
//   [0, 98]
//   [1, 117]
//   [2, 102]
//   [3, 102]
//   [4, 101]
//   [5, 114]

buf.equals(otherBuffer)

[History]

الإصدار	التغييرات
v8.0.0	الوسائط الآن يمكن أن تكون Uint8Arrays.
v0.11.13	أضيف في: v0.11.13

• otherBuffer <Buffer> | <Uint8Array> Buffer أو Uint8Array للمقارنة مع buf.
• مُخرجات: <boolean>

يُرجع true إذا كان كلاً من buf و otherBuffer يحتويان على نفس البايتات بالضبط، false بخلاف ذلك. ما يعادل buf.compare(otherBuffer) === 0.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('ABC')
const buf2 = Buffer.from('414243', 'hex')
const buf3 = Buffer.from('ABCD')

console.log(buf1.equals(buf2))
// يُطبع: true
console.log(buf1.equals(buf3))
// يُطبع: false

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('ABC')
const buf2 = Buffer.from('414243', 'hex')
const buf3 = Buffer.from('ABCD')

console.log(buf1.equals(buf2))
// يُطبع: true
console.log(buf1.equals(buf3))
// يُطبع: false

buf.fill(value[, offset[, end]][, encoding])

[History]

الإصدار	التغييرات
v11.0.0	يطرح ERR_OUT_OF_RANGE بدلاً من ERR_INDEX_OUT_OF_RANGE.
v10.0.0	قيم end السالبة تطرح خطأ ERR_INDEX_OUT_OF_RANGE.
v10.0.0	محاولة ملء مُخزن مؤقت غير صفري الطول بمُخزن مؤقت صفري الطول تُسبب استثناءً.
v10.0.0	تحديد سلسلة غير صالحة لـ value يُسبب استثناءً.
v5.7.0	تم دعم معلمة encoding الآن.
v0.5.0	تمت الإضافة في: v0.5.0

• value <string> | <Buffer> | <Uint8Array> | <integer> القيمة التي سيتم بها ملء buf. القيمة الفارغة (سلسلة، Uint8Array، Buffer) يتم تحويلها إلى 0.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في ملء buf. الافتراضي: 0.
• end <integer> مكان التوقف عن ملء buf (غير شامل). الافتراضي: buf.length.
• encoding <string> ترميز value إذا كان value سلسلة. الافتراضي: 'utf8'.
• القيمة المُرجعة: <Buffer> مرجع إلى buf.

يملأ buf بالقيمة المحددة value. إذا لم يتم إعطاء offset و end، فسيتم ملء buf بالكامل:

ESM

import { Buffer } from 'node:buffer'

// ملء `Buffer` بحرف ASCII 'h'.

const b = Buffer.allocUnsafe(50).fill('h')

console.log(b.toString())
// يطبع: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

// ملء مخزن مؤقت بسلسلة فارغة
const c = Buffer.allocUnsafe(5).fill('')

console.log(c.fill(''))
// يطبع: <Buffer 00 00 00 00 00>

CJS

const { Buffer } = require('node:buffer')

// ملء `Buffer` بحرف ASCII 'h'.

const b = Buffer.allocUnsafe(50).fill('h')

console.log(b.toString())
// يطبع: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

// ملء مخزن مؤقت بسلسلة فارغة
const c = Buffer.allocUnsafe(5).fill('')

console.log(c.fill(''))
// يطبع: <Buffer 00 00 00 00 00>

يتم تحويل value إلى قيمة uint32 إذا لم تكن سلسلة أو Buffer أو عدد صحيح. إذا كان العدد الصحيح الناتج أكبر من 255 (عشري)، فسيتم ملء buf بـ value & 255.

إذا وقعت الكتابة النهائية لعملية fill() على حرف متعدد البايتات، فسيتم كتابة بايتات ذلك الحرف التي تتناسب مع buf فقط:

ESM

import { Buffer } from 'node:buffer'

// ملء `Buffer` بحرف يحتل بايتين في UTF-8.

console.log(Buffer.allocUnsafe(5).fill('\u0222'))
// يطبع: <Buffer c8 a2 c8 a2 c8>

CJS

const { Buffer } = require('node:buffer')

// ملء `Buffer` بحرف يحتل بايتين في UTF-8.

console.log(Buffer.allocUnsafe(5).fill('\u0222'))
// يطبع: <Buffer c8 a2 c8 a2 c8>

إذا كانت value تحتوي على أحرف غير صالحة، فسيتم اقتطاعها؛ وإذا لم تَبْقَ بيانات ملء صالحة، فسيتم طرح استثناء:

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(5)

console.log(buf.fill('a'))
// يطبع: <Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'))
// يطبع: <Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'))
// يطرح استثناءً.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(5)

console.log(buf.fill('a'))
// يطبع: <Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'))
// يطبع: <Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'))
// يطرح استثناءً.

buf.includes(value[, byteOffset][, encoding])

أضيف في: v5.3.0

• value <string> | <Buffer> | <Uint8Array> | <integer> ما الذي يجب البحث عنه.
• byteOffset <integer> أين تبدأ عملية البحث في buf. إذا كانت سالبة، فسيتم حساب الإزاحة من نهاية buf. الافتراضي: 0.
• encoding <string> إذا كانت value سلسلة، فهذه هي ترميزها. الافتراضي: 'utf8'.
• الإرجاع: <boolean> true إذا تم العثور على value في buf، false بخلاف ذلك.

ما يعادل buf.indexOf() !== -1.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('this is a buffer')

console.log(buf.includes('this'))
// يطبع: true
console.log(buf.includes('is'))
// يطبع: true
console.log(buf.includes(Buffer.from('a buffer')))
// يطبع: true
console.log(buf.includes(97))
// يطبع: true (97 هي القيمة العشرية ASCII لـ 'a')
console.log(buf.includes(Buffer.from('a buffer example')))
// يطبع: false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)))
// يطبع: true
console.log(buf.includes('this', 4))
// يطبع: false

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('this is a buffer')

console.log(buf.includes('this'))
// يطبع: true
console.log(buf.includes('is'))
// يطبع: true
console.log(buf.includes(Buffer.from('a buffer')))
// يطبع: true
console.log(buf.includes(97))
// يطبع: true (97 هي القيمة العشرية ASCII لـ 'a')
console.log(buf.includes(Buffer.from('a buffer example')))
// يطبع: false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)))
// يطبع: true
console.log(buf.includes('this', 4))
// يطبع: false

buf.indexOf(value[, byteOffset][, encoding])

[History]

الإصدار	التغييرات
v8.0.0	يمكن الآن أن تكون قيمة value عبارة عن Uint8Array.
v5.7.0, v4.4.0	عند تمرير encoding، لم يعد مُعامل byteOffset مطلوبًا.
v1.5.0	تمت الإضافة في: v1.5.0

• value <string> | <Buffer> | <Uint8Array> | <integer> ما الذي يجب البحث عنه.
• byteOffset <integer> أين تبدأ البحث في buf. إذا كانت سالبة، فسيتم حساب الإزاحة من نهاية buf. الافتراضي: 0.
• encoding <string> إذا كانت value سلسلة، فهذا هو الترميز المستخدم لتحديد التمثيل الثنائي للسلسلة التي سيتم البحث عنها في buf. الافتراضي: 'utf8'.
• القيمة المُرجعه: <integer> مؤشر أول ظهور لـ value في buf، أو -1 إذا لم تحتوي buf على value.

إذا كانت value:

• سلسلة، فسيتم تفسير value وفقًا لترميز الأحرف في encoding.
• Buffer أو Uint8Array، سيتم استخدام value بالكامل. لمقارنة جزء من Buffer، استخدم buf.subarray.
• رقم، سيتم تفسير value على أنه قيمة عدد صحيح بدون إشارة 8 بت بين 0 و 255.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('this is a buffer')

console.log(buf.indexOf('this'))
// يطبع: 0
console.log(buf.indexOf('is'))
// يطبع: 2
console.log(buf.indexOf(Buffer.from('a buffer')))
// يطبع: 8
console.log(buf.indexOf(97))
// يطبع: 8 (97 هي القيمة العشرية ASCII لـ 'a')
console.log(buf.indexOf(Buffer.from('a buffer example')))
// يطبع: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)))
// يطبع: 8

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')

console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'))
// يطبع: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'))
// يطبع: 6

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('this is a buffer')

console.log(buf.indexOf('this'))
// يطبع: 0
console.log(buf.indexOf('is'))
// يطبع: 2
console.log(buf.indexOf(Buffer.from('a buffer')))
// يطبع: 8
console.log(buf.indexOf(97))
// يطبع: 8 (97 هي القيمة العشرية ASCII لـ 'a')
console.log(buf.indexOf(Buffer.from('a buffer example')))
// يطبع: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)))
// يطبع: 8

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')

console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'))
// يطبع: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'))
// يطبع: 6

إذا لم تكن value سلسلة أو رقمًا أو Buffer، فستطرح هذه الطريقة خطأ TypeError. إذا كانت value رقمًا، فسيتم إجبارها على قيمة بايت صالحة، وهي عدد صحيح بين 0 و 255.

إذا لم يكن byteOffset رقمًا، فسيتم إجباره على رقم. إذا كانت نتيجة الإجبار NaN أو 0، فسيتم البحث في المخزن المؤقت بالكامل. يتطابق هذا السلوك مع String.prototype.indexOf().

ESM

import { Buffer } from 'node:buffer'

const b = Buffer.from('abcdef')

// تمرير قيمة هي رقم، ولكن ليست بايت صالحة.
// يطبع: 2، ما يعادل البحث عن 99 أو 'c'.
console.log(b.indexOf(99.9))
console.log(b.indexOf(256 + 99))

// تمرير byteOffset الذي يُجبر على NaN أو 0.
// يطبع: 1، البحث في المخزن المؤقت بالكامل.
console.log(b.indexOf('b', undefined))
console.log(b.indexOf('b', {}))
console.log(b.indexOf('b', null))
console.log(b.indexOf('b', []))

CJS

const { Buffer } = require('node:buffer')

const b = Buffer.from('abcdef')

// تمرير قيمة هي رقم، ولكن ليست بايت صالحة.
// يطبع: 2، ما يعادل البحث عن 99 أو 'c'.
console.log(b.indexOf(99.9))
console.log(b.indexOf(256 + 99))

// تمرير byteOffset الذي يُجبر على NaN أو 0.
// يطبع: 1، البحث في المخزن المؤقت بالكامل.
console.log(b.indexOf('b', undefined))
console.log(b.indexOf('b', {}))
console.log(b.indexOf('b', null))
console.log(b.indexOf('b', []))

إذا كانت value سلسلة فارغة أو Buffer فارغة و byteOffset أقل من buf.length، فسيتم إرجاع byteOffset. إذا كانت value فارغة و byteOffset يساوي أو أكبر من buf.length، فسيتم إرجاع buf.length.

buf.keys()

أضيف في: v1.1.0

• مُخرجات: <Iterator>

يقوم بإنشاء وإرجاع مُكرر iterator لمفاتيح (مؤشرات) buf.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('buffer')

for (const key of buf.keys()) {
  console.log(key)
}
// يطبع:
//   0
//   1
//   2
//   3
//   4
//   5

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('buffer')

for (const key of buf.keys()) {
  console.log(key)
}
// يطبع:
//   0
//   1
//   2
//   3
//   4
//   5

buf.lastIndexOf(value[, byteOffset][, encoding])

[History]

الإصدار	التغييرات
v8.0.0	أصبح بإمكان value الآن أن يكون Uint8Array.
v6.0.0	أضيف في: v6.0.0

• value <string> | <Buffer> | <Uint8Array> | <integer> ما يجب البحث عنه.
• byteOffset <integer> أين يبدأ البحث في buf. إذا كان سالبًا، يتم حساب الإزاحة من نهاية buf. الافتراضي: buf.length - 1.
• encoding <string> إذا كان value سلسلة، فهذا هو الترميز المستخدم لتحديد التمثيل الثنائي للسلسلة التي سيتم البحث عنها في buf. الافتراضي: 'utf8'.
• مُخرجات: <integer> مؤشر آخر حدوث لـ value في buf، أو -1 إذا لم يحتوِ buf على value.

مطابق لـ buf.indexOf()، باستثناء أن آخر حدوث لـ value يتم العثور عليه بدلاً من الحدوث الأول.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('this buffer is a buffer')

console.log(buf.lastIndexOf('this'))
// يطبع: 0
console.log(buf.lastIndexOf('buffer'))
// يطبع: 17
console.log(buf.lastIndexOf(Buffer.from('buffer')))
// يطبع: 17
console.log(buf.lastIndexOf(97))
// يطبع: 15 (97 هي القيمة العشرية ASCII لـ 'a')
console.log(buf.lastIndexOf(Buffer.from('yolo')))
// يطبع: -1
console.log(buf.lastIndexOf('buffer', 5))
// يطبع: 5
console.log(buf.lastIndexOf('buffer', 4))
// يطبع: -1

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')

console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'))
// يطبع: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'))
// يطبع: 4

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('this buffer is a buffer')

console.log(buf.lastIndexOf('this'))
// يطبع: 0
console.log(buf.lastIndexOf('buffer'))
// يطبع: 17
console.log(buf.lastIndexOf(Buffer.from('buffer')))
// يطبع: 17
console.log(buf.lastIndexOf(97))
// يطبع: 15 (97 هي القيمة العشرية ASCII لـ 'a')
console.log(buf.lastIndexOf(Buffer.from('yolo')))
// يطبع: -1
console.log(buf.lastIndexOf('buffer', 5))
// يطبع: 5
console.log(buf.lastIndexOf('buffer', 4))
// يطبع: -1

const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')

console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'))
// يطبع: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'))
// يطبع: 4

إذا لم يكن value سلسلة أو رقمًا أو Buffer، فسوف تُلقي هذه الطريقة خطأ TypeError. إذا كان value رقمًا، فسيتم إجباره على قيمة بايت صالحة، عدد صحيح بين 0 و 255.

إذا لم يكن byteOffset رقمًا، فسيتم إجباره على رقم. أي وسيطات تُجبر على NaN، مثل {} أو undefined، ستبحث في المخزن المؤقت بأكمله. يتطابق هذا السلوك مع String.prototype.lastIndexOf().

ESM

import { Buffer } from 'node:buffer'

const b = Buffer.from('abcdef')

// تمرير قيمة هي رقم، ولكن ليست بايت صالح.
// يطبع: 2، ما يعادل البحث عن 99 أو 'c'.
console.log(b.lastIndexOf(99.9))
console.log(b.lastIndexOf(256 + 99))

// تمرير byteOffset يُجبر على NaN.
// يطبع: 1، البحث في المخزن المؤقت بأكمله.
console.log(b.lastIndexOf('b', undefined))
console.log(b.lastIndexOf('b', {}))

// تمرير byteOffset يُجبر على 0.
// يطبع: -1، ما يعادل تمرير 0.
console.log(b.lastIndexOf('b', null))
console.log(b.lastIndexOf('b', []))

CJS

const { Buffer } = require('node:buffer')

const b = Buffer.from('abcdef')

// تمرير قيمة هي رقم، ولكن ليست بايت صالح.
// يطبع: 2، ما يعادل البحث عن 99 أو 'c'.
console.log(b.lastIndexOf(99.9))
console.log(b.lastIndexOf(256 + 99))

// تمرير byteOffset يُجبر على NaN.
// يطبع: 1، البحث في المخزن المؤقت بأكمله.
console.log(b.lastIndexOf('b', undefined))
console.log(b.lastIndexOf('b', {}))

// تمرير byteOffset يُجبر على 0.
// يطبع: -1، ما يعادل تمرير 0.
console.log(b.lastIndexOf('b', null))
console.log(b.lastIndexOf('b', []))

إذا كان value سلسلة فارغة أو Buffer فارغًا، فسيتم إرجاع byteOffset.

buf.length

مُضاف في: v0.1.90

• <integer>

يُعيد عدد البايتات في buf.

ESM

import { Buffer } from 'node:buffer'

// إنشاء `Buffer` وكتابة سلسلة أقصر فيه باستخدام UTF-8.

const buf = Buffer.alloc(1234)

console.log(buf.length)
// يُطبع: 1234

buf.write('some string', 0, 'utf8')

console.log(buf.length)
// يُطبع: 1234

CJS

const { Buffer } = require('node:buffer')

// إنشاء `Buffer` وكتابة سلسلة أقصر فيه باستخدام UTF-8.

const buf = Buffer.alloc(1234)

console.log(buf.length)
// يُطبع: 1234

buf.write('some string', 0, 'utf8')

console.log(buf.length)
// يُطبع: 1234

buf.parent

مسحوب منذ: v8.0.0

[مستقر: 0 - مسحوب]

مستقر: 0 الثبات: 0 - مسحوب: استخدم buf.buffer بدلاً من ذلك.

خاصية buf.parent هي اسم مستعار مُسحوب لـ buf.buffer.

buf.readBigInt64BE([offset])

مُضاف في: v12.0.0، v10.20.0

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق: 0 \<= offset \<= buf.length - 8. افتراضيًا: 0.
• يُعيد: <bigint>

يقوم بقراءة عدد صحيح مُوقّع، كبير النهاية، 64 بت من buf في الإزاحة المحددة.

يتم تفسير الأعداد الصحيحة المُقروءة من Buffer كقيم مُوقّعة مكملة للزوجين.

buf.readBigInt64LE([offset])

مُضاف في: v12.0.0، v10.20.0

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق: 0 \<= offset \<= buf.length - 8. افتراضيًا: 0.
• يُعيد: <bigint>

يقوم بقراءة عدد صحيح مُوقّع، صغير النهاية، 64 بت من buf في الإزاحة المحددة.

يتم تفسير الأعداد الصحيحة المُقروءة من Buffer كقيم مُوقّعة مكملة للزوجين.

buf.readBigUInt64BE([offset])

[History]

الإصدار	التغييرات
v14.10.0، v12.19.0	تتوفر هذه الدالة أيضًا كـ buf.readBigUint64BE().
v12.0.0، v10.20.0	تمت الإضافة في: v12.0.0، v10.20.0

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يلبي الشرط: 0 \<= offset \<= buf.length - 8. الافتراضي: 0.
• القيمة المُرجعة: <bigint>

يقوم بقراءة عدد صحيح بدون إشارة، كبير النهاية، 64 بت من buf عند الإزاحة المحددة offset.

تتوفر هذه الدالة أيضًا تحت مُسمى readBigUint64BE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])

console.log(buf.readBigUInt64BE(0))
// Prints: 4294967295n

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])

console.log(buf.readBigUInt64BE(0))
// Prints: 4294967295n

buf.readBigUInt64LE([offset])

[History]

الإصدار	التغييرات
v14.10.0، v12.19.0	تتوفر هذه الدالة أيضًا كـ buf.readBigUint64LE().
v12.0.0، v10.20.0	تمت الإضافة في: v12.0.0، v10.20.0

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يلبي الشرط: 0 \<= offset \<= buf.length - 8. الافتراضي: 0.
• القيمة المُرجعة: <bigint>

يقوم بقراءة عدد صحيح بدون إشارة، صغير النهاية، 64 بت من buf عند الإزاحة المحددة offset.

تتوفر هذه الدالة أيضًا تحت مُسمى readBigUint64LE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])

console.log(buf.readBigUInt64LE(0))
// Prints: 18446744069414584320n

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])

console.log(buf.readBigUInt64LE(0))
// Prints: 18446744069414584320n

buf.readDoubleBE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك إكراه ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق الشرط 0 \<= offset \<= buf.length - 8. الافتراضي: 0.
• القيمة المُرجعة: <number>

يقوم بقراءة قيمة مزدوجة 64 بت، كبيرة النهاية، من buf في الإزاحة المحددة offset.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])

console.log(buf.readDoubleBE(0))
// يطبع: 8.20788039913184e-304

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])

console.log(buf.readDoubleBE(0))
// يطبع: 8.20788039913184e-304

buf.readDoubleLE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك إكراه ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق الشرط 0 \<= offset \<= buf.length - 8. الافتراضي: 0.
• القيمة المُرجعة: <number>

يقوم بقراءة قيمة مزدوجة 64 بت، صغيرة النهاية، من buf في الإزاحة المحددة offset.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])

console.log(buf.readDoubleLE(0))
// يطبع: 5.447603722011605e-270
console.log(buf.readDoubleLE(1))
// يطرح ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])

console.log(buf.readDoubleLE(0))
// يطبع: 5.447603722011605e-270
console.log(buf.readDoubleLE(1))
// يطرح ERR_OUT_OF_RANGE.

buf.readFloatBE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• القيمة المُرجعة: <number>

يقوم بقراءة قيمة عددية بتعويم 32 بت، ذات ترتيب البايتات الكبير، من buf عند الإزاحة المحددة offset.

ESM

import { Buffer } from 'node:buffer'

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

console.log(buf.readFloatBE(0))
// يطبع: 2.387939260590663e-38

CJS

const { Buffer } = require('node:buffer')

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

console.log(buf.readFloatBE(0))
// يطبع: 2.387939260590663e-38

buf.readFloatLE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• القيمة المُرجعة: <number>

يقوم بقراءة قيمة عددية بتعويم 32 بت، ذات ترتيب البايتات الصغير، من buf عند الإزاحة المحددة offset.

ESM

import { Buffer } from 'node:buffer'

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

console.log(buf.readFloatLE(0))
// يطبع: 1.539989614439558e-36
console.log(buf.readFloatLE(1))
// يرمي ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

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

console.log(buf.readFloatLE(0))
// يطبع: 1.539989614439558e-36
console.log(buf.readFloatLE(1))
// يرمي ERR_OUT_OF_RANGE.

buf.readInt8([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للـ offset إلى uint32.
v0.5.0	تمت الإضافة في: v0.5.0

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق الشرط 0 \<= offset \<= buf.length - 1. الافتراضي: 0.
• القيمة المُرجعة: <integer>

يقوم بقراءة عدد صحيح مُوقع من 8 بت من buf في offset المحدد.

يتم تفسير الأعداد الصحيحة التي تمت قراءتها من Buffer على أنها قيم مُوقعة بتكامل ثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([-1, 5])

console.log(buf.readInt8(0))
// يُطبع: -1
console.log(buf.readInt8(1))
// يُطبع: 5
console.log(buf.readInt8(2))
// يُطرح الخطأ ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([-1, 5])

console.log(buf.readInt8(0))
// يُطبع: -1
console.log(buf.readInt8(1))
// يُطبع: 5
console.log(buf.readInt8(2))
// يُطرح الخطأ ERR_OUT_OF_RANGE.

buf.readInt16BE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للـ offset إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق الشرط 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• القيمة المُرجعة: <integer>

يقوم بقراءة عدد صحيح مُوقع، ذي ترتيب بايت كبير (Big-Endian)، من 16 بت من buf في offset المحدد.

يتم تفسير الأعداد الصحيحة التي تمت قراءتها من Buffer على أنها قيم مُوقعة بتكامل ثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0, 5])

console.log(buf.readInt16BE(0))
// يُطبع: 5

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0, 5])

console.log(buf.readInt16BE(0))
// يُطبع: 5

buf.readInt16LE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يفي ب الشرط 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• القيمة المُرجعه: <integer>

يقوم بقراءة عدد صحيح مُوقع، مُصغر النهاية، 16 بت من buf عند الإزاحة المُحددة offset.

يتم تفسير الأعداد الصحيحة المُقروءة من Buffer كقيم مُوقعة مكملة للثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0, 5])

console.log(buf.readInt16LE(0))
// يُطبع: 1280
console.log(buf.readInt16LE(1))
// يُلقي خطأ ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0, 5])

console.log(buf.readInt16LE(0))
// يُطبع: 1280
console.log(buf.readInt16LE(1))
// يُلقي خطأ ERR_OUT_OF_RANGE.

buf.readInt32BE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يفي ب الشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• القيمة المُرجعه: <integer>

يقوم بقراءة عدد صحيح مُوقع، كبير النهاية، 32 بت من buf عند الإزاحة المُحددة offset.

يتم تفسير الأعداد الصحيحة المُقروءة من Buffer كقيم مُوقعة مكملة للثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0, 0, 0, 5])

console.log(buf.readInt32BE(0))
// يُطبع: 5

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0, 0, 0, 5])

console.log(buf.readInt32BE(0))
// يُطبع: 5

buf.readInt32LE([offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي يجب تخطيها قبل البدء في القراءة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• قيمة الإرجاع: <integer>

يقوم بقراءة عدد صحيح مكون من 32 بت، موقّع، ذو ترتيب بايت صغير (little-endian) من buf عند الإزاحة المحددة offset.

يتم تفسير الأعداد الصحيحة المقروءة من Buffer على أنها قيم موقعة مكملة للثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0, 0, 0, 5])

console.log(buf.readInt32LE(0))
// يطبع: 83886080
console.log(buf.readInt32LE(1))
// يرمي ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0, 0, 0, 5])

console.log(buf.readInt32LE(0))
// يطبع: 83886080
console.log(buf.readInt32LE(1))
// يرمي ERR_OUT_OF_RANGE.

buf.readIntBE(offset, byteLength)

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة و byteLength إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي يجب تخطيها قبل البدء في القراءة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم قراءتها. يجب أن يفي بشرط 0 \< byteLength \<= 6.
• قيمة الإرجاع: <integer>

يقوم بقراءة عدد byteLength من البايتات من buf عند الإزاحة المحددة offset ويفسر النتيجة كقيمة موقعة مكملة للثنائي ذات ترتيب بايت كبير (big-endian) تدعم حتى 48 بت من الدقة.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readIntBE(0, 6).toString(16))
// يطبع: 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16))
// يرمي ERR_OUT_OF_RANGE.
console.log(buf.readIntBE(1, 0).toString(16))
// يرمي ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readIntBE(0, 6).toString(16))
// يطبع: 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16))
// يرمي ERR_OUT_OF_RANGE.
console.log(buf.readIntBE(1, 0).toString(16))
// يرمي ERR_OUT_OF_RANGE.

buf.readIntLE(offset, byteLength)

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني لـ offset و byteLength إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يستوفي الشرط 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم قراءتها. يجب أن يستوفي الشرط 0 \< byteLength \<= 6.
• القيمة المُرجعة: <integer>

يقوم بقراءة byteLength من البايتات من buf في offset المحدد، ويفسر النتيجة كقيمة مُوقعة ثنائية التكامل little-endian تدعم ما يصل إلى 48 بت من الدقة.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readIntLE(0, 6).toString(16))
// Prints: -546f87a9cbee

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readIntLE(0, 6).toString(16))
// Prints: -546f87a9cbee

buf.readUInt8([offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الوظيفة أيضًا باسم buf.readUint8().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني لـ offset إلى uint32.
v0.5.0	تمت الإضافة في: v0.5.0

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يستوفي الشرط 0 \<= offset \<= buf.length - 1. افتراضيًا: 0.
• القيمة المُرجعة: <integer>

يقوم بقراءة عدد صحيح بدون إشارة 8 بت من buf في offset المحدد.

تتوفر هذه الوظيفة أيضًا تحت اسم readUint8.

ESM

import { Buffer } from 'node:buffer'

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

console.log(buf.readUInt8(0))
// Prints: 1
console.log(buf.readUInt8(1))
// Prints: 254
console.log(buf.readUInt8(2))
// Throws ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

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

console.log(buf.readUInt8(0))
// Prints: 1
console.log(buf.readUInt8(1))
// Prints: 254
console.log(buf.readUInt8(2))
// Throws ERR_OUT_OF_RANGE.

buf.readUInt16BE([offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.readUint16BE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يلبي الشرط 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• القيمة المُرجعة: <integer>

يقوم بقراءة عدد صحيح بدون إشارة، كبير النهاية، 16 بت من buf في الإزاحة المحددة offset.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار readUint16BE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56])

console.log(buf.readUInt16BE(0).toString(16))
// Prints: 1234
console.log(buf.readUInt16BE(1).toString(16))
// Prints: 3456

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56])

console.log(buf.readUInt16BE(0).toString(16))
// Prints: 1234
console.log(buf.readUInt16BE(1).toString(16))
// Prints: 3456

buf.readUInt16LE([offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.readUint16LE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يلبي الشرط 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• القيمة المُرجعة: <integer>

يقوم بقراءة عدد صحيح بدون إشارة، صغير النهاية، 16 بت من buf في الإزاحة المحددة offset.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار readUint16LE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56])

console.log(buf.readUInt16LE(0).toString(16))
// Prints: 3412
console.log(buf.readUInt16LE(1).toString(16))
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16))
// Throws ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56])

console.log(buf.readUInt16LE(0).toString(16))
// Prints: 3412
console.log(buf.readUInt16LE(1).toString(16))
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16))
// Throws ERR_OUT_OF_RANGE.

buf.readUInt32BE([offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.readUint32BE().
v10.0.0	تمت إزالة noAssert وعدم وجود إكراه ضمني للإزاحة إلى uint32 بعد الآن.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يلبي الشرط 0 \<= offset \<= buf.length - 4. افتراضيًا: 0.
• الإرجاع: <integer>

يقوم بقراءة عدد صحيح بدون إشارة، كبير النهاية، 32 بت من buf في الإزاحة المحددة.

تتوفر هذه الدالة أيضًا تحت اسم مستعار readUint32BE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])

console.log(buf.readUInt32BE(0).toString(16))
// يطبع: 12345678

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])

console.log(buf.readUInt32BE(0).toString(16))
// يطبع: 12345678

buf.readUInt32LE([offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.readUint32LE().
v10.0.0	تمت إزالة noAssert وعدم وجود إكراه ضمني للإزاحة إلى uint32 بعد الآن.
v0.5.5	تمت الإضافة في: v0.5.5

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يلبي الشرط 0 \<= offset \<= buf.length - 4. افتراضيًا: 0.
• الإرجاع: <integer>

يقوم بقراءة عدد صحيح بدون إشارة، صغير النهاية، 32 بت من buf في الإزاحة المحددة.

تتوفر هذه الدالة أيضًا تحت اسم مستعار readUint32LE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])

console.log(buf.readUInt32LE(0).toString(16))
// يطبع: 78563412
console.log(buf.readUInt32LE(1).toString(16))
// يرمي ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])

console.log(buf.readUInt32LE(0).toString(16))
// يطبع: 78563412
console.log(buf.readUInt32LE(1).toString(16))
// يرمي ERR_OUT_OF_RANGE.

buf.readUIntBE(offset, byteLength)

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.readUintBE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك إكراه ضمني للإزاحة و byteLength إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم قراءتها. يجب أن يحقق 0 \< byteLength \<= 6.
• القيمة المُرجعة: <integer>

يقوم بقراءة byteLength من البايتات من buf عند الإزاحة المُحددة offset ويفسر النتيجة كعدد صحيح بدون إشارة، كبير النهاية، يدعم حتى 48 بت من الدقة.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار readUintBE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readUIntBE(0, 6).toString(16))
// يطبع: 1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16))
// يطرح ERR_OUT_OF_RANGE.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readUIntBE(0, 6).toString(16))
// يطبع: 1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16))
// يطرح ERR_OUT_OF_RANGE.

buf.readUIntLE(offset, byteLength)

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.readUintLE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك إكراه ضمني للإزاحة و byteLength إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في القراءة. يجب أن يحقق 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم قراءتها. يجب أن يحقق 0 \< byteLength \<= 6.
• القيمة المُرجعة: <integer>

يقوم بقراءة byteLength من البايتات من buf عند الإزاحة المُحددة offset ويفسر النتيجة كعدد صحيح بدون إشارة، صغير النهاية، يدعم حتى 48 بت من الدقة.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار readUintLE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readUIntLE(0, 6).toString(16))
// يطبع: ab9078563412

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])

console.log(buf.readUIntLE(0, 6).toString(16))
// يطبع: ab9078563412

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

مضاف في: v3.0.0

• start <integer> حيث يبدأ المُصفوفة الجديدة Buffer. افتراضيًا: 0.
• end <integer> حيث تنتهي المُصفوفة الجديدة Buffer (غير شاملة). افتراضيًا: buf.length.
• مُخرجات: <Buffer>

يُرجِع مُصفوفة Buffer جديدة تشير إلى نفس الذاكرة مثل الأصلية، ولكنها مُزاحة ومُقتَطَعَة بواسطة مُؤشرات start و end.

يُرجِع تحديد end أكبر من buf.length نفس النتيجة التي تُعاد عند تعادل end مع buf.length.

تُورَث هذه الطريقة من TypedArray.prototype.subarray().

سيؤدي تعديل شريحة Buffer الجديدة إلى تعديل الذاكرة في Buffer الأصلية لأن الذاكرة المُخصصة لكلا الكائنين تتداخل.

ESM

import { Buffer } from 'node:buffer'

// إنشاء `Buffer` مع الأبجدية ASCII، وأخذ شريحة، وتعديل بايت واحد
// من `Buffer` الأصلي.

const buf1 = Buffer.allocUnsafe(26)

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf1[i] = i + 97
}

const buf2 = buf1.subarray(0, 3)

console.log(buf2.toString('ascii', 0, buf2.length))
// يُطبع: abc

buf1[0] = 33

console.log(buf2.toString('ascii', 0, buf2.length))
// يُطبع: !bc

CJS

const { Buffer } = require('node:buffer')

// إنشاء `Buffer` مع الأبجدية ASCII، وأخذ شريحة، وتعديل بايت واحد
// من `Buffer` الأصلي.

const buf1 = Buffer.allocUnsafe(26)

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf1[i] = i + 97
}

const buf2 = buf1.subarray(0, 3)

console.log(buf2.toString('ascii', 0, buf2.length))
// يُطبع: abc

buf1[0] = 33

console.log(buf2.toString('ascii', 0, buf2.length))
// يُطبع: !bc

يؤدي تحديد المؤشرات السالبة إلى إنشاء الشريحة نسبةً إلى نهاية buf بدلاً من البداية.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('buffer')

console.log(buf.subarray(-6, -1).toString())
// يُطبع: buffe
// (ما يُعادل buf.subarray(0, 5).)

console.log(buf.subarray(-6, -2).toString())
// يُطبع: buff
// (ما يُعادل buf.subarray(0, 4).)

console.log(buf.subarray(-5, -2).toString())
// يُطبع: uff
// (ما يُعادل buf.subarray(1, 4).)

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('buffer')

console.log(buf.subarray(-6, -1).toString())
// يُطبع: buffe
// (ما يُعادل buf.subarray(0, 5).)

console.log(buf.subarray(-6, -2).toString())
// يُطبع: buff
// (ما يُعادل buf.subarray(0, 4).)

console.log(buf.subarray(-5, -2).toString())
// يُطبع: uff
// (ما يُعادل buf.subarray(1, 4).)

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

[History]

الإصدار	التغييرات
v17.5.0, v16.15.0	تم إهمال طريقة buf.slice().
v7.0.0	يتم الآن إجبار جميع الإزاحات على الأعداد الصحيحة قبل إجراء أي حسابات بها.
v7.1.0, v6.9.2	تتعامل عملية إجبار الإزاحات على الأعداد الصحيحة الآن مع القيم خارج نطاق عدد صحيح 32 بت بشكل صحيح.
v0.3.0	تمت الإضافة في: v0.3.0

• start <integer> مكان بدء Buffer الجديد. الافتراضي: 0.
• end <integer> مكان انتهاء Buffer الجديد (غير شاملة). الافتراضي: buf.length.
• القيمة المُرجعة: <Buffer>

[مستقر: 0 - مُهمل]

مستقر: 0 الثبات: 0 - مُهمل: استخدم buf.subarray بدلاً من ذلك.

يرجع Buffer جديدًا يشير إلى نفس الذاكرة مثل الأصل، ولكن يتم إزاحته وتقليمها بواسطة مؤشرات start و end.

هذه الطريقة غير متوافقة مع Uint8Array.prototype.slice(), وهو فئة عليا من Buffer. لنسخ الشريحة، استخدم Uint8Array.prototype.slice().

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('buffer')

const copiedBuf = Uint8Array.prototype.slice.call(buf)
copiedBuf[0]++
console.log(copiedBuf.toString())
// يُطبع: cuffer

console.log(buf.toString())
// يُطبع: buffer

// مع buf.slice()، يتم تعديل المخزن المؤقت الأصلي.
const notReallyCopiedBuf = buf.slice()
notReallyCopiedBuf[0]++
console.log(notReallyCopiedBuf.toString())
// يُطبع: cuffer
console.log(buf.toString())
// يُطبع أيضًا: cuffer (!)

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('buffer')

const copiedBuf = Uint8Array.prototype.slice.call(buf)
copiedBuf[0]++
console.log(copiedBuf.toString())
// يُطبع: cuffer

console.log(buf.toString())
// يُطبع: buffer

// مع buf.slice()، يتم تعديل المخزن المؤقت الأصلي.
const notReallyCopiedBuf = buf.slice()
notReallyCopiedBuf[0]++
console.log(notReallyCopiedBuf.toString())
// يُطبع: cuffer
console.log(buf.toString())
// يُطبع أيضًا: cuffer (!)

buf.swap16()

مضاف في: v5.10.0

• قيمة الإرجاع: <Buffer> مرجع إلى buf.

يفسر buf كمصفوفة من الأعداد الصحيحة بدون إشارة 16 بت، ويبدل ترتيب البايتات مباشرة. يرمي ERR_INVALID_BUFFER_SIZE إذا لم يكن buf.length مضاعفًا لـ 2.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])

console.log(buf1)
// يطبع: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap16()

console.log(buf1)
// يطبع: <Buffer 02 01 04 03 06 05 08 07>

const buf2 = Buffer.from([0x1, 0x2, 0x3])

buf2.swap16()
// يرمي ERR_INVALID_BUFFER_SIZE.

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])

console.log(buf1)
// يطبع: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap16()

console.log(buf1)
// يطبع: <Buffer 02 01 04 03 06 05 08 07>

const buf2 = Buffer.from([0x1, 0x2, 0x3])

buf2.swap16()
// يرمي ERR_INVALID_BUFFER_SIZE.

من الاستخدامات الملائمة لـ buf.swap16() إجراء تحويل سريع مباشر بين UTF-16 little-endian و UTF-16 big-endian:

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('This is little-endian UTF-16', 'utf16le')
buf.swap16() // تحويل إلى نص UTF-16 big-endian.

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('This is little-endian UTF-16', 'utf16le')
buf.swap16() // تحويل إلى نص UTF-16 big-endian.

buf.swap32()

مضاف في: v5.10.0

• قيمة الإرجاع: <Buffer> مرجع إلى buf.

يفسر buf كمصفوفة من الأعداد الصحيحة بدون إشارة 32 بت، ويبدل ترتيب البايتات مباشرة. يرمي ERR_INVALID_BUFFER_SIZE إذا لم يكن buf.length مضاعفًا لـ 4.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])

console.log(buf1)
// يطبع: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap32()

console.log(buf1)
// يطبع: <Buffer 04 03 02 01 08 07 06 05>

const buf2 = Buffer.from([0x1, 0x2, 0x3])

buf2.swap32()
// يرمي ERR_INVALID_BUFFER_SIZE.

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])

console.log(buf1)
// يطبع: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap32()

console.log(buf1)
// يطبع: <Buffer 04 03 02 01 08 07 06 05>

const buf2 = Buffer.from([0x1, 0x2, 0x3])

buf2.swap32()
// يرمي ERR_INVALID_BUFFER_SIZE.

buf.swap64()

مضاف في: v6.3.0

• مُخرجات: <Buffer> مرجع إلى buf.

يُفسر buf كمصفوفة من الأعداد 64 بت ويُبدل ترتيب البايتات مباشرة. يُطلق استثناء ERR_INVALID_BUFFER_SIZE إذا لم يكن buf.length مضاعفاً لـ 8.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])

console.log(buf1)
// يُطبع: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap64()

console.log(buf1)
// يُطبع: <Buffer 08 07 06 05 04 03 02 01>

const buf2 = Buffer.from([0x1, 0x2, 0x3])

buf2.swap64()
// يُطلق ERR_INVALID_BUFFER_SIZE.

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])

console.log(buf1)
// يُطبع: <Buffer 01 02 03 04 05 06 07 08>

buf1.swap64()

console.log(buf1)
// يُطبع: <Buffer 08 07 06 05 04 03 02 01>

const buf2 = Buffer.from([0x1, 0x2, 0x3])

buf2.swap64()
// يُطلق ERR_INVALID_BUFFER_SIZE.

buf.toJSON()

مضاف في: v0.9.2

• مُخرجات: <Object>

يُعيد تمثيل JSON لـ buf. تُدعو الدالة JSON.stringify() ضمنياً عند تحويل مثيل Buffer إلى سلسلة نصية.

تقبل Buffer.from() كائنات بالصيغة المُرتجعة من هذه الطريقة. على وجه الخصوص، يعمل Buffer.from(buf.toJSON()) مثل Buffer.from(buf).

ESM

import { Buffer } from 'node:buffer'

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

console.log(json)
// يُطبع: {"type":"Buffer","data":[1,2,3,4,5]}

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

console.log(copy)
// يُطبع: <Buffer 01 02 03 04 05>

CJS

const { Buffer } = require('node:buffer')

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

console.log(json)
// يُطبع: {"type":"Buffer","data":[1,2,3,4,5]}

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

console.log(copy)
// يُطبع: <Buffer 01 02 03 04 05>

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

أضيف في: v0.1.90

• 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.

ESM

import { Buffer } from 'node:buffer'

const buf1 = Buffer.allocUnsafe(26)

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf1[i] = i + 97
}

console.log(buf1.toString('utf8'))
// يطبع: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5))
// يطبع: abcde

const buf2 = Buffer.from('tést')

console.log(buf2.toString('hex'))
// يطبع: 74c3a97374
console.log(buf2.toString('utf8', 0, 3))
// يطبع: té
console.log(buf2.toString(undefined, 0, 3))
// يطبع: té

CJS

const { Buffer } = require('node:buffer')

const buf1 = Buffer.allocUnsafe(26)

for (let i = 0; i < 26; i++) {
  // 97 هي القيمة العشرية ASCII لـ 'a'.
  buf1[i] = i + 97
}

console.log(buf1.toString('utf8'))
// يطبع: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5))
// يطبع: abcde

const buf2 = Buffer.from('tést')

console.log(buf2.toString('hex'))
// يطبع: 74c3a97374
console.log(buf2.toString('utf8', 0, 3))
// يطبع: té
console.log(buf2.toString(undefined, 0, 3))
// يطبع: té

buf.values()

أضيف في: v1.1.0

• الإرجاع: <Iterator>

يقوم بإنشاء وإرجاع مُكرر iterator لقيم buf (بايت). يتم استدعاء هذه الدالة تلقائيًا عند استخدام Buffer في جملة for..of.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.from('buffer')

for (const value of buf.values()) {
  console.log(value)
}
// يطبع:
//   98
//   117
//   102
//   102
//   101
//   114

for (const value of buf) {
  console.log(value)
}
// يطبع:
//   98
//   117
//   102
//   102
//   101
//   114

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.from('buffer')

for (const value of buf.values()) {
  console.log(value)
}
// يطبع:
//   98
//   117
//   102
//   102
//   101
//   114

for (const value of buf) {
  console.log(value)
}
// يطبع:
//   98
//   117
//   102
//   102
//   101
//   114

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

أضيف في: v0.1.90

• string <string> سلسلة نصية لكتابتها في buf.
• offset <integer> عدد البايت التي يجب تخطيها قبل البدء في كتابة string. الافتراضي: 0.
• length <integer> الحد الأقصى لعدد البايت التي سيتم كتابتها (لن يتجاوز عدد البايت المكتوبة buf.length - offset). الافتراضي: buf.length - offset.
• encoding <string> ترميز الأحرف لـ string. الافتراضي: 'utf8'.
• الإرجاع: <integer> عدد البايت المكتوبة.

يكتب string إلى buf عند offset وفقًا لترميز الأحرف في encoding. معلمة length هي عدد البايت التي سيتم كتابتها. إذا لم يكن buf يحتوي على مساحة كافية لتناسب السلسلة بأكملها، فسيتم كتابة جزء فقط من string. ومع ذلك، لن يتم كتابة الأحرف المشفرة جزئيًا.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.alloc(256)

const len = buf.write('\u00bd + \u00bc = \u00be', 0)

console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`)
// يطبع: 12 bytes: ½ + ¼ = ¾

const buffer = Buffer.alloc(10)

const length = buffer.write('abcd', 8)

console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`)
// يطبع: 2 bytes : ab

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.alloc(256)

const len = buf.write('\u00bd + \u00bc = \u00be', 0)

console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`)
// يطبع: 12 bytes: ½ + ¼ = ¾

const buffer = Buffer.alloc(10)

const length = buffer.write('abcd', 8)

console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`)
// يطبع: 2 bytes : ab

buf.writeBigInt64BE(value[, offset])

مضاف في: v12.0.0، v10.20.0

• value <bigint> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء بالكتابة. يجب أن يحقق الشرط: 0 \<= offset \<= buf.length - 8. الافتراضي: 0.
• القيمة المرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf في offset المحدد كـ big-endian.

يتم تفسير value وكتابته كعدد صحيح ذي إشارة مكمل للثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(8)

buf.writeBigInt64BE(0x0102030405060708n, 0)

console.log(buf)
// Prints: <Buffer 01 02 03 04 05 06 07 08>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(8)

buf.writeBigInt64BE(0x0102030405060708n, 0)

console.log(buf)
// Prints: <Buffer 01 02 03 04 05 06 07 08>

buf.writeBigInt64LE(value[, offset])

مضاف في: v12.0.0، v10.20.0

• value <bigint> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء بالكتابة. يجب أن يحقق الشرط: 0 \<= offset \<= buf.length - 8. الافتراضي: 0.
• القيمة المرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf في offset المحدد كـ little-endian.

يتم تفسير value وكتابته كعدد صحيح ذي إشارة مكمل للثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(8)

buf.writeBigInt64LE(0x0102030405060708n, 0)

console.log(buf)
// Prints: <Buffer 08 07 06 05 04 03 02 01>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(8)

buf.writeBigInt64LE(0x0102030405060708n, 0)

console.log(buf)
// Prints: <Buffer 08 07 06 05 04 03 02 01>

buf.writeBigUInt64BE(value[, offset])

[History]

الإصدار	التغييرات
v14.10.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeBigUint64BE().
v12.0.0, v10.20.0	تمت الإضافة في: v12.0.0, v10.20.0

• value <bigint> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يستوفي الشرط: 0 \<= offset \<= buf.length - 8. افتراضيًا: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf في offset المحدد كـ big-endian.

تتوفر هذه الدالة أيضًا تحت اسم مستعار writeBigUint64BE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(8)

buf.writeBigUInt64BE(0xdecafafecacefaden, 0)

console.log(buf)
// Prints: <Buffer de ca fa fe ca ce fa de>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(8)

buf.writeBigUInt64BE(0xdecafafecacefaden, 0)

console.log(buf)
// Prints: <Buffer de ca fa fe ca ce fa de>

buf.writeBigUInt64LE(value[, offset])

[History]

الإصدار	التغييرات
v14.10.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeBigUint64LE().
v12.0.0, v10.20.0	تمت الإضافة في: v12.0.0, v10.20.0

• value <bigint> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يستوفي الشرط: 0 \<= offset \<= buf.length - 8. افتراضيًا: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf في offset المحدد كـ little-endian.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(8)

buf.writeBigUInt64LE(0xdecafafecacefaden, 0)

console.log(buf)
// Prints: <Buffer de fa ce ca fe fa ca de>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(8)

buf.writeBigUInt64LE(0xdecafafecacefaden, 0)

console.log(buf)
// Prints: <Buffer de fa ce ca fe fa ca de>

تتوفر هذه الدالة أيضًا تحت اسم مستعار writeBigUint64LE.

buf.writeDoubleBE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• value <number> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بـ 0 \<= offset \<= buf.length - 8. افتراضي: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كـ big-endian. يجب أن يكون value رقمًا في جافا سكريبت. السلوك غير مُعرّف عندما يكون value أي شيء آخر غير رقم جافا سكريبت.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(8)

buf.writeDoubleBE(123.456, 0)

console.log(buf)
// Prints: <Buffer 40 5e dd 2f 1a 9f be 77>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(8)

buf.writeDoubleBE(123.456, 0)

console.log(buf)
// Prints: <Buffer 40 5e dd 2f 1a 9f be 77>

buf.writeDoubleLE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• value <number> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بـ 0 \<= offset \<= buf.length - 8. افتراضي: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كـ little-endian. يجب أن يكون value رقمًا في جافا سكريبت. السلوك غير مُعرّف عندما يكون value أي شيء آخر غير رقم جافا سكريبت.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(8)

buf.writeDoubleLE(123.456, 0)

console.log(buf)
// Prints: <Buffer 77 be 9f 1a 2f dd 5e 40>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(8)

buf.writeDoubleLE(123.456, 0)

console.log(buf)
// Prints: <Buffer 77 be 9f 1a 2f dd 5e 40>

buf.writeFloatBE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• value <number> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. افتراضيًا: 0.
• القيمة المعادة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كبيانات كبيرة النهاية. السلوك غير معرف عندما يكون value أي شيء آخر غير رقم جافا سكريبت.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeFloatBE(0xcafebabe, 0)

console.log(buf)
// Prints: <Buffer 4f 4a fe bb>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeFloatBE(0xcafebabe, 0)

console.log(buf)
// Prints: <Buffer 4f 4a fe bb>

buf.writeFloatLE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• value <number> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. افتراضيًا: 0.
• القيمة المعادة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كبيانات صغيرة النهاية. السلوك غير معرف عندما يكون value أي شيء آخر غير رقم جافا سكريبت.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeFloatLE(0xcafebabe, 0)

console.log(buf)
// Prints: <Buffer bb fe 4a 4f>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeFloatLE(0xcafebabe, 0)

console.log(buf)
// Prints: <Buffer bb fe 4a 4f>

buf.writeInt8(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك إكراه ضمني للإزاحة إلى uint32.
v0.5.0	تمت الإضافة في: v0.5.0

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بـ 0 \<= offset \<= buf.length - 1. الافتراضي: 0.
• الإرجاع: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset. يجب أن يكون value عددًا صحيحًا صحيحًا ذي 8 بت. يكون السلوك غير محدد عندما يكون value أي شيء آخر غير عدد صحيح صحيح ذي 8 بت.

يتم تفسير value وكتابته كعدد صحيح موقّع ذي مكمل ثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(2)

buf.writeInt8(2, 0)
buf.writeInt8(-2, 1)

console.log(buf)
// Prints: <Buffer 02 fe>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(2)

buf.writeInt8(2, 0)
buf.writeInt8(-2, 1)

console.log(buf)
// Prints: <Buffer 02 fe>

buf.writeInt16BE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك إكراه ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بـ 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• الإرجاع: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كـ big-endian. يجب أن يكون value عددًا صحيحًا صحيحًا ذي 16 بت. يكون السلوك غير محدد عندما يكون value أي شيء آخر غير عدد صحيح صحيح ذي 16 بت.

يتم تفسير value وكتابته كعدد صحيح موقّع ذي مكمل ثنائي.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(2)

buf.writeInt16BE(0x0102, 0)

console.log(buf)
// Prints: <Buffer 01 02>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(2)

buf.writeInt16BE(0x0102, 0)

console.log(buf)
// Prints: <Buffer 01 02>

buf.writeInt16LE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء بالكتابة. يجب أن يحقق الشرط 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• الإرجاع: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة offset المحددة كـ little-endian. يجب أن يكون value عددًا صحيحًا ذي علامة صحيحًا مكونًا من 16 بت. السلوك غير مُعرّف عندما يكون value أي شيء آخر غير عدد صحيح ذي علامة مكون من 16 بت.

يتم تفسير value وكتابته كعدد صحيح ذي علامة مُكمّل للثنائيات.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(2)

buf.writeInt16LE(0x0304, 0)

console.log(buf)
// يطبع: <Buffer 04 03>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(2)

buf.writeInt16LE(0x0304, 0)

console.log(buf)
// يطبع: <Buffer 04 03>

buf.writeInt32BE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء بالكتابة. يجب أن يحقق الشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• الإرجاع: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة offset المحددة كـ big-endian. يجب أن يكون value عددًا صحيحًا ذي علامة صحيحًا مكونًا من 32 بت. السلوك غير مُعرّف عندما يكون value أي شيء آخر غير عدد صحيح ذي علامة مكون من 32 بت.

يتم تفسير value وكتابته كعدد صحيح ذي علامة مُكمّل للثنائيات.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeInt32BE(0x01020304, 0)

console.log(buf)
// يطبع: <Buffer 01 02 03 04>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeInt32BE(0x01020304, 0)

console.log(buf)
// يطبع: <Buffer 01 02 03 04>

buf.writeInt32LE(value[, offset])

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يستوفي الشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المُحددة offset كصغير النهاية. يجب أن يكون value عددًا صحيحًا ذي علامة 32 بت صالحًا. السلوك غير مُعرّف عندما يكون value أي شيء آخر غير عدد صحيح ذي علامة 32 بت.

يتم تفسير value وكتابته كعدد صحيح ذي علامة مكمل للزوجين.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeInt32LE(0x05060708, 0)

console.log(buf)
// يطبع: <Buffer 08 07 06 05>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeInt32LE(0x05060708, 0)

console.log(buf)
// يطبع: <Buffer 08 07 06 05>

buf.writeIntBE(value, offset, byteLength)

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة و byteLength إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يستوفي الشرط 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم كتابتها. يجب أن يستوفي الشرط 0 \< byteLength \<= 6.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب byteLength بايت من value إلى buf عند الإزاحة المُحددة offset ككبير النهاية. يدعم ما يصل إلى 48 بت من الدقة. السلوك غير مُعرّف عندما يكون value أي شيء آخر غير عدد صحيح ذي علامة.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(6)

buf.writeIntBE(0x1234567890ab, 0, 6)

console.log(buf)
// يطبع: <Buffer 12 34 56 78 90 ab>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(6)

buf.writeIntBE(0x1234567890ab, 0, 6)

console.log(buf)
// يطبع: <Buffer 12 34 56 78 90 ab>

buf.writeIntLE(value, offset, byteLength)

[History]

الإصدار	التغييرات
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني لـ offset و byteLength إلى uint32.
v0.11.15	تمت الإضافة في: v0.11.15

• value <عدد صحيح> العدد الذي سيتم كتابته في buf.
• offset <عدد صحيح> عدد البايتات التي سيتم تخطيها قبل البدء بالكتابة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - byteLength.
• byteLength <عدد صحيح> عدد البايتات التي سيتم كتابتها. يجب أن يفي بشرط 0 \< byteLength \<= 6.
• القيمة المُرجعة: <عدد صحيح> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب byteLength بايت من value إلى buf عند offset المحدد كـ little-endian. يدعم حتى 48 بت من الدقة. السلوك غير معرف عندما يكون value أي شيء آخر غير عدد صحيح ذي إشارة.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(6)

buf.writeIntLE(0x1234567890ab, 0, 6)

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

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(6)

buf.writeIntLE(0x1234567890ab, 0, 6)

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

buf.writeUInt8(value[, offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUint8().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني لـ offset إلى uint32.
v0.5.0	تمت الإضافة في: v0.5.0

• value <عدد صحيح> العدد الذي سيتم كتابته في buf.
• offset <عدد صحيح> عدد البايتات التي سيتم تخطيها قبل البدء بالكتابة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 1. الافتراضي: 0.
• القيمة المُرجعة: <عدد صحيح> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند offset المحدد. يجب أن يكون value عددًا صحيحًا بدون إشارة ذي 8 بت صحيحًا. السلوك غير معرف عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة ذي 8 بت.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار writeUint8.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeUInt8(0x3, 0)
buf.writeUInt8(0x4, 1)
buf.writeUInt8(0x23, 2)
buf.writeUInt8(0x42, 3)

console.log(buf)
// Prints: <Buffer 03 04 23 42>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeUInt8(0x3, 0)
buf.writeUInt8(0x4, 1)
buf.writeUInt8(0x23, 2)
buf.writeUInt8(0x42, 3)

console.log(buf)
// Prints: <Buffer 03 04 23 42>

buf.writeUInt16BE(value[, offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUint16BE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بـ 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• القيمة المرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كـ big-endian. يجب أن يكون value عدد صحيحًا صحيحًا بدون إشارة من 16 بت. السلوك غير محدد عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة من 16 بت.

تتوفر هذه الدالة أيضًا تحت اسم writeUint16BE المُستعار.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeUInt16BE(0xdead, 0)
buf.writeUInt16BE(0xbeef, 2)

console.log(buf)
// Prints: <Buffer de ad be ef>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeUInt16BE(0xdead, 0)
buf.writeUInt16BE(0xbeef, 2)

console.log(buf)
// Prints: <Buffer de ad be ef>

buf.writeUInt16LE(value[, offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUint16LE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني للإزاحة إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بـ 0 \<= offset \<= buf.length - 2. الافتراضي: 0.
• القيمة المرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf عند الإزاحة المحددة offset كـ little-endian. يجب أن يكون value عدد صحيحًا صحيحًا بدون إشارة من 16 بت. السلوك غير محدد عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة من 16 بت.

تتوفر هذه الدالة أيضًا تحت اسم writeUint16LE المُستعار.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeUInt16LE(0xdead, 0)
buf.writeUInt16LE(0xbeef, 2)

console.log(buf)
// Prints: <Buffer ad de ef be>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeUInt16LE(0xdead, 0)
buf.writeUInt16LE(0xbeef, 2)

console.log(buf)
// Prints: <Buffer ad de ef be>

buf.writeUInt32BE(value[, offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUint32BE().
v10.0.0	تمت إزالة noAssert وعدم وجود إكراه ضمني للإزاحة إلى uint32 بعد الآن.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf في الإزاحة المحددة offset على هيئة big-endian. يجب أن يكون value عددًا صحيحًا بدون إشارة من 32 بت. السلوك غير محدد عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة من 32 بت.

تتوفر هذه الدالة أيضًا تحت اسم writeUint32BE المستعار.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeUInt32BE(0xfeedface, 0)

console.log(buf)
// Prints: <Buffer fe ed fa ce>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeUInt32BE(0xfeedface, 0)

console.log(buf)
// Prints: <Buffer fe ed fa ce>

buf.writeUInt32LE(value[, offset])

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUint32LE().
v10.0.0	تمت إزالة noAssert وعدم وجود إكراه ضمني للإزاحة إلى uint32 بعد الآن.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يفي بشرط 0 \<= offset \<= buf.length - 4. الافتراضي: 0.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب value إلى buf في الإزاحة المحددة offset على هيئة little-endian. يجب أن يكون value عددًا صحيحًا بدون إشارة من 32 بت. السلوك غير محدد عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة من 32 بت.

تتوفر هذه الدالة أيضًا تحت اسم writeUint32LE المستعار.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(4)

buf.writeUInt32LE(0xfeedface, 0)

console.log(buf)
// Prints: <Buffer ce fa ed fe>

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(4)

buf.writeUInt32LE(0xfeedface, 0)

console.log(buf)
// Prints: <Buffer ce fa ed fe>

buf.writeUIntBE(value, offset, byteLength)

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUintBE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني لـ offset و byteLength إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يلبي الشرط 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم كتابتها. يجب أن يلبي الشرط 0 \< byteLength \<= 6.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب byteLength بايت من value إلى buf في offset المحدد كـ big-endian. يدعم ما يصل إلى 48 بت من الدقة. السلوك غير مُعرف عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار writeUintBE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(6)

buf.writeUIntBE(0x1234567890ab, 0, 6)

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

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(6)

buf.writeUIntBE(0x1234567890ab, 0, 6)

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

buf.writeUIntLE(value, offset, byteLength)

[History]

الإصدار	التغييرات
v14.9.0, v12.19.0	تتوفر هذه الدالة أيضًا باسم buf.writeUintLE().
v10.0.0	تمت إزالة noAssert ولم يعد هناك تحويل ضمني لـ offset و byteLength إلى uint32.
v0.5.5	تمت الإضافة في: v0.5.5

• value <integer> الرقم الذي سيتم كتابته في buf.
• offset <integer> عدد البايتات التي سيتم تخطيها قبل البدء في الكتابة. يجب أن يلبي الشرط 0 \<= offset \<= buf.length - byteLength.
• byteLength <integer> عدد البايتات التي سيتم كتابتها. يجب أن يلبي الشرط 0 \< byteLength \<= 6.
• القيمة المُرجعة: <integer> offset بالإضافة إلى عدد البايتات المكتوبة.

يكتب byteLength بايت من value إلى buf في offset المحدد كـ little-endian. يدعم ما يصل إلى 48 بت من الدقة. السلوك غير مُعرف عندما يكون value أي شيء آخر غير عدد صحيح بدون إشارة.

تتوفر هذه الدالة أيضًا تحت اسم مُستعار writeUintLE.

ESM

import { Buffer } from 'node:buffer'

const buf = Buffer.allocUnsafe(6)

buf.writeUIntLE(0x1234567890ab, 0, 6)

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

CJS

const { Buffer } = require('node:buffer')

const buf = Buffer.allocUnsafe(6)

buf.writeUIntLE(0x1234567890ab, 0, 6)

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

new Buffer(array)

[السجل]

الإصدار	التغييرات
v10.0.0	يؤدي استدعاء مُنشئ هذا إلى إصدار تحذير بالإهمال عند تشغيله من التعليمات البرمجية خارج دليل node_modules.
v7.2.1	لم يعد استدعاء مُنشئ هذا يُصدر تحذيرًا بالإهمال.
v7.0.0	يُصدر استدعاء مُنشئ هذا تحذيرًا بالإهمال الآن.
v6.0.0	مُهمل منذ: v6.0.0

[مستقر: 0 - مُهمل]

مستقر: 0 الثبات: 0 - مُهمل: استخدم Buffer.from(array) بدلاً من ذلك.

• array <integer[]> مصفوفة من البايتات لنسخها من.

انظر Buffer.from(array).

new Buffer(arrayBuffer[, byteOffset[, length]])

[السجل]

الإصدار	التغييرات
v10.0.0	يؤدي استدعاء مُنشئ هذا إلى إصدار تحذير بالإهمال عند تشغيله من التعليمات البرمجية خارج دليل node_modules.
v7.2.1	لم يعد استدعاء مُنشئ هذا يُصدر تحذيرًا بالإهمال.
v7.0.0	يُصدر استدعاء مُنشئ هذا تحذيرًا بالإهمال الآن.
v6.0.0	يتم دعم معاملتي byteOffset و length الآن.
v6.0.0	مُهمل منذ: v6.0.0
v3.0.0	تمت الإضافة في: v3.0.0

[مستقر: 0 - مُهمل]

مستقر: 0 الثبات: 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)

[History]

الإصدار	التغييرات
v10.0.0	يُصدر هذا المُنشئ تحذيرًا بالإهمال عند تشغيله من التعليمات البرمجية خارج مجلد node_modules.
v7.2.1	لم يعد هذا المُنشئ يُصدر تحذيرًا بالإهمال.
v7.0.0	يُصدر هذا المُنشئ تحذيرًا بالإهمال الآن.
v6.0.0	مُهمل منذ: v6.0.0

[مستقر: 0 - مُهمل]

مستقر: 0 استقرار: 0 - مُهمل: استخدم Buffer.from(buffer) بدلاً من ذلك.

• buffer <Buffer> | <Uint8Array> مُخزن مؤقت Buffer أو مصفوفة Uint8Array موجودة لنسخ البيانات منها.

انظر Buffer.from(buffer).

new Buffer(size)

[History]

الإصدار	التغييرات
v10.0.0	يُصدر هذا المُنشئ تحذيرًا بالإهمال عند تشغيله من التعليمات البرمجية خارج مجلد node_modules.
v8.0.0	سيُعيد new Buffer(size) ذاكرة مُملوءة بالأصفار افتراضيًا.
v7.2.1	لم يعد هذا المُنشئ يُصدر تحذيرًا بالإهمال.
v7.0.0	يُصدر هذا المُنشئ تحذيرًا بالإهمال الآن.
v6.0.0	مُهمل منذ: v6.0.0

[مستقر: 0 - مُهمل]

مستقر: 0 استقرار: 0 - مُهمل: استخدم Buffer.alloc() بدلاً من ذلك (انظر أيضًا Buffer.allocUnsafe()).

• size <integer> الطول المطلوب للمُخزن المؤقت Buffer الجديد.

انظر Buffer.alloc() و Buffer.allocUnsafe(). هذا البديل من المُنشئ يُعادل Buffer.alloc().

new Buffer(string[, encoding])

[السجل]

الإصدار	التغييرات
v10.0.0	يؤدي استدعاء مُنشئ هذا إلى إصدار تحذير بالإهمال عند تشغيله من التعليمات البرمجية خارج دليل node_modules.
v7.2.1	لم يعد استدعاء مُنشئ هذا يُصدر تحذيرًا بالإهمال.
v7.0.0	يُصدر استدعاء مُنشئ هذا تحذيرًا بالإهمال الآن.
v6.0.0	مُهمل منذ: v6.0.0

[مستقر: 0 - مُهمل]

مستقر: 0 ثبات: 0 - مُهمل: استخدم Buffer.from(string[, encoding]) بدلاً من ذلك.

• string <string> سلسلة لتشفيرها.
• encoding <string> ترميز string. الافتراضي: 'utf8'.

انظر Buffer.from(string[, encoding]).

الفئة: File

[السجل]

الإصدار	التغييرات
v23.0.0	يجعل مثيلات File قابلة للاستنساخ.
v20.0.0	لم تعد تجريبية.
v19.2.0، v18.13.0	تمت الإضافة في: v19.2.0، v18.13.0

• يمتد: <Blob>

يوفر File معلومات حول الملفات.

new buffer.File(sources, fileName[, options])

تمت الإضافة في: v19.2.0، v18.13.0

• sources <string[]> | <ArrayBuffer[]> | <TypedArray[]> | <DataView[]> | <Blob[]> | <File[]> مصفوفة من سلاسل، <ArrayBuffer>، <TypedArray>، <DataView>، <File>، أو <Blob> كائنات، أو أي مزيج من هذه الكائنات، سيتم تخزينها داخل File.
• fileName <string> اسم الملف.
• options <Object>
  • endings <string> أحد 'transparent' أو 'native'. عند تعيينه على 'native'، سيتم تحويل نهايات الأسطر في أجزاء المصدر النصية إلى نهاية السطر الأصلية للمنصة كما هو محدد بواسطة require('node:os').EOL.
  • type <string> نوع محتوى الملف.
  • lastModified <number> تاريخ آخر تعديل للملف. الافتراضي: Date.now().

file.name

تم الإضافة في: v19.2.0، v18.13.0

• النوع: <string>

اسم الملف File.

file.lastModified

تم الإضافة في: v19.2.0، v18.13.0

• النوع: <number>

تاريخ آخر تعديل للملف File.

واجهات برمجة التطبيقات وحدة node:buffer

في حين أن كائن Buffer متوفر ككائن عام، هناك واجهات برمجة تطبيقات إضافية متعلقة بـ Buffer متاحة فقط عبر وحدة node:buffer التي يتم الوصول إليها باستخدام require('node:buffer').

buffer.atob(data)

تم الإضافة في: v15.13.0، v14.17.0

[مستقر: 3 - قديم]

مستقر: 3 الثبات: 3 - قديم. استخدم Buffer.from(data, 'base64') بدلاً من ذلك.

• data <any> سلسلة الإدخال المشفرة بـ Base64.

يقوم بفك تشفير سلسلة من البيانات المشفرة بـ Base64 إلى بايت، ويشفر هذه البايت إلى سلسلة باستخدام Latin-1 (ISO-8859-1).

قد يكون data أي قيمة JavaScript يمكن تحويلها إلى سلسلة.

يتم توفير هذه الدالة فقط للتوافق مع واجهات برمجة تطبيقات منصة الويب القديمة ويجب عدم استخدامها أبدًا في التعليمات البرمجية الجديدة، لأنها تستخدم سلاسل لتمثيل البيانات الثنائية وتسبق تقديم المصفوفات المكتوبة في JavaScript. بالنسبة للكود الذي يعمل باستخدام واجهات برمجة تطبيقات Node.js، يجب إجراء التحويل بين السلاسل المشفرة بـ base64 والبيانات الثنائية باستخدام Buffer.from(str, 'base64') و buf.toString('base64').

buffer.btoa(data)

تم الإضافة في: v15.13.0، v14.17.0

[مستقر: 3 - قديم]

مستقر: 3 الثبات: 3 - قديم. استخدم buf.toString('base64') بدلاً من ذلك.

• data <any> سلسلة ASCII (Latin1).

يقوم بفك تشفير سلسلة إلى بايت باستخدام Latin-1 (ISO-8859)، ويشفر هذه البايت إلى سلسلة باستخدام Base64.

قد يكون data أي قيمة JavaScript يمكن تحويلها إلى سلسلة.

يتم توفير هذه الدالة فقط للتوافق مع واجهات برمجة تطبيقات منصة الويب القديمة ويجب عدم استخدامها أبدًا في التعليمات البرمجية الجديدة، لأنها تستخدم سلاسل لتمثيل البيانات الثنائية وتسبق تقديم المصفوفات المكتوبة في JavaScript. بالنسبة للكود الذي يعمل باستخدام واجهات برمجة تطبيقات Node.js، يجب إجراء التحويل بين السلاسل المشفرة بـ base64 والبيانات الثنائية باستخدام Buffer.from(str, 'base64') و buf.toString('base64').

buffer.isAscii(input)

مضاف في: v19.6.0، v18.15.0

• input <Buffer> | <ArrayBuffer> | <TypedArray> المدخل المراد التحقق منه.
• العائد: <boolean>

تعيد هذه الدالة true إذا كان input يحتوي فقط على بيانات مشفرة بـ ASCII صالحة، بما في ذلك الحالة التي يكون فيها input فارغًا.

ترمي خطأ إذا كان input عبارة عن مصفوفة بايت مفككة.

buffer.isUtf8(input)

مضاف في: v19.4.0، v18.14.0

• input <Buffer> | <ArrayBuffer> | <TypedArray> المدخل المراد التحقق منه.
• العائد: <boolean>

تعيد هذه الدالة true إذا كان input يحتوي فقط على بيانات مشفرة بـ UTF-8 صالحة، بما في ذلك الحالة التي يكون فيها input فارغًا.

ترمي خطأ إذا كان input عبارة عن مصفوفة بايت مفككة.

buffer.INSPECT_MAX_BYTES

مضاف في: v0.5.4

• <integer> افتراضيًا: 50

يعيد الحد الأقصى لعدد البايتات التي سيتم إرجاعها عند استدعاء buf.inspect(). يمكن تجاوز ذلك بواسطة وحدات المستخدم. راجع util.inspect() لمزيد من التفاصيل حول سلوك buf.inspect().

buffer.kMaxLength

مضاف في: v3.0.0

• <integer> أكبر حجم مسموح به لمثيل Buffer واحد.

اسم آخر لـ buffer.constants.MAX_LENGTH.

buffer.kStringMaxLength

مضاف في: v3.0.0

• <integer> أقصى طول مسموح به لمثيل string واحد.

اسم آخر لـ buffer.constants.MAX_STRING_LENGTH.

buffer.resolveObjectURL(id)

مضاف في: v16.7.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

• id <string> سلسلة URL من نوع 'blob:nodedata:... تم إرجاعها من خلال اتصال سابق بـ URL.createObjectURL().
• قيمة الإرجاع: <Blob>

يُحلل 'blob:nodedata:...' إلى كائن <Blob> مرتبط مُسجل باستخدام اتصال سابق بـ URL.createObjectURL().

buffer.transcode(source, fromEnc, toEnc)

[السجل]

الإصدار	التغييرات
v8.0.0	أصبح بإمكان معلمة source الآن أن تكون Uint8Array.
v7.1.0	مضاف في: v7.1.0

• source <Buffer> | <Uint8Array> مثيل Buffer أو Uint8Array.
• fromEnc <string> ترميز الأحرف الحالي.
• toEnc <string> ترميز الأحرف الهدف.
• قيمة الإرجاع: <Buffer>

يعيد ترميز مثيل Buffer أو Uint8Array المُعطى من ترميز أحرف واحد إلى آخر. يُرجع مثيلًا جديدًا من Buffer.

يُطرح استثناء إذا كانت fromEnc أو toEnc تُحدد ترميزات أحرف غير صالحة أو إذا لم يكن التحويل من fromEnc إلى toEnc مُسموحًا به.

تشمل ترميزات الأحرف التي يدعمها buffer.transcode(): 'ascii', 'utf8', 'utf16le', 'ucs2', 'latin1', و 'binary'.

ستستخدم عملية إعادة الترميز أحرف بديلة إذا تعذر تمثيل تسلسل بايت معين بشكل كافٍ في ترميز الهدف. على سبيل المثال:

ESM

import { Buffer, transcode } from 'node:buffer'

const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii')
console.log(newBuf.toString('ascii'))
// يُطبع: '?'

CJS

const { Buffer, transcode } = require('node:buffer')

const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii')
console.log(newBuf.toString('ascii'))
// يُطبع: '?'

بما أن رمز اليورو (€) غير قابل للتمثيل في US-ASCII، فإنه يتم استبداله بـ ? في Buffer المُعاد ترميزه.

الصف: SlowBuffer

مُعطّل منذ الإصدار: v6.0.0

[مستقر: 0 - مُعطّل]

مستقر: 0 ثبات: 0 - مُعطّل: استخدم Buffer.allocUnsafeSlow() بدلاً من ذلك.

راجع Buffer.allocUnsafeSlow(). لم يكن هذا أبداً صفاً بالمعنى الذي يُعيد فيه المُنشئ دائماً مثيل Buffer، بدلاً من مثيل SlowBuffer.

new SlowBuffer(size)

مُعطّل منذ الإصدار: v6.0.0

[مستقر: 0 - مُعطّل]

مستقر: 0 ثبات: 0 - مُعطّل: استخدم Buffer.allocUnsafeSlow() بدلاً من ذلك.

• size <عدد صحيح> الطول المطلوب لـ SlowBuffer الجديد.

راجع Buffer.allocUnsafeSlow().

ثوابت بايت

مضاف في الإصدار: v8.2.0

buffer.constants.MAX_LENGTH

[السجل]

الإصدار	التغييرات
v22.0.0	تم تغيير القيمة إلى 2 - 1 على أنظمة 64 بت.
v15.0.0	تم تغيير القيمة إلى 2 على أنظمة 64 بت.
v14.0.0	تم تغيير القيمة من 2 - 1 إلى 2 - 1 على أنظمة 64 بت.
v8.2.0	مضاف في الإصدار: v8.2.0

• <عدد صحيح> أكبر حجم مسموح به لمثيل Buffer واحد.

على أنظمة 32 بت، هذه القيمة حاليًا هي 2 - 1 (حوالي 1 جيجابايت).

على أنظمة 64 بت، هذه القيمة حاليًا هي 2 - 1 (حوالي 8 بيتابايت).

تعكس v8::TypedArray::kMaxLength تحت الغطاء.

تتوفر هذه القيمة أيضًا كـ buffer.kMaxLength.

buffer.constants.MAX_STRING_LENGTH

مضاف في الإصدار: v8.2.0

• <عدد صحيح> أقصى طول مسموح به لمثيل string واحد.

يمثل أطول طول يمكن أن يكون له مُؤشِّر سلسلة نصية، مُحسب بوحدات ترميز 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. بينما هذا السلوك متعمد لتحسين الأداء، أظهرت تجربة التطوير أن هناك حاجة إلى تمييز أكثر وضوحًا بين إنشاء Buffer سريع ولكن غير مُهيأ مقابل إنشاء Buffer أبطأ ولكن أكثر أمانًا. منذ Node.js 8.0.0، يُعيد Buffer(num) و new Buffer(num) كائن Buffer بذاكرة مُهيأة.
• تمرير سلسلة نصية، أو مصفوفة، أو Buffer كأول وسيطة يُنسخ بيانات الكائن المُمرر إلى Buffer.
• تمرير ArrayBuffer أو SharedArrayBuffer يُعيد Buffer يشارك الذاكرة المُخصصة مع مُخزن المصفوفة المُعطى.

بسبب اختلاف سلوك new Buffer() بناءً على نوع الوسيطة الأولى، يمكن إدخال مشاكل أمان وموثوقية عن غير قصد في التطبيقات عندما لا يتم إجراء التحقق من صحة الوسائط أو تهيئة Buffer.

على سبيل المثال، إذا استطاع مُهاجم أن يتسبب في استقبال تطبيق لرقم حيث يُتوقع سلسلة نصية، فقد يقوم التطبيق باستدعاء new Buffer(100) بدلاً من new Buffer("100")، مما يؤدي إلى تخصيص مُخزن مؤقت بسعة 100 بايت بدلاً من تخصيص مُخزن مؤقت بسعة 3 بايت مع محتوى "100". هذا ممكن عادةً باستخدام دعوات واجهة برمجة التطبيقات JSON. نظرًا لأن JSON يُميز بين الأنواع العددية وأنواع السلاسل النصية، فإنه يسمح بحقن الأرقام حيث قد يتوقع تطبيق مكتوب بسذاجة ولا يُجري التحقق الكافي من مدخلاته أن يتلقى دائمًا سلسلة نصية. قبل Node.js 8.0.0، قد يحتوي مُخزن المؤقت الذي تبلغ مساحته 100 بايت على بيانات موجودة مسبقًا في الذاكرة، لذلك قد يتم استخدامه لكشف أسرار الذاكرة لمهاجم عن بُعد. منذ Node.js 8.0.0، لا يمكن حدوث كشف الذاكرة لأن البيانات مُعبأة بالأصفار. ومع ذلك، لا تزال هناك هجمات أخرى ممكنة، مثل التسبب في تخصيص مُخازن مؤقتة كبيرة جدًا بواسطة الخادم، مما يؤدي إلى انخفاض الأداء أو التعطل بسبب استنفاد الذاكرة.

لجعل إنشاء مثيلات Buffer أكثر موثوقية وأقل عرضة للأخطاء، تم إهمال الأشكال المختلفة لمنشئ new Buffer() واستبدالها بطرق Buffer.from(), Buffer.alloc(), و Buffer.allocUnsafe() المنفصلة.

يجب على المُطورين ترقية جميع الاستخدامات الحالية لمنشئي new Buffer() إلى أحد واجهات برمجة التطبيقات الجديدة هذه.

• Buffer.from(array) يُعيد كائن Buffer جديدًا يحتوي على نسخة من البايتات المُقدمة.
• Buffer.from(arrayBuffer[, byteOffset[, length]]) يُعيد كائن Buffer جديدًا يشارك نفس الذاكرة المُخصصة مع ArrayBuffer المُعطى.
• Buffer.from(buffer) يُعيد كائن Buffer جديدًا يحتوي على نسخة من محتويات Buffer المُعطى.
• Buffer.from(string[, encoding]) يُعيد كائن Buffer جديدًا يحتوي على نسخة من السلسلة النصية المُقدمة.
• Buffer.alloc(size[, fill[, encoding]]) يُعيد كائن Buffer مُهيأ جديدًا بالحجم المُحدد. هذه الطريقة أبطأ من Buffer.allocUnsafe(size) ولكنها تضمن أن مثيلات Buffer المُنشأة حديثًا لا تحتوي أبدًا على بيانات قديمة قد تكون حساسة. سيتم طرح TypeError إذا لم يكن size رقمًا.
• Buffer.allocUnsafe(size) و Buffer.allocUnsafeSlow(size) يُعيد كل منهما كائن Buffer غير مُهيأ جديدًا بالحجم المُحدد size. نظرًا لأن Buffer غير مُهيأ، فقد يحتوي الجزء المُخصص من الذاكرة على بيانات قديمة قد تكون حساسة.

قد يتم تخصيص مثيلات Buffer المُعادَة بواسطة Buffer.allocUnsafe()، Buffer.from(string)، Buffer.concat() و Buffer.from(array) من تجمع ذاكرة داخلي مُشارك إذا كان size أقل من أو يساوي نصف Buffer.poolSize. مثيلات المُعادَة بواسطة Buffer.allocUnsafeSlow() لا تستخدم أبدًا تجمع الذاكرة الداخلية المُشارك.

خيار سطر الأوامر --zero-fill-buffers

تمت الإضافة في: v5.10.0

يمكن تشغيل Node.js باستخدام خيار سطر الأوامر --zero-fill-buffers لتسبب في ملء جميع مثيلات Buffer المُخصصة حديثًا بصفر افتراضيًا عند إنشائها. بدون هذا الخيار، لا يتم ملء المخازن المؤقتة التي تم إنشاؤها باستخدام Buffer.allocUnsafe()، وBuffer.allocUnsafeSlow()، وnew SlowBuffer(size) بصفر. قد يكون لاستخدام هذا العلم تأثير سلبي يمكن قياسه على الأداء. استخدم خيار --zero-fill-buffers فقط عند الضرورة لفرض عدم احتواء مثيلات Buffer المُخصصة حديثًا على بيانات قديمة قد تكون حساسة.

$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
<Buffer 00 00 00 00 00>

ما الذي يجعل Buffer.allocUnsafe() و Buffer.allocUnsafeSlow() "غير آمنين"؟

عند استدعاء Buffer.allocUnsafe() و Buffer.allocUnsafeSlow()، فإن جزء الذاكرة المُخصصة يكون غير مُهيأ (لم يتم تعيينه إلى صفر). بينما يجعل هذا التصميم تخصيص الذاكرة سريعًا جدًا، إلا أن جزء الذاكرة المُخصصة قد يحتوي على بيانات قديمة قد تكون حساسة. قد يؤدي استخدام Buffer تم إنشاؤه بواسطة Buffer.allocUnsafe() دون الكتابة الكاملة فوق الذاكرة إلى تسريب هذه البيانات القديمة عند قراءة ذاكرة Buffer.

في حين أن هناك مزايا أداء واضحة لاستخدام Buffer.allocUnsafe()، يجب توخي الحذر الشديد لتجنب إدخال ثغرات أمنية في التطبيق.