الصنف ‎‎‎Buffer‎ في Node.js

من موسوعة حسوب
< Node.js
مراجعة 11:16، 23 أكتوبر 2018 بواسطة عبد اللطيف ايمش (نقاش | مساهمات) (استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}')
(فرق) → مراجعة أقدم | المراجعة الحالية (فرق) | مراجعة أحدث ← (فرق)
اذهب إلى التنقل اذهب إلى البحث

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

قبل تعريف نوع الكائن TypedArray، لم يكن لدى JavaScript أيَّة آلية لقراءة وتعديل مجاري البيانات الثنائية (binary data streams). أُنشِئ الصنف Buffer ليكون جزءًا من واجهة Node.js البرمجيَّة من أجل التعامل مع المجاري الثمانيَّة (octet streams) في مجاري TCP، وعمليات أنظمة الملفات، وسياقاتٍ الأخرى.

لمَّا أوجد الكائن TypedArray، أصبح الصنف Buffer يُنفِّذ الواجهة البرمجية Uint8Array بطريقة أكثر كفاءةً وملائمةً مع Node.js.

النسخ المنشأة من الصنف Buffer مشابهة لمصفوفات الأعداد الصحيحة ولكن متوافقة مع حجم الذاكرة الخام الثابتة والمحجوزة خارج الكومة V8 (heap)‎. يُحدَّد حجم النسخة Buffer عند إنشائها ولا يمكن تغييرها بعد ذلك.

يقع الصنف Buffer ضمن النطاق العام (global scope)، لذا ليس هنالك حاجةٌ لاستعمال require('buffer').Buffer.

// وإسناد جزء من الذاكرة المؤقتة إليه بطول 10 وملئه بالأصفار Buffer إنشاء الكائن
const buf1 = Buffer.alloc(10);

// فيه ‎0x1 وإسناد جزء من الذاكرة المؤقتة إليه بطول 10 ووضع القيمة Buffer‎ إنشاء الكائن
const buf2 = Buffer.alloc(10, 1);

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

// فيه ‎[0x1, 0x2, 0x3] وحجز جزء من الذاكرة ووضع القيمة Buffer إنشاء الكائن
const buf4 = Buffer.from([1, 2, 3]);

// ‎[0x74, 0xc3, 0xa9, 0x73, 0x74] وحجز جزء من الذاكرة ووضع البايتات Buffer إنشاء الكائن
// UTF-8 فيه وفقًا للترميز
const buf5 = Buffer.from('tést');

// ‎[0x74, 0xe9, 0x73, 0x74] وحجز جزء من الذاكرة ووضع البايتات Buffer إنشاء الكائن
// Latin-1 فيه وفقًا لترميز المحارف اللاتينية
const buf6 = Buffer.from('tést', 'latin1');

التابع Buffer.from()‎، والتابع Buffer.alloc()‎، والتابع Buffer.allocUnsafe()‎

في إصدارات Node.js ما قبل 6.0.0، تُنشَئ النسخ Buffer باستعمال دالة بانية تحجز جزءًا من الذاكرة للنسخة Buffer المعادة بطريقة تعتمد على الوسائط المُمرَّرة إليها وهي:

  • تمرير عدد كوسيط أول إلى الدالة Buffer()‎ (مثل new Buffer(10)‎) يحجز جزءًا من الذاكرة المؤقتة بالحجم المعطى ويُسنَد إلى كائن Buffer جديد. قبل الإصدار Node.js 8.0.0، لا يهيئ جزء الذاكرة المحجوز لبعض نسخ Buffer ويمكن بذلك أن يحتوي على بيانات قديمة حسَّاسة. في هذه الحالة، يجب تهيئة جزء الذاكرة المحجوز إمَّا عبر استعمال buf.fill(0)‎ لملء كامل الجزء المحجوز بأصفارٍ، أو عبر كتابة بيانات معيَّنة على كامل هذا الجزء. لمَّا كان عدم تهيئة الجزء المحجوز سلوكًا متعمدًا يحسِّن الأداء، فقد أظهرت تجربة التطوير (development experience) أنَّه ينبغي التفريق بشكل واضح بين إنشاء كائن Buffer دون تهيئته ولكن بسرعة مقابل إنشاء كائن Buffer آمن ولكن ببطء. بدءًا من الإصدار Node.js 8.0.0، يعيد استعمال الدالة بالشكل Buffer(num)‎ و new Buffer(num)‎ كائن Buffer مع تهيئة جزء الذاكرة المحجوز.
  • تمرير سلسلة نصية، أو مصفوفة، أو كائن Buffer كوسيط أول إلى الدالة Buffer()‎ يؤدي إلى إنشاء كائن Buffer ونسخ بيانات ذلك الكائن المُمرَّر إليه.
  • تمرير الكائن ArrayBuffer أو الكائن SharedArrayBuffer إلى الدالة Buffer()‎ يعيد كائن Buffer يتشارك جزءًا من الذاكرة المؤقتة المحجوزة مع ذلك الكائن المعطى.

لمَّا كان سلوك الدالة بالشكل new Buffer()‎ يختلف تبعًا لنوع الوسيط الأول المُمرَّر إليها، فمن الممكن أن تتعرض التطبيقات عن غير قصد لمشكلات متعلقة بالأمن والوثوقيَّة عندما لا يُتحقَّق من صحة الوسيط الأول أو لا يهيأ جزء الذاكرة المحجوز.

لجعل عمليَّة إنشاء نسخٍ من الصنف Buffer أكثر وثوقيَّة وأقل عرضةً للخطأ، أُهملت عدَّة أشكال من الدالة new Buffer()‎ البانية وحلَّ مكانها توابع مستقلة مثل Buffer.from()‎، و Buffer.alloc()‎، و Buffer.allocUnsafe()‎.

يجب على المطورين أن يتركوا استعمال الدالة new Buffer()‎ البانية كليًّا يجميع أشكالها، وأن ينتقلوا إلى ما يقابلها من الواجهات البرمجيَّة الجديدة التالية:

  • التابع Buffer.from(array)‎: يعيد هذا التابع كائن Buffer جديد يحوي نسخةً من القيمة الثمانية المُمرَّرة إليه.
  • التابع Buffer.from(arrayBuffer[, byteOffset[, length]])‎: يعيد كائن Buffer جديد يشارك الكائن ArrayBuffer المعطى جزءًا من الذاكرة المحجوز الخاص به.
  • التابع Buffer.alloc(size[, fill[, encoding]])‎: يعيد كائن Buffer مع حجز جزء ذي حجم مُحدَّد من الذاكرة المؤقتة وتهيئته. الجدير بالذكر أنَّ هذا التابع أبطأ من التابع Buffer.allocUnsafe(size)‎ ولكنه يضمن أنَّ نُسَخ Buffer المنشأة حديثًا آنذاك لا تحوي أيَّة بيانات قديمة يحتمل أن تكون معلومات حسَّاسة ومهمَّة.
  • التابع Buffer.allocUnsafe(size)‎ والتابع Buffer.allocUnsafeSlow(size)‎: يعيد كلًّا منهما كائن Buffer جديد دون تهيئة الحجم size المحجوز من الذاكرة المؤقتة آنذاك. بناءً على ذلك، قد يحتوي هذا الجزء المحجوز على بيانات قديمة يحتمل أن تكون حسَّاسة.

النسخ Buffer التي يعيدها التابع Buffer.allocUnsafe()‎ قد تكون محجوزة خارج مُجمَّع الذاكرة الداخلي المشترك (shared internal memory pool) إن كانت قيمة الوسيط size أقل أو مساويةً لنصف القيمة Buffer.poolSize. أمَّا النُسخ التي يعيدها التابع Buffer.allocUsafeSlow()‎، فلا تستعمل مجمَّع الذاكرة الداخلية المشتركة مطلقًا.

الخيار ‎--zero-fill-buffers في سطر الأوامر

أضيف في الإصدار v5.10.0.

يمكن أن تبدأ Node.js باستعمال الخيار ‎--zero-fill-buffers في سطر الأوامر لإضافة أصفارٍ إلى الجزء الذي تحجزه نسخ Buffer الجديدة من الذاكرة المؤقتة عند إنشائها باستعمال new Buffer(size)‎، و Buffer.allocUnsafe()‎، و Buffer.allocUnsafeSlow()‎، و new SlowBuffer(size)‎ ...إلخ. يؤثِّر استعمال هذه الراية سلبًا على الأداء بدرجة كبيرة ولا ينصح باستعماله إلا في الحالات الضرورية التي لا يراد فيها أن تحتوي نسخ 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()‎ والتابع Buffer.allocUnsafeSlow()‎ له ميزة كبيرة في تحسين الأداء إلا أنَّه يجب أخذ المزيد من الحيطة والحذر لتجنب وجود ثغرات تؤثِّر على الحماية.

ترميز المحارف

سجل التغييرات
الإصدار التغييرات
v6.4.0 أصبح الترميز latin1 اسمًا بديلًا للترميز binary.
v5.0.0 إزالة الترميز raw والترميز raws اللذان كانا مهملين.

يمكن تحديد ترميز المحارف المراد استعماله عند تخزين أو جلب سلسلة نصية من البيانات من النسخة Buffer.

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

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

console.log(Buffer.from('fhqwhgads', 'ascii'));
// <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 حاليًا هي:

  • 'ascii': ترمَّز المحارف باستعمال الترميز ASCII الذي يكون فيه حجم المحرف 7 بت فقط. يَقتطِع هذا الترميز البت الثامن الأكثر أهميَّة (MSB) من كامل البايت، ويوصف بسرعته الكبيرة.
  • 'utf8': ترمَّز المحارف باستعمال الترميز الموحَّد (Unicode) للمحارف متعدِّدة البايتات، وتستعمله أغلب صفحات الويب والمستندات.
  • 'utf16le': ترمَّز المحارف باستعمال الترميز الموحد بحجم 2 أو 4 بايت مع ضبط ترتيب تخزين البايتات الأكثر أهميَّة أولًا (little-endian). الأزواج البديلة (من U+10000 إلى U+10FFFF) مدعومةٌ أيضًا.
  • 'ucs2': هو اسمٌ بديلٌ للترميز 'utf16le'.
  • 'base64': ترمَّز المحارف باستعمال الترميز Base64. عند إنشاء نسخة Buffer من سلسلة نصية، فسيَقبل هذا الترميز بشكل صحيح «الأبجدية الآمنة لعناوين URL وأسماء الملفات» كما هو مذكورٌ في المعيار RFC4648 في القسم الخامس.
  • 'latin1': ترمَّز البيانات إلى سلسلة نصية مرمَّزة ببايت واحد (one-byte encoded string) كما حدَّدته IANA في المعيار RFC1346 في الصفحة 63 ليكون كتلةً ملحقة بالترميز Latin-1 وشيفرات التحكم C0/C1.
  • 'binary': اسمٌ بديلٌ للترميز 'latin1'.
  • 'hex': يرمَّز كلُّ بايت بمحرفين ست عشريين.

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

الصنف Buffer والكائن TypedArray

سجل التغييرات
الإصدار التغييرات
v3.0.0 أصبح الصنف Buffer يرث من الكائن Uint8Array.

النسخ Buffer هي أيضًا نسخ Uint8Array. مع ذلك، هنالك مشكلات غامضة متعلقة بالتوافقيَّة مع الكائن TypedArray. على سبيل المثال، ينشئ التابع ArrayBuffer.slice()‎ كائن ArrayBuffer جديد يحوي نسخةً من الجزء المحدَّد من البيانات، بينما يعيد تنفيذ التابع نفسه بالشكل Buffer.slice()‎ مرجعًا يشير إلى الجزء المحدَّد من البيانات للنسخة Buffer الموجودة ولا ينسخها. بناءً على ذلك، يكون استعمال Buffer.slice()‎ أكثر كفاءةً.

من الممكن أيضًا إنشاء نُسَخ TypedArray جديدة من الكائن Buffer مع الانتباه إلى الأمرين التاليين:

  1. تُنسَخ محتويات ذاكرة الكائن Buffer إلى الكائن TypedArray ولا تُشارَك معه.
  2. تُفسَّر ذاكرة الكائن Buffer على أنَّها مصفوفة من عناصر مختلفة وليست مصفوفة من البايتات من النوع المستهدف. نتيجةً لذلك، نجد أنَّ new Uint32Array(Buffer.from([1, 2, 3, 4]))‎ ينشئ أربعة عناصر من النسخة Uint32Array هي [1, 2, 3, 4] وليس نسخة من العنصر الوحيد [0x1020304] أو [0x4030201].

يمكن أيضًا إنشاء نسخة Buffer جديدة تتشارك جزء الذاكرة الحجوز نفسه كنسخة TypedArray عبر استعمال الخاصِّيَّة ‎.buffer للكائن TypeArray.

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 من الذاكرة المراد مشاركته فقط بالشكل التالي:

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 والتكرار (iteration)

يمكن وضع النسخ Buffer في حلقة تكراريَّة عبر استعمال الصيغة for..of:

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

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

أضف إلى ذلك أنَّ التوابع buf.values()‎، و buf.keys()‎، و buf.entries()‎ يمكن استعمالها لإنشاء مكرارات (iterators).

الصنف Buffer

الصنف Buffer هو نوعٌ عامٌّ يُستعمَل للتعامل مع البيانات الثنائيَّة بشكل مباشر، ويمكن إنشاؤه بطرائق عدَّة سنذكرها جميعها.

Buffer(array)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 أصبح استدعاء هذه الدالة البانية ضمن شيفرة تقع خارج المجلد node_modules يُصدِر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.2.1 استدعاء هذه الدالة البانية لم يعد يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.0.0 أصبح استدعاء هذه الدالة البانية يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v6.0.0 أهملت هذه الدالة.

الاستقرار: 0-مهمل: استعمل التابع Buffer.from(array)‎ عوضًا عن هذه الدالة.

  • array: ‏integer[]>‎> مصفوفةٌ من البايتات المراد نسخها.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز جزءًا من ذاكرة التخزين المؤقت تضع فيه نسخةً من محتويات المعامل array المعطى.

// UTF-8 بترميز 'buffer' جديدة تحتوي على بايتات السلسلة النصية Buffer إنشاء نسخة
const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);

Buffer(arrayBuffer[, byteOffset[, length]])‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 أصبح استدعاء هذه الدالة البانية ضمن شيفرة تقع خارج المجلد node_modules يُصدِر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.2.1 استدعاء هذه الدالة البانية لم يعد يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.0.0 أصبح استدعاء هذه الدالة البانية يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v6.0.0 إضافة المعاملان byteOffset و length.
v6.0.0 أهملت هذه الدالة.
v3.0.0 أضيفت هذه الدالة.

الاستقرار: 0-مهمل: استعمل التابع Buffer.from(arrayBuffer[, byteOffset[, length]])‎ عوضًا عن هذه الدالة.

  • arrayBuffer: ‏<ArrayBuffer> | <SharedArrayBuffer> كائنٌ من النوع ArrayBuffer أو من النوع SharedArrayBuffer أو الخاصِّيَّة ‎.buffer للكائن TypedBuffer.
  • byteOffset: ‏<integer> فهرس البايت الأول الذي سيبدأ عنده مشاركة جزءٍ من الذاكرة. القيمة الافتراضية هي: 0.
  • length: ‏<integer> عدد بايتات الذاكرة المراد مشاركتها. القيمة الافتراضيَّة هي: arrayBuffer.length - byteOffset.

تنشئ هذه الدالة نسخة Buffer جديدة وتتشارك جزء الذاكرة الخاص بالكائن ArrayBuffer أو SharedArrayBuffer دون نسخ ما يحتويه. عندما نُمرِّر مثلًا مرجعًا للخاصِّيَّة ‎.buffer في النسخة TypedArray، فستتشارك النسخة Buffer الجديدة المنشأة آنذاك مع نفس الذاكرة المحجوزة من طرف TypedArray.

إن مُرِّر المعاملان byteOffset و length الاختياريان، فسيُحدِّدان مجالًا من الذاكرة ضمن arrayBuffer تريد النسخة Buffer مشاركته فقط.

const arr = new Uint16Array(2);

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

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

console.log(buf);
// <Buffer 88 13 a0 0f> :سيطبع
 
// أيضًا Buffer الأصلي يؤدي إلى تغيير Uint16Array تغيير
arr[1] = 6000;

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

Buffer(buffer)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 أصبح استدعاء هذه الدالة البانية ضمن شيفرة تقع خارج المجلد node_modules يُصدِر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.2.1 استدعاء هذه الدالة البانية لم يعد يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.0.0 أصبح استدعاء هذه الدالة البانية يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v6.0.0 أهملت هذه الدالة.

الاستقرار: 0-مهمل: استعمل Buffer.from(buffer)‎ عوضًا عن هذه الدالة.

  • buffer: ‏<Buffer> | <Uint8Array> نسخةٌ من Buffer أو Unit8Array يراد نسخ البيانات منها.

تنشئ هذه الدالة نسخة Buffer جديدة وتضع فيها نسخةً من محتوى المعامل buffer المعطى.

const buf1 = new Buffer('buffer');
const buf2 = new Buffer(buf1);

buf1[0] = 0x61;

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

Buffer(size)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 أصبح استدعاء هذه الدالة البانية ضمن شيفرة تقع خارج المجلد node_modules يُصدِر تحذيرًا بأنَّ هذه الدالة مهملة.
v8.0.0 ستهيئ new Buffer(size)‎ جزء الذاكرة الذي تحجزه دومًا وتضع فيه أصفارًا.
v7.2.1 استدعاء هذه الدالة البانية لم يعد يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.0.0 أصبح استدعاء هذه الدالة البانية يُصدِر تحذيرًا بأنََّّ هذه الدالة مهملة.
v6.0.0 أُهملَت هذه الدالة.

الاستقرار: 0-مهمل: استعمل التابع Buffer.alloc()‎ عوضًا عن هذه الدالة (انظر أيضًا التابع Buffer.allocUnsafe()‎).

  • size: ‏<integer> حجم الذاكرة المراد حجزه للنسخة Buffer المنشأة.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز لها جزءًا من الذاكرة بالحجم size المعطى. إن كانت قيمة المعامل size المعطاة أكبر من buffer.constants.MAX_LENGTH أو أصغر من الصفر، فسيرمى الخطأ ERR_INVALID_OPT_VALUE. الجدير بالذكر أنَّه تُنشَأ النسخة Buffer إن أعطيت القيمة 0 للمعامل size.

قبل الإصدار Node.js 8.0.0، لم تكن تهيأ الذاكرة التي يتم حجزها للنسخ Buffer، لذا يكون محتوى النسخة Buffer المنشأة حديثًا آنذاك غير معروف وقد يحوي بيانات حساسة كتبت على تلك الذاكرة مسبقًا. استعمل حينئذ التابع Buffer.alloc(size)‎ الذي يهيئ الذاكرة عبر وضع أصفارٍ فيها.

const buf = new Buffer(10);

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

Buffer(string[, encoding])‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 أصبح استدعاء هذه الدالة البانية ضمن شيفرة تقع خارج المجلد node_modules يُصدِر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.2.1 استدعاء هذه الدالة البانية لم يعد يصدر تحذيرًا بأنَّ هذه الدالة مهملة.
v7.0.0 أصبح استدعاء هذه الدالة البانية يُصدِر تحذيرًا بأنََّّ هذه الدالة مهملة.
v6.0.0 أُهملَت هذه الدالة.

الاستقرار: 0-مهمل: استعمل التابع Buffer.from(string[, encoding])‎ عوضًا عن هذه الدالة.

  • string: ‏<string> السلسلة النصية المراد ترميزها ووضعها في النسخة Buffer المنشأة.
  • encoding: ‏<string> الترميز المراد استعماله مع السلسلة النصية string المعطاة. القيمة الافتراضيَّة هي: 'utf8'.

تنشئ هذه الدالة نسخة Buffer جديدة وتضع فيها السلسلة النصية string المعطاة بعد ترميزها باستعمال الترميز المحدَّد في المعامل encoding.

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

console.log(buf1.toString());
// this is a tést :سيُطبَع
console.log(buf2.toString());
// this is a tést :سيُطبَع
console.log(buf1.toString('ascii'));
// this is a tC)st :سيُطبَع

Buffer.alloc(size[, fill[, encoding]])‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 يرمى استثناء عند محاولة وضع أصفار في الموقع الذي لا يحوي قيمة صفرية من الذاكرة الخاصَّة بالنسخة buffer.
v10.0.0 يرمى استثناء عند إعطاء المعامل fill سلسلة نصية غير صالحة.
v8.9.3 يؤدي إعطاء المعامل fill سلسلة نصية غير صالحة إلى تجاهلها واستعمال القيمة الافتراضية لهذا المعامل.
v5.10.0 أضيف هذا التابع.
  • size: ‏<integer> حجم الذاكرة المراد حجزه للنسخة Buffer المنشأة.
  • fill: ‏‏<string> | ‏<Buffer>‏‏ | ‏<integer>‏ القيمة الأوليَّة للنسخة Buffer الجديدة التي ستُوضع في الذاكرة عند حجزها. القيمة الافتراضيَّة هي: 0.
  • encoding: ‏<string> إن كان المعامل fill سلسلة نصية، فستمثل قيمة هذا المعامل الترميز المستعمل معها. القيمة الافتراضيَّة هي: 'utf8'.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز لها جزءًا من الذاكرة بالحجم size المعطى. إن لم يعطَ المعامل fill أو أعطي وكانت قيمته undefined، فستملأ الذاكرة المحجوزة بأصفار كقيمة أوليَّة.

const buf = Buffer.alloc(5);

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

إن كانت قيمة المعامل size المعطاة أكبر من buffer.constants.MAX_LENGTH أو أصغر من الصفر، فسيرمى الخطأ ERR_INVALID_OPT_VALUE. الجدير بالذكر أنَّه تنشأ النسخة Buffer إن أعطيت القيمة 0 للمعامل size. إن أعطي المعامل fill، فسيهيأ جزء الذاكرة المحجوز عبر استدعاء buf.fill(fill)‎.

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

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

إن أعطي المعاملان fill و encoding كلاهما، فسيُهيَّأ جزء الذاكرة المحجوز عبر استدعاء buf.fill(fill, encoding)‎.

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()‎ المشابه والسبب أنَّ الأول يكتب على الذاكرة التي يحجزها قيمةً محدَّدةً للتأكد من عدم الوصول إلى بيانات موجودة في هذه الذاكرة مسبقًا يحتمل أن تكون حسَّاسة.

سيرمى الخطأ TypeError إن لم يكن المعامل size عددًا.

 Buffer.allocUnsafe(size)

سجل التغييرات
الإصدار التغييرات
v7.0.0 يرمى خطأ الآن عند استعمال قيمة سالبة مع المعامل size.
v5.10.0 أضيف هذا التابع.
  • size: ‏<integer> حجم الذاكرة المراد حجزه للنسخة Buffer المنشأة.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز لها جزءًا من الذاكرة بالحجم size المعطى. إن كانت قيمة المعامل size المعطاة أكبر من buffer.constants.MAX_LENGTH أو أصغر من الصفر، فسيرمى الخطأ ERR_INVALID_OPT_VALUE. الجدير بالذكر أنَّه تنشأ النسخة Buffer إن أعطيت القيمة 0 للمعامل size.

انتبه إلى أنَّ هذا التابع لا يهيئ الذاكرة التي يحجزها عند استعماله لإنشاء نسخٍ من Buffer. نتيجةً لذلك، لا يُعرَف المحتوى الأولي للنسخة Buffer المنشأة آنذاك وقد يكون بيانات حساسة كتبت على تلك الذاكرة مسبقًا. إن أردت تهيئة جزء الذاكرة المحجوز ووضع قيمة أولية معروفة فيه، فاستعمل التابع Buffer.alloc()‎.

const buf = Buffer.allocUnsafe(10);

console.log(buf);
// (contents may vary): <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()‎ والدالة new Buffer(size)‎ المهملة أيضًا شرط أن تكون قيمة size أصغر أو تساوي القيمة Buffer.poolSize >> 1 (ناتج قسمة Buffer.poolSize على 2 بعد تقريبه إلى أقرب عدد صحيح).

استعمال هذا الحجز الداخلي المسبق لكتلة (pool) من الذاكرة هو جوهر الاختلاف بين الاستدعاء Buffer.alloc(size, fill)‎ والاستدعاء Buffer.allocUnsafe(size).fill(fill)‎. بناءً على ذلك، نجد أنَّ Buffer.alloc(size, fill)‎ لا يستخدم هذه الكتلة من الذاكرة المحجوزة مسبقًا بينما يستعملها التابع Buffer.allocUnsafe(size).fill(fill)‎ إن كانت قيمة size أصغر أو تساوي نصف القيمة Buffer.poolSize. قد يكون الفرق غامضًا بعض الشيء إلا أنَّه يلعب دورًا مهمًا في تسريع الأداء الذي يستطيع Buffer.allocUnsafe()‎ أن يوفِّره خصوصًا عندما يتطلب التطبيق ذلك.

Buffer.allocUnsafeSlow(size)‎

أضيف في الإصدار v5.12.0.

  • size: ‏<integer> حجم الذاكرة المراد حجزه للنسخة Buffer المنشأة.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز لها من الذاكرة الحجم size المعطى. إن كانت قيمة المعامل size المعطاة أكبر من buffer.constants.MAX_LENGTH أو أصغر من الصفر، فسيرمى الخطأ ERR_INVALID_OPT_VALUE. الجدير بالذكر أنَّه تنشأ النسخة Buffer إن أعطيت القيمة 0 للمعامل size.

انتبه إلى أنَّ هذا التابع لا يهيئ الذاكرة التي يحجزها عند استعماله لإنشاء نسخٍ من Buffer. نتيجةً لذلك، لا يُعرف المحتوى الأولي للنسخة Buffer المنشأة آنذاك وقد يكون بعض البيانات الحسَّاسة التي كتبت على تلك الذاكرة مسبقًا. إن أردت تهيئة جزء الذاكرة المحجوز ووضع قيمة أولية معروفة فيه، فاستعمل التابع buf.fill()‎.

عند استعمال Buffer.allocUnsafe()‎ لإنشاء نسخٍ جديدة من Buffer، فستُقتَطَع حجوزات الذاكرة التي تقل عن 4 كيلوبايت من نسخة Buffer واحدة محجوزة مسبقًا (التي شُرحت آنفًا). هذا يساعد التطبيقات على تجنب زيادة مجمَّع المهملات (garbage allocation) عبر تقليل إنشاء نسخ Buffer جديدة وحجز أجزاء من الذاكرة بشكل فردي. يحسِّن ذلك الأداء واستخدام الذاكرة عبر تقليل الحاجة إلى تتبُّع وإزالة أقل قدر ممكن من الكائنات الموجودة والمتكررة.

مع ذلك، في حال احتاج المطور إلى الاحتفاظ يجزءٍ صغيرٍ من الذاكرة يقع في المجمع (pool) المحجوز مسبقًا لفترة زمنية غير معلومة، فيُستحسن إنشاء نسخة Buffer بحجز جزء آخر من الذاكر يقع خارج مجمع الذاكرة المحجوز مسبقًا (un-pooled) عبر استعمال Buffer.allocUnsafeSlow()‎ ثمَّ نسخ البيانات التي تريد الاحتفاظ بها.

// الحاجة إلى الاحتفاظ ببعض أجزاء الذاكرة
const store = [];

socket.on('readable', () => {
  const data = socket.read();

  // حجز جزء من الذاكرة خاص بالبيانات المراد الاحتفاظ بها
  const sb = Buffer.allocUnsafeSlow(10);

  // نسخ البيانات إلى موقع جديد
  data.copy(sb, 0, 0, 10);

  store.push(sb);
});

يجب عدم اللجوء إلى استعمال التابع Buffer.allocUnsafeSlow()‎ إلا في نهاية المطاف بعد أن يلاحظ المطور نفسه أنه احتفظ بأجزاء من الذاكرة لا حاجة له فيها في تطبيقه.

سيرمى الخطأ TypeError إن لم يكن المعامل size عددًا.

Buffer.byteLength(string[, encoding])‎

سجل التغييرات
الإصدار التغييرات
v7.0.0 يرمى خطأ الآن عند تمرير قيم غير صحيحة.
v5.10.0 يمكن أن يكون المعامل string أحد الكائنات TypedArray أو DataView أو ArrayBuffer.
v0.1.90 أضيف هذا التابع.
  • string: ‏<string>‏‏ | <Buffer>‏ | ‏‏<TypedArray>‏ | ‏<DataView> | ‏<ArrayBuffer> | ‏<SharedArrayBuffer‏>‏ القيمة المراد حساب طولها (عدد بايتاتها).
  • encoding: ‏<string> إن كان المعامل string سلسلة نصية، فسيمثَّل هذا المعامل الترميز الذي سيُستعمَل معها. القيمة الافتراضيَّة هي: 'utf8'.
  • القيم المعادة: <integer> يعاد عدد بايتات المعامل string المعطى.

يعيد هذا التابع عدد البايتات الحقيقي للسلسلة النصية المُمرَّرة إليه. لا يشبه هذا التابع الخاصِّيَّة String.prototype.length التي تعيد عدد المحارف الموجودة في السلسلة النصية وليس عدد البايتات.

عند استعمال الترميز 'base64' والترميز 'hex'، يَفترض هذا التابع أنَّ جميع المدخلات صالحة. أمَّا عند إعطاء سلاسل نصية تحتوي على بيانات غير مرمَّزة بالترميز Base64 أو Hex (مثل المسافات البيضاء)، فقد تكون القيمة المعادة أكبر من طول النسخة 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، أو SharedArrayBuffe، فسيُعاد عدد البيانات الفعلي لهذا المعامل.

Buffer.compare(buf1, buf2)

سجل التغييرات
الإصدار التغييرات
v8.0.0 أصبح بالإمكان استعمال الكائن Uint8Array مع المعاملين المُمرَّرين إلى التابع.
v0.11.13 أضيف هذا التابع.
  • buf1: ‏<Buffer> | <Uint8Array> القيمة الأولى المراد موازتنها مع قيمة ثانية.
  • buf2: ‏<Buffer> | <Uint8Array> القيمة الثانية المراد موازتنها مع القيمة الأولى.

يوازن هذا التابع بين المعاملين buf1 و buf2 المُمرَّرين إليه ثمَّ يعيد عددًا صحيحًا، إذ يستعمل عادةً بغرض ترتيب المصفوفات في النسخ Buffer. عمل هذا التابع مشابهٌ تمامًا للاستدعاء buf1.compare(buf2).

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

console.log(arr.sort(Buffer.compare));
// Prints: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// ([buf2, buf1] هذه النتيجة مساوية إلى)

Buffer.concat(list[, totalLength])‎

سجل التغييرات
الإصدار التغييرات
v8.0.0 أصبح بالإمكان استعمال الكائن Uint8Array مع المعامل list المُمرَّر إلى التابع.
v0.7.11 أضيف هذا التابع.
  • list: ‏<Buffer[]> | <Uint8Array> قائمةٌ من النسخ Buffer أو Uint8Array المراد دمجها مع بعضها بعضًا.
  • totalLength:‏ <integer> الطول الكلي للنسخ Buffer أو Uint8Array المراد دمجها.

يدمج هذا التابع جميع النسخ Buffer أو Uint8Array المُحدَّدة في المعامل list مع بعضها بعضها ووفقًا للطول totalLength المعطى ثمَّ ينشئ نسخة Buffer جديدة يضع الناتج فيها ويعيدها.

إن لم يحوي المعامل list أيَّ عنصر أو كانت قيمة المعامل totalLength المعطاة 0، فستعاد نسخة Buffer جديدة بطول 0.

إن لم يعطَ المعامل totalLength، فسيحسب من النسخ Buffer الموجودة في المعامل list. هذا الأمر سيُقلِّل من الأداء، إذ ستزيد العمليات المنفَّذة لحساب الطول الكلي totalLength المراد دمجه. بناءً على ذلك، يُفضَّل حساب قيمة totalLength ثمَّ تمريرها إلى التابع إن كان بالإمكان.

إن أعطيت قيمة المعامل totalLength، فسيُحوَّل إلى عدد صحيح عديم الإشارة (unsigned integer). إن زاد طول النُسَخ المعطاة في المعامل list المراد دمجها عن القيمة totalLength المعطاة، فستُقتَطَع نتيجة دمج جميع تلك النسخ لتصبح مساوية للطول totalLength.

// في نسخة واحدة 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.from(array)‎

أضيف في الإصدار v5.10.0.

  • array: ‏<integer[]‎> مصفوفةٌ من البايتات المراد نسخها.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز جزءًا من ذاكرة التخزين المؤقت تضع فيه نسخةً من محتويات المعامل array.

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

سيرمى الخطأ TypeError إن لم يكن المعامل array مصفوفةً.

Buffer.from(arrayBuffer[, byteOffset[, length]])‎

أضيف في الإصدار v5.10.0.

  • arrayBuffer: ‏<ArrayBuffer> | <SharedArrayBuffer> كائنٌ من النوع ArrayBuffer أو من النوع SharedArrayBuffer أو الخاصِّيَّة ‎.buffer للكائن TypedBuffer.
  • byteOffset: ‏<integer> فهرس البايت الأول الذي سيبدأ عنده مشاركة جزءٍ من الذاكرة. القيمة الافتراضيَّة هي: 0.
  • length: ‏<integer> عدد بايتات الذاكرة المراد مشاركتها. القيمة الافتراضيَّة هي: arrayBuffer.length - byteOffset.

تنشئ هذه الدالة نسخة Buffer جديدة وتتشارك جزء الذاكرة الخاص بالكائن ArrayBuffer أو SharedArrayBuffer دون نسخ ما تحتويها. عندما نُمرِّر مثلًا مرجعًا للخاصِّيَّة ‎.buffer في النسخة TypedArray، ستتشارك النسخة Buffer الجديدة المنشأة آنذاك مع نفس الذاكرة المحجوزة من طرف TypedArray.

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> :سيُطبع

// Changing the original Uint16Array changes the Buffer also
arr[1] = 6000;

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

إن مُرِّر المعاملان byteOffset و length الاختياريان، فسيُحدِّدان مجالًا من الذاكرة ضمن arrayBuffer تريد النسخة Buffer مشاركته فقط.

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

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

سيرمى الخطأ TypeError إن لم يكن المعامل arrayBuffer كائنًا من النوع ArrayBuffer أو  SharedArrayBuffer.

Buffer.from(buffer)‎

أضيف في الإصدار v5.10.0.

  • buffer: ‏<Buffer> | <Uint8Array> نسخةٌ من Buffer أو Unit8Array يراد نسخ البيانات منها.

تنشئ هذه الدالة نسخة Buffer جديدة وتضع فيها نسخةً من محتوى المعامل 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 أو Uint8Array يراد نسخ البيانات منها.

Buffer.from(string[, encoding])‎

أضيف في الإصدار v5.10.0.

  • string: ‏<string> السلسلة النصية المراد ترميزها ووضعها في النسخة Buffer المنشأة.
  • encoding: ‏‏<string> الترميز المراد استعماله مع السلسلة النصية string المعطاة. القيمة الافتراضيَّة هي: 'utf8'.

تنشئ هذه الدالة نسخة Buffer جديدة وتضع فيها السلسلة النصية string المعطاة بعد ترميزها باستعمال الترميز المحدَّد في المعامل encoding.

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('ascii'));
// this is a tC)st :سيُطبع

سيرمى الخطأ TypeError إن لم يكن المعامل string سلسلة نصية.

Buffer.from(object[, offsetOrEncoding[, length]])‎

أضيف في الإصدار v8.2.0.

  • object: ‏<Object> كائنٌ يدعم Symbol.toPrimitive أو valueOf()‎.
  • offsetOrEncoding: ‏<number> | ‏<string> عدد البايتات التي تمثِّل مقدار الإزاحة أو قيمةٌ تمثِّل الترميز المراد استعماله وهذا يعتمد على القيمة التي يعيدها إمَّا object.valueOf()‎ أو object[Symbol.toPrimitive]()‎.
  • length: ‏<number> عدد البايتات المراد نسخها وتعتمد على القيمة التي يعيدها إمَّا object.valueOf()‎ أو object[Symbol.toPrimitive]()‎.

تستعمل هذه الدالة بالشكل Buffer.from(object.valueOf(), offsetOrEncoding, length)‎ من أجل الكائنات التي تعيد الدالة valueOf()‎ معها قيمةً لا تتساوى بشكل صارم مع قيمة المعامل object.

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>

بينما تستعمل بالشكل Buffer.from(object[Symbol.toPrimitive](), offsetOrEncoding, length)‎ من أجل الكائنات التي تدعم Symbol.toPrimitive.

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>

Buffer.isBuffer(obj)

أضيف في الإصدار v0.1.101.

  • obj: ‏<Object> الكائن المراد التحقُّق منه إن كان من النوع Buffer أم لا.

تعيد هذه الدالة القيمة المنطقيَّة true إن كان الكائن obj المعطى من النوع Buffer، والقيمة المنطقيَّة false إن لم يكن.

Buffer.isEncoding(encoding)‎

أضيف في الإصدار v0.9.1.

  • encoding: ‏<string> اسم الترميز المراد التحقُّق منه.

يعيد هذا التابع القيمة المنطقيَّة true إن كان الترميز encoding المعطى مدعومًا، أو القيمة المنطقيَّة false إن لم يكن.

الخاصية Buffer.poolSize

أضيفت في الإصدار v0.11.3.

تمثِّل هذه الخاصِّيَّة حجم الذاكرة المحجوزة مسبقًا (بالبايت) للنسخ Buffer الداخلية التي تُستعمَل كمُجمِّع (pooling). قيمتها الافتراضيَّة هي 8192، ويمكن تعديلها.

buf[Index]‎

يمكن استعمال معامل الفهرسة [index] لجلب أو تعيين قيمة بايت واحد موجود في الموقع index ضمن buf. بما أنَّ كل قيمة تمثِّل بايتًا واحدًا، فيجب أن تقع بين المجال 0x00 و 0xFF بالنظام الست عشري أو بين 0 و 255 بالنظام العشري.

إنَّ معامل الفهرسة هذا موروثٌ من Uint8Array، لذا سلوكه مماثل تمامًا للسلوك الذي يسلكه في Uint8Array. هذا يعني أنَّ محاولة الوصول إلى قيمة تقع خارج الحدود يعيد القيمة undefined، ومحاولة ضبط تلك القيمة ليس له أي تأثير.

// بايتًا واحدًا في كل مرة Buffer إلى ASCII نسخ سلسلة نصية بترميز

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('ascii'));
// Node.js :سيُطبع

الخاصية buf.buffer

تعيد الكائن ArrayBuffer بناءً على النوع الذي أنشئ الكائن Buffer منه.

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

console.log(buffer.buffer === arrayBuffer);
// true :سيُطبع

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

سجل التغييرات
الإصدار التغييرات
v8.0.0 أصبح بالإمكان استعمال الكائن Uint8Array مع المعامل target المُمرَّر إلى التابع.
v5.11.0 أضيفت معاملات جديدة لتحديد مجال معين يراد موازنته فقط.
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.

يوازن هذا التابع بين buf و target ثمَّ يعيد عددًا يحدِّد إن كان buf يأتي قبل Buffer أو بعده أو كان مماثلًا له من ناحية الترتيب. تعتمد عمليَّة الموازنة على سلسلة البايتات الفعليَّة في Buffer. يعيد هذا التابع العدد:

  • 0 إن كان target و buf متماثلان، أو
  • 1 إن كان من المفترض أن يأتي target قبل buf عند ترتيبهما، أو
  • ‎-1 إن كان من المفترض أن يأتي target بعد but عند ترتيبهما.
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.

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

ينسخ هذا التابع بيانات من مجال محدَّد من buf ويلصقها ضمن مجال محدَّد في atrget حتى لو كان مجال الذاكرة المحجوز للكائن target المعطى يتداخل مع buf.

 1 // `Buffer` إنشاء نسختين من
 2 const buf1 = Buffer.allocUnsafe(26);
 3 const buf2 = Buffer.allocUnsafe(26).fill('!');
 4 
 5 for (let i = 0; i < 26; i++) {
 6   // ASCII قيمة المحرف في الجدول 'a' العدد 97 هو
 7   buf1[i] = i + 97;
 8 }
 9 
10 // بدءًا من البايت 8 `buf2` من 16 إلى 19 ولصقها ضمن `buf1` نسخ بايتات
11 buf1.copy(buf2, 8, 16, 20);
12 
13 console.log(buf2.toString('ascii', 0, 25));
14 // !!!!!!!!qrst!!!!!!!!!!!!! :سيُطبع

buf.entries()‎

أضيف في الإصدار v1.1.0.

ينشئ هذا التابع مُكرِّرًا (iterator) للأزواج [index, byte] من محتويات الكائن buf ثمَّ يعيده.

// `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)‎

سجل التغييرات
الإصدار التغييرات
v8.0.0 أصبح بالإمكان استعمال الكائن Uint8Array مع المعامل otherBuffer المُمرَّر إلى التابع.
v0.11.13 أضيف هذا التابع.
  • otherBuffer: ‏<Buffer> | <Uint8Array> نسخةٌ من Buffer أو Uint8Array التي يراد موازنتها مع buf.

يعيد هذا التابع القيمة المنطقيَّة true إن كان buf و otherBuffer متساويين بقيمة البايتات نفسها، أو القيمة المنطقيَّة false خلاف ذلك.

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])‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 أصبح استعمال قيمة سالبة مع المعامل end يرمي الخطأ ERR_INDEX_OUT_OF_RANGE.
v10.0.0 سيرمى استثناءٌ عند محاولة تبديل قيم صفرية مكان القيم غير الصفرية الموجودة في Buffer.
v10.0.0 سيرمى خطأ عند استعمال سلسلة نصية غير صالحة مع المعامل value.
v5.7.0 أضيف المعامل encoding.
v0.5.0 أضيف هذا التابع.
  • value: ‏<string> | ‏<Buffer>‏‏ | ‏<integer>‏ القيمة المراد وضعها في buf.
  • offset: ‏<integer> عدد البايتات المراد تخطيها في buf قبل البدء بملء النسخة buf بقيمة المعامل value. القيمة الافتراضيَّة هي: 0.
  • end: ‏<integer> عددٌ يمثِّل البايت الذي ستتوقف عنده عملية ملء النسخة buf بقيمة المعامل value (لا يدخل هذا البايت ضمن المجال). القيمة الافتراضيَّة هي: 0.
  • encoding: ‏<string> الترميز المراد استعمال مع المعامل value إن كان سلسلةً نصيةً. القيمة الافتراضيَّة هي: 'utf8'.

يملأ هذا التابع النسخة buf بالقيمة value المعطاة.  إن لم يعطَ المعامل offset أو end أو كلاهما، فستملأ كامل ذاكرة buf بالقيمة value المعطاة:

// ‘h’ بالمحرف Buffer ملء

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

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

ستُحوَّل القيمة value إلى النوع uint32 إن لم تكن سلسلةً نصيةً أو عددًا صحيحًا. عند كتابة محارف متعدِّدة البايتات ووصول التابع fill()‎ إلى عمليَّة الكتابة الأخيرة ولم يعد هنالك حجم كافٍ لكتابة محرف كامل، فستٌكتَب البايتات الأولى من ذلك المحرف التي تتسع في الحجم المتبقي. يشرح المثال التالي هذا الأمر:

// بمحرف يتألف من بايتين `Buffer` ملء

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

إن احتوى المعامل value على محارف غير صالحة، فستُقتطَع وتزال؛ وإن لم يعد هنالك بيانات صالحة لملئها، فسيرمى استثناءٌ.

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> | ‏<integer> القيمة المراد البحث عنها.
  • byteOffset: ‏<integer> عدد البايتات المراد تخطيها في buf قبل البدء بعمليَّة البحث. القيمة الافتراضيَّة هي: 0.
  • encoding: ‏<string> الترميز المراد استعماله مع المعامل value إن كان سلسلةً نصيةً. القيمة الافتراضيَّة هي: 'utf8'.

يبحث هذا التابع عن القيمة value المعطاة ضمن buf، ويعيد القيمة المنطقيَّة true إن عثر عليها أو القيمة المنطقيَّة إن لم تكن value موجودة في buf.

هذا التابع يكافئ  buf.indexOf() !== -1.

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 is the decimal ASCII value for '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])‎

سجل التغييرات
الإصدار التغييرات
v8.0.0 أصبح بالإمكان استعمال الكائن Uint8Array مع المعامل value المُمرَّر إلى التابع.
v5.7.0 - v4.4.0 عندما يُمرَّر المعامل encoding، ليس هنالك حاجة لاستعمال أو تمرير المعامل byteOffset.
v1.5.0 أضيف هذا التابع.
  • value: ‏<string> | ‏<Buffer> | <Uint8Array> | ‏<integer> القيمة المراد البحث عنها.
  • byteOffset: ‏<integer> عدد البايتات المراد تخطيها في buf قبل البدء بعملية البحث. القيمة الافتراضيَّة هي: 0.
  • encoding: ‏<string> إن كان المعامل value المعطى سلسلةً نصيةً، فسيثِّمل هذا المعامل الترميز المراد استعماله لتحديد التمثيل الثنائي لتلك السلسلة النصية الذي سيُبحث عنه في buf. القيمة الافتراضيَّة هي: 'utf8'.

إن كان المعامل value:

  • سلسلةً نصيةً، فسيرمَّز وفقًا للترميز encoding المعطى ثمَّ يبحث عنه.
  • نسخةً من Buffer، أو Uint8Array، فستُسعمَل القيمة value المعطاة بأكملها. إن أردت البحث في جزءٍ محدَّد من Buffer، فاستعمل buf.slice()‎.
  • عددًا، فستعامل القيمة value على أنَّها عددٌ صحيحٌ عديم الإشارة بحجم 8 بت (أي يقع بين 0 و 255).

يعيد هذا التابع عددًا يمثل فهرس البايت الأول للقيمة value لأول ظهور لها في buf، أو القيمة ‎-1 إن لم تكن القيمة value موجودة في buf.

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 (ASCII في الجدول 'a' العدد 97 هو قيمة المحرف)
console.log(buf.indexOf(Buffer.from('a buffer example')));
// Prints: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)));
// Prints: 8

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

console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'));
// Prints: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'));
// Prints: 6

إن يكن المعامل value سلسلةً نصيةً أو عددًا أو نسخةً من Buffer، فسيرمى الخطأ TypeError.

إن كان المعامل value عددًا، فسيحول إلى قيمة بايت صحيح أو إلى عددٍ صحيح يقع في المجال بين 0 و 255.

إن لم يكن المعامل byteOffset عددًا، فسيحول رغمًا عنه إلى عدد. إن حصلنا بعد عمليَّة التحويل هذه على القيمة NaN أو 0، فسيُبحث في buf بأكملها. يطابق هذا السلوك الشكل String.indexOf()‎.

const b = Buffer.from('abcdef');

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

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

إن كان المعامل value سلسلة نصية فارغة أو نسخة Buffer فارغة وكان المعامل byteOffset أقل من buf.length، فسيُعاد حينئذٍ المعامل byteOffset. أمَّا إن كان المعامل byteOffset أكبر أو يساوي buf.length في نفس شروط الحالة السابقة، فسيُعاد حينئذٍ buf.length.

buf.keys()‎

أضيف في الاصدار v1.1.0.

ينشئ هذا التابع مُكررًا (iterator) لمفاتيح (أو فهارس) الكائن buf ثمَّ يعيده.

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

سجل التغييرات
الإصدار التغييرات
v8.0.0 أصبح بالإمكان استعمال الكائن Uint8Array مع المعامل value المُمرَّر إلى التابع.
v6.0.0 أضيف هذا التابع.
  • value: ‏<string> | ‏<Buffer> | ‏<Uint8Array> | ‏<integer>‏ القيمة المراد البحث عنها.
  • byteOffset: ‏<integer> عدد البايتات المراد تخطيها في buf قبل البدء بعمليَّة البحث. القيمة الافتراضيَّة هي: buf.length - 1.
  • encoding: ‏<string> إن كان المعامل value المعطى سلسلةً نصيةً، فسيثِّمل هذا المعامل الترميز المراد استعماله لتحديد التمثيل الثنائي لتلك السلسلة النصية الذي سيُبحث عنه في buf. القيمة الافتراضية هي: 'utf8'.

يعيد هذا التابع عددًا يمثِّل فهرس البايت الأول للقيمة value لآخر ظهور لها في buf، أو القيمة ‎-1 إن لم تكن القيمة value موجودة في buf. هذا التابع مماثل تمامًا للتابع buf.indexOf()‎ باستثناء أنَّه يبحث عن آخر ظهور للقيمة value عوضًا عن أول ظهور لها.

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 (ASCII في الجدول 'a' العدد 97 هو قيمة المحرف)
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)، فسيُبحث في buf بأكملها. يطابق هذا السلوك الشكل String.lastIndexOf()‎.

const b = Buffer.from('abcdef');

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

// NaN تحول إلى القيمة byteOffset تمرير قيمة للمعامل
console.log(b.lastIndexOf('b', undefined));
console.log(b.lastIndexOf('b', {}));
// ستُطبع القيمة 1، إذ جرت عمليَّة البحث في كامل المحتوى


// تحول إلى القيمة 0 byteOffset تمرير قيمة للمعامل
console.log(b.lastIndexOf('b', null));
console.log(b.lastIndexOf('b', []));
// ستُطبع القيمة -1، وهذا يكافئ تمرير القيمة 0

إن كان المعامل value سلسلةً نصيةً فارغةً أو نسخة Buffer فارغة، فستُعاد حينئذٍ قيمة المعامل byteOffset.

الخاصية buf.length

أضيف في الاصدار v0.1.90.

تعيد هذه الخاصِّيَّة حجم الذاكرة المحجوز للنسخة buf بواحدة البايت. انتبه إلى أنَّ هذا الحجم لا يمثِّل بالضرورة حجم الذاكرة المستهلكة ضمن buf.

// عليها ASCII ثمَّ كتابة سلسلة نصية بترميز Buffer إنشاء نسخة جديدة

const buf = Buffer.alloc(1234);

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

buf.write('some string', 0, 'ascii');

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

لمَّا كانت الخاصِّيَّة length غير ثابتة، فيمكن أن يؤدي تغيير قيمتها إلى الحصول على سلوك غير مُعرَّف وغير منتظم. يجب على التطبيقات التي ترغب بتعديل حجم نسخةٍ من Buffer أن تعامل الخاصِّيَّة length كقيمة قابلة للقراءة فقط، وأن تستعمل buf.slice()‎ لاقتطاع جزءٍ من Buffer.

let buf = Buffer.allocUnsafe(10);

buf.write('abcdefghj', 0, 'ascii');

console.log(buf.length);
// 10

buf = buf.slice(0, 5);

console.log(buf.length);
// 5

الخاصية buf.parent

أضيف في الإصدار v8.0.0.

الاستقرار: 0-مهمل: استعمل الخاصِّيَّة buf.buffer عوضًا عنها.

هذه الخاصِّيَّة هي اسمٌ بديلٌ مهمل للخاصِّيَّة buf.buffer.

buf.readDoubleBE(offset)‎، و buf.readDoubleLE(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 8.

يقرأ هذا التابع الأعداد العشريَّة المضاعفة (double) ذات الحجم 64 بت من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهميَّة مُخزَّنة أولًا (big endian)، فاستعمل readDoubleBE()‎؛ وإن كانت البتات الأكثر أهميَّة مُخزَّنة أولًا (little endian)، فاستعمل readDoubleLE()‎.

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

console.log(buf.readDoubleBE(0));
// 8.20788039913184e-304
console.log(buf.readDoubleLE(0));
// 5.447603722011605e-270
console.log(buf.readDoubleLE(1));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readFloatBE(offset)‎ و buf.readFloatLE(offset)‎

الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 4.

يقرأ هذا التابع الأعداد العشرية (float) ذات الحجم 32 بت من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهميَّة مُخزَّنة أولًا (big endian)، فاستعمل readFloatBE()‎؛ وإن كانت البتات الأكثر أهمية مُخزَّنة أولًا (little endian)، فاستعمل readFloatLE()‎.

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

console.log(buf.readFloatBE(0));
// Prints: 2.387939260590663e-38
console.log(buf.readFloatLE(0));
// Prints: 1.539989614439558e-36
console.log(buf.readFloatLE(1));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readInt8(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.0 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 1.

يقرأ هذا التابع الأعداد الصحيحة ذات الإشارة (signed integer) التي حجمها 8 بت من buf بدءًا من البايت offset المعطى ثمَّ يعيدها.

تفسَّر الأعداد الصحيحة المقروءة من نسخة Buffer على أنَّها قيمٌ متمِّمة ثنائيًّا (two's complement) وذات إشارة.

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

console.log(buf.readInt8(0));
// Prints: -1
console.log(buf.readInt8(1));
// Prints: 5
console.log(buf.readInt8(2));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readInt16BE(offset)‎ و buf.readInt16LE(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 2.

يقرأ هذا التابع الأعداد الصحيحة ذات الإشارة (signed integer) التي حجمها 16 بت من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهميَّة مُخزَّنة أولًا (big endian)، فاستعمل readInt16BE()‎؛ وإن كانت البتات الأكثر أهمية مُخزَّنة أولًا (little endian)، فاستعمل readInt16LE()‎.

تفسَّر الأعداد الصحيحة المقروءة من نسخة Buffer على أنَّها قيمٌ متمِّمة ثنائيًّا (two's complement) وذات إشارة.

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

console.log(buf.readInt16BE(0));
// Prints: 5
console.log(buf.readInt16LE(0));
// Prints: 1280
console.log(buf.readInt16LE(1));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readInt32BE(offset)‎ و buf.readInt32LE(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 4.

يقرأ هذا التابع الأعداد الصحيحة ذات الإشارة (signed integer) التي حجمها 32 بت من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهمية مُخزَّنة أولًا (big endian)، فاستعمل readInt32BE()‎؛ وإن كانت البتات الأكثر أهمية مُخزَّنة أولًا (little endian)، فاستعمل readInt32LE()‎.

تفسَّر الأعداد الصحيحة المقروءة من نسخة Buffer على أنَّها قيم متمِّمة ثنائيًّا (two's complement) وذات إشارة.

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

console.log(buf.readInt32BE(0));
// Prints: 5
console.log(buf.readInt32LE(0));
// Prints: 83886080
console.log(buf.readInt32LE(1));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readIntBE(offset, byteLength)‎ و buf.readIntLE(offset, byteLength)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حُذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset والمعامل byteLength إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع قيمة هذا المعامل في المجال ‎0 <= offset <= buf.length - byteLength.
  • byteLength: ‏<integer> عدد البايتات المراد قراءتها، ويجب أن تقع بين قيمة هذا المعامل في المجال 0‎ < byteLength <= 6.

يقرأ هذا التابع الأعداد الصحيحة ذات الإشارة (signed integer) التي حجمها هو byteLength المعطى من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهمية مُخزَّنة أولًا (big endian)، فاستعمل readIntBE()‎؛ وإن كانت البتات الأكثر أهمية مُخزَّنة أولًا (little endian)، فاستعمل readIntLE()‎.

تفسَّر الأعداد الصحيحة المقروءة من نسخة Buffer على أنَّها قيم متمِّمة ثنائيًّا (two's complement) وذات إشارة. تدعم هذه الدالة قراءة الأعداد الصحيحة بدقة تصل إلى 48 بت.

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

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

console.log(buf.readIntLE(0, 6).toString(16));
// -546f87a9cbee
console.log(buf.readIntBE(0, 6).toString(16));
// 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16));
// ERR_INDEX_OUT_OF_RANGE يرمى الخطأ
console.log(buf.readIntBE(1, 0).toString(16));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readUInt8(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.0 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع قيمة هذا المعامل في المجال ‎0 <= offset <= buf.length - 1.

يقرأ هذا التابع الأعداد الصحيحة عديمة الإشارة (unsigned integer) ذات الحجم 8 بت من buf بدءًا من البايت offset المعطى ثمَّ يعيدها.

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

console.log(buf.readInt8(0));
// Prints: -1
console.log(buf.readInt8(1));
// Prints: 5
console.log(buf.readInt8(2));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readUInt16BE(offset)‎ و buf.readUInt16LE(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 2.

يقرأ هذا التابع الأعداد الصحيحة عديمة الإشارة (unsigned integer) ذات الحجم 16 بت من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهميَّة مُخزَّنة أولًا (big endian)، فاستعمل readUInt16BE()‎؛ وإن كانت البتات الأكثر أهميَّة مُخزَّنة أولًا (little endian)، فاستعمل readUInt16LE()‎.

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

console.log(buf.readUInt16BE(0).toString(16));
// Prints: 1234
console.log(buf.readUInt16LE(0).toString(16));
// Prints: 3412
console.log(buf.readUInt16BE(1).toString(16));
// Prints: 3456
console.log(buf.readUInt16LE(1).toString(16));
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readUInt32BE(offset)‎ و buf.readUInt32LE(offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة، ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 4.

يقرأ هذا التابع الأعداد الصحيحة عديمة الإشارة (unsigned integer) ذات الحجم 32 بت من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهمية مُخزَّنة أولًا (big endian)، فاستعمل readUInt32BE()‎؛ وإن كانت البتات الأكثر أهمية مُخزَّنة أولًا (little endian)، فاستعمل readUInt32LE()‎.

تُفسَّر الأعداد الصحيحة المقروءة من نسخة Buffer على أنَّها قيم متمِّمة ثنائيًّا (two's complement) وعديمة الإشارة.

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

console.log(buf.readUInt32BE(0).toString(16));
// Prints: 12345678
console.log(buf.readUInt32LE(0).toString(16));
// Prints: 78563412
console.log(buf.readUInt32LE(1).toString(16));
// ERR_OUT_OF_RANGE يرمى الخطأ

buf.readUIntBE(offset, byteLength)‎ و buf.readUIntLE(offset, byteLength)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset والمعامل byteLength إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • offset: ‏<integer> عدد البايتات المراد تخطيها قبل البدء بعملية القراءة، ويجب أن تقع قيمة هذا المعامل في المجال ‎0 <= offset <= buf.length - byteLength.
  • byteLength: ‏<integer> عدد البايتات المراد قراءتها، ويجب أن تقع قيمة هذا المعامل في المجال ‎0 < byteLength <= 6.

يقرأ هذا التابع الأعداد الصحيحة عديمة الإشارة ذات الحجم byteLength المعطى من buf بدءًا من البايت offset المعطى مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة ثمَّ يعيدها. إن كانت البتات الأقل أهميَّة مُخزَّنة أولًا (big endian)، فاستعمل readUIntBE()‎؛ وإن كانت البتات الأكثر أهمية مُخزَّنة أولًا (little endian)، فاستعمل readUIntLE()‎.

تفسَّر الأعداد الصحيحة المقروءة من نسخة Buffer على أنَّها قيم متمِّمة ثنائيًّا (two's complement) وعديمة الإشارة. تدعم هذه الدالة قراءة الأعداد الصحيحة بدقة تصل إلى 48 بت.

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

console.log(buf.readUIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readUIntLE(0, 6).toString(16));
// Prints: ab9078563412
console.log(buf.readUIntBE(1, 6).toString(16));
// ERR_OUT_OF_RANGE يرمى الخطأ

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

سجل التغييرات
الإصدار التغييرات
v7.1.0 - v6.9.2 أصبح تحويل قيمة المعامل start والمعامل end إلى أعداد صحيحة يدعم قيمًا ذات دقة أكبر من 32 بت.
v7.0.0 يُحوَّل الآن المعامل start والمعامل end إلى أعداد صحيحة قبل بدء إجراء أية عمليَّة حسابيَّة عليهما.
v0.3.0 أضيف هذا التابع.
  • start: ‏<integer> عددٌ يمثل فهرس البايت الذي يُحدَّد بداية الجزء المراد اقتطاعه من كائن Buffer معيَّن.
  • end: ‏<integer> عددٌ يمثل فهرس البايت الذي يُحدِّد نهاية الجزء المراد اقتطاعه من كائن Buffer معيَّن (لا يدخل هذا البايت ضمن الجزء المقتطع).

يعيد هذا التابع كائن Buffer جديد يتشارك جزء الذاكرة المحجوز نفسه مع الكائن Buffer الأصلي باستنثاء أنَّه يقتطع ذلك الجزء عبر تحديد بدايته ونهايته.

إعطاء قيمة للمعامل end أكبر من القيمة buf.length سيعيد النتيجة نفسها فيما لو كانت قيمة هذا المعامل مساويةً إلى buf.length.

تعديل الكائن Buffer المقتطع سيؤدي إلى تعديل جزء الذاكرة المخصص للكائن buffer الأصلي بسبب تداخل جزء الذاكرة المحجوز لكلٍّ منهما.

// فيه، ثمَّ اقتطاع جزء منه، ثمَّ تعديل ASCII جديد ووضع بعض محارف Buffer إنشاء كائن 
// الأصلي Buffer بايت واحد من الكائن

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // ASCII في الجدول 'a' العدد 97 هو قيمة المحرف
  buf1[i] = i + 97;
}

const buf2 = buf1.slice(0, 3);

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

buf1[0] = 33;

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

استعمال قيمٍ سالبةٍ مع المعامل start أو المعامل end يؤدي إلى تحديد فهرس البايت -الذي يعين بداية أو نهاية الجزء المراد اقتطاعه- بدءًا من نهاية الكائن buf بدلًا من بدايته.

const buf = Buffer.from('buffer');

console.log(buf.slice(-6, -1).toString());
// buffe :سيُطبع
// (Equivalent to buf.slice(0, 5))

console.log(buf.slice(-6, -2).toString());
// buff :سيُطبع
// (Equivalent to buf.slice(0, 4))

console.log(buf.slice(-5, -2).toString());
// uff :سيُطبع
// (Equivalent to buf.slice(1, 4))

buf.swap16()‎

أضيف في الإصدار v5.10.0.

يفسِّر هذا التابع الكائن buf المُعطى على أنَّه مصفوفةٌ لأعداد صحيحة عديمة الإشارة بحجم 16 بت ويعكس ترتيب بايتي كلِّ عدد في مكانهما ثمَّ يعيد ذلك الكائن.

سيُرمَى الخطأ ERR_INVALID_BUFFER_SIZE إن لم تكن قيمة buf.length من مضاعفات العدد 2.

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.swap32()‎

أضيف في الإصدار v5.10.0.

يُفسِّر هذا التابع الكائن buf المعطى على أنَّه مصفوفةٌ لأعداد صحيحة عديمة الإشارة بحجم 32 بت ويعكس ترتيب البايتات الأربعة لكل عدد في مكانهما ثمَّ يعيد ذلك الكائن.

سيُرمى الخطأ ERR_INVALID_BUFFER_SIZE إن لم تكن قيمة buf.length من مضاعفات العدد 4.

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.

يُفسِّر هذا التابع الكائن buf المعطى على أنَّه مصفوفةٌ لأعداد صحيحة عديمة الإشارة بحجم 64 بت ويعكس ترتيب البايتات الأربعة لكل عدد في مكانهما ثمَّ يعيد ذلك الكائن.

سيُرمَى الخطأ ERR_INVALID_BUFFER_SIZE إن لم تكن قيمة buf.length من مضاعفات العدد 8.

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 سيرمى الخطأ

انتبه إلى أنَّ JavaScript لا تستطيع أن ترمِّز أعداد صحيحة بحجم 64 بت حاليًّا، لذا يستعمل هذا التابع مع الأعداد العشرية (floats) ذات الحجم 64 بت.

buf.toJSON()‎

أضيف في الإصدار v0.9.2.

يحوِّل هذا التابع محتويات النسخة buf إلى صيغة JSON ثمَّ يعيدها في كائن من النوع Object. يستدعى هذا التابع ضمنيًّا عند استدعاء JSON.stringify()‎ لتحويل نسخة 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.data) :
    value;
});

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

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

أضيف في الإصدار v0.1.90.

  • encoding: ‏<string> سلسلة نصية تحدِّد ترميز المحارف المراد استعماله. القيمة الافتراضيَّة هي: 'utf8'.
  • start:‏ <string> عددٌ يمثل فهرس البايت الذي ستبدأ عمليَّة فك الترميز عنده. القيمة الافتراضيَّة هي: 0.
  • end: ‏<string> عددٌ يمثل فهرس البايت الذي ستنتهي عمليَّة فك الترميز عنده (لا يدخل هذا البايت ضمن المجال). القيمة الافتراضيَّة هي: buf.length.

يفك هذا التابع ترميز كائن buf معيَّن إلى سلسلة نصية وفقًا للترميز encoding المعطى. يمكن فك ترميز جزء معيَّن فقط من buf عبر تمرير قيمةٍ للمعامل start والمعامل end.

الطول الأعظمي لنسخةٍ من سلسلةٍ نصيةٍ (في واحدات الترميز UTF-16) متاحٌ عبر buffer.constants.MAX_STRING_LENGTH.

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // ASCII في الجدول 'a' العدد 97 هو قيمة المحرف
  buf1[i] = i + 97;
}

console.log(buf1.toString('ascii'));
// abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('ascii', 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) لقيم (بايتات) الكائن buf ثمَّ يعيده. يستدعى هذا التابع تلقائيًّا عند استعمال كائن buffer في الحلقة for..of التكرارية.

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.
  • encoding:‏ <string> ترميز السلسلة النصية string المراد كتابتها. القيمة الافتراضيَّة هي: 'utf8'.

يكتب هذا التابع السلسلة النصية string المعطاة في الكائن buf عند البايت offset بعد ترميزها وفقًا للترميز encoding المحدَّد. يعيد بعدئذٍ عدد البايتات التي كُتبَت.

إن لم يحتوي الكائن buf على مساحة كافية تتسع السلسلة النصية string، فسيُكتَب قسمٌ من تلك السلسلة بحسب المساحة المتوافرة.

const buf = Buffer.alloc(256);

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

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

buf.writeDoubleBE(value, offset)‎ و buf.writeDoubleLE(value, offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • value: ‏<number> عددٌ عشري مضاعف (double) بحجم 64 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال  ‎0 <= offset <= buf.length - 8.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة. يعيد التابع بعدئذٍ عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset. إن كنت تريد كتابة البتات الأقل أهمية أولًا (big endian)، فاستعمل writeDoubleBE()‎؛ وإن كنت تريد كتابة البتات الأكثر أهمية أولًا (little endian)، فاستعمل writeDoubleLE()‎.

يجب أن يكون المعامل value عددًا عشريًا مضاعفًا بحجم 64 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

buf.writeFloatBE(value, offset)‎ و buf.writeFloatLE(value, offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حُذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • value: ‏<number> عددٌ عشري (float) بحجم 32 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال  ‎0 <= offset <= buf.length - 4.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة. يعيد التابع بعدئذٍ عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset. إن كنت تريد كتابة البتات الأقل أهمية أولًا (big endian)، فاستعمل writeFloatBE()‎؛ وإن كنت تريد كتابة البتات الأكثر أهمية أولًا (little endian)، فاستعمل writeFloatLE()‎.

يجب أن يكون المعامل value عددًا عشريًا بحجم 32 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

const buf = Buffer.allocUnsafe(4);

buf.writeFloatBE(0xcafebabe, 0);

console.log(buf);
// <Buffer 4f 4a fe bb> :سيُطبع

buf.writeFloatLE(0xcafebabe, 0);

console.log(buf);
// <Buffer bb fe 4a 4f> :سيُطبع

buf.writeInt8(value, offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.0 أضيف هذا التابع.
  • value: ‏<number> عددٌ صحيح ذو إشارة (signed integer) بحجم 8 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال  ‎0 <= offset <= buf.length - 1.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset ثمَّ يعيد عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset.

يجب أن يكون المعامل value عددًا صحيحًا ذي إشارة بحجم 8 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

يُفسَّر العدد الصحيح المراد كتابته على أنَّه متممٌ ثنائيٌ (two's complement) وله إشارة.

const buf = Buffer.allocUnsafe(2);

buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);

console.log(buf);
// <Buffer 02 fe> :سيُطبع

buf.writeInt16BE(value, offset)‎ و buf.writeInt16LE(value, offset)‎

  • value: ‏<number> عدد صحيح ذو إشارة (signed integer) بحجم 16 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال  ‎0 <= offset <= buf.length - 2.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة. يعيد التابع بعدئذٍ عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset. إن كنت تريد كتابة البتات الأقل أهمية أولًا (big endian)، فاستعمل writeInt16BE()‎؛ وإن كنت تريد كتابة البتات الأكثر أهمية أولًا (little endian)، فاستعمل writeInt16LE()‎.

يجب أن يكون المعامل value عددًا صحيحًا ذي إشارة بحجم 16 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

يفسَّر العدد الصحيح المراد كتابته على أنَّه متممٌ ثنائيٌ (two's complement) وله إشارة.

const buf = Buffer.allocUnsafe(4);

buf.writeInt16BE(0x0102, 0);
buf.writeInt16LE(0x0304, 2);

console.log(buf);
// <Buffer 01 02 04 03> :سيُطبع

buf.writeInt32BE(value, offset)‎ و buf.writeInt32LE(value, offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • value:‏ <number> عددٌ صحيحٌ ذو إشارة (signed integer) بحجم 32 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعملية القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 4.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة. يعيد التابع بعدئذٍ عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset. إن كنت تريد كتابة البتات الأقل أهمية أولًا (big endian)، فاستعمل writeInt32BE()‎؛ وإن كنت تريد كتابة البتات الأكثر أهمية أولًا (little endian)، فاستعمل writeInt32LE()‎.

يجب أن يكون المعامل value عددًا صحيحًا ذي إشارة بحجم 32 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

يفسَّر العدد الصحيح المراد كتابته على أنَّه متممٌ ثنائيٌ (two's complement) وله إشارة.

const buf = Buffer.allocUnsafe(8);

buf.writeInt32BE(0x01020304, 0);
buf.writeInt32LE(0x05060708, 4);

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

buf.writeIntBE(value, offset, byteLength)‎ و buf.writeIntLE(value, offset, byteLength)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.11.15 أضيف هذا التابع.
  • value: ‏<number> عددٌ صحيحٌ ذو إشارة (signed integer) يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - byteLength.
  • byteLength: ‏<integer> عدد البايتات المراد كتابتها. يجب أن تقع قيمة هذا المعامل في المجال ‎0 < byteLength <= 6.

يكتب هذا التابع عددًا محددًا من بايتات المعامل value المعطى في buf بدءًا من البايت offset ثمَّ يعيد عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset.

يدعم هذا التابع الأعداد الصحيحة ذات الإشارة بدقة تصل إلى 48 بت. يجب أن يكون المعامل value عددًا صحيحًا ذي إشارة، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

const buf = Buffer.allocUnsafe(6);

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

console.log(buf);
// <Buffer 12 34 56 78 90 ab> :سيُطبع

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

console.log(buf);
// <Buffer ab 90 78 56 34 12> :سيُطبع

buf.writeUInt8(value, offset)‎

سجل التغييرات
الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.0 أضيف هذا التابع.
  • value: ‏<number> عددٌ صحيحٌ عديم الإشارة (unsigned integer) بحجم 8 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 1.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset ثمَّ يعيد عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset.

يجب أن يكون المعامل value عددًا صحيحًا عديم الإشارة بحجم 8 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);

console.log(buf);
// <Buffer 03 04 23 42> :سيُطبع

buf.writeUInt16BE(value, offset)‎ و buf.writeUInt16LE(value, offset)‎

الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • value: ‏<number> عددٌ صحيحٌ عديم الإشارة (unsigned integer) بحجم 16 بت يراد كتابته في كائن buf معين.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 2.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة. يعيد التابع بعدئذٍ عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset. إن كنت تريد كتابة البتات الأقل أهمية أولًا (big endian)، فاستعمل writeUInt16BE()‎؛ وإن كنت تريد كتابة البتات الأكثر أهمية أولًا (little endian)، فاستعمل writeUInt16LE()‎.

يجب أن يكون المعامل value عددًا صحيحًا عديم الإشارة بحجم 16 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);

console.log(buf);
// <Buffer de ad be ef> :سيُطبع

buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);

console.log(buf);
// <Buffer ad de ef be> :سيُطبع

buf.writeUInt32BE(value, offset)‎ و buf.writeUInt32LE(value, offset)‎

الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • value: ‏<number> عددٌ صحيحٌ عديم الإشارة (unsigned integer) بحجم 32 بت يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - 4.

يكتب هذا التابع قيمة المعامل value المعطى في buf بدءًا من البايت offset مع مراعاة التنسيق المستعمل في ترتيب البتات المُخزَّنة أولًا في الذاكرة. يعيد التابع بعدئذٍ عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset. إن كنت تريد كتابة البتات الأقل أهمية أولًا (big endian)، فاستعمل writeUInt32BE()‎؛ وإن كنت تريد كتابة البتات الأكثر أهمية أولًا (little endian)، فاستعمل writeUInt32LE()‎.

يجب أن يكون المعامل value عددًا صحيحًا عديم الإشارة بحجم 32 بت، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32BE(0xfeedface, 0);

console.log(buf);
// <Buffer fe ed fa ce> :سيُطبع

buf.writeUInt32LE(0xfeedface, 0);

console.log(buf);
// <Buffer ce fa ed fe> :سيُطبع

buf.writeUIntBE(value, offset, byteLength)‎ و buf.writeUIntLE(value, offset, byteLength)‎

الإصدار التغييرات
v10.0.0 حذف المعامل noAssert، ولم يعد يُحوَّل المعامل offset إلى النوع uint32 ضمنيًّا بعد الآن.
v0.5.5 أضيف هذا التابع.
  • value: ‏<number> عددٌ صحيحٌ عديم الإشارة (unsigned integer) يراد كتابته في كائن buf معيَّن.
  • offset: ‏<number> عدد البايتات المراد تخطيها قبل البدء بعمليَّة القراءة. ويجب أن تقع القيمة المعطاة بين المجال ‎0 <= offset <= buf.length - byteLength.
  • byteLength: ‏<integer> عدد البايتات المراد كتابتها. يجب أن تقع قيمة هذا المعامل في المجال ‎0 < byteLength <= 6.

يكتب هذا التابع عددًا محددًا من بايتات المعامل value المعطى في buf بدءًا من البايت offset ثمَّ يعيد عدد البايتات المكتوبة مضافًا إليه قيمة المعامل offset.

يدعم هذا التابع الأعداد الصحيحة عديمة الإشارة بدقة تصل إلى 48 بت. يجب أن يكون المعامل value عددًا صحيحًا عديم الإشارة، ولن يُعرَف سلوك التابع إن كانت قيمة المعامل غير ذلك.

const buf = Buffer.allocUnsafe(6);

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

console.log(buf);
// <Buffer 12 34 56 78 90 ab> :سيُطبع

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

console.log(buf);
// <Buffer ab 90 78 56 34 12> :سيُطبع

الخاصية buffer.INSPECT_MAX_BYTES

أضيفت في الإصدار v0.5.4.

تعيد هذه الخاصِّيَّة عدد البايتات الأعظمي التي سيُعاد عند استدعاء buf.inspect()‎. القيمة الافتراضيَّة هي: 50. يمكن أن يُستبدَل هذا العدد من طرف وحدات المستخدم. ارجع إلى util.inspect()‎ لتفاصيل أوسع حول سلوك التابع buf.inspect()‎.

انتبه إلى أنَّ هذه الخاصِّيًّة هي خاصِّيَّةٌ في الوحدة Buffer تُعاد عبر require('buffer')‎ وليست في Buffer العام أو نسخة Buffer.

الخاصية buffer.kMaxLength

أضيفت في الإصدار v3.0.0.

تعيد هذه الخاصِّيًّة عددًا يمثل أكبر حجم مسموح لنسخة Buffer واحدة، وهي اسم بديل للخاصِّيَّة buffer.constants.MAX_LENGTH.

انتبه إلى أنَّ هذه الخاصِّيًّة هي خاصِّيَّةٌ في الوحدة Buffer تُعاد عبر require('buffer')‎ وليست في Buffer العام أو نسخة Buffer.

التابع buffer.transcode(source, fromEnc, toEnc)

سجل التغييرات
الإصدار التغيير
v8.0.0 يمكن أن يكون المعامل source الآن نسخةً من النوع Uint8Array.
v7.1.0 أضيف هذا التابع.
  • source: ‏<Buffer> | <Uint8Array> نسخةٌ من Buffer أو Uint8Array.
  • fromEnc: ‏<string> الترميز الحالي.
  • toEnc: ‏<string> الترميز المراد التحويل إليه.

تغير هذه الدالة ترميز نسخة Buffer أو Uint8Array المعطية من ترميز إلى آخر ثمَّ تضع الناتج في نسخة Buffer جديدة وتعيدها.

سيُرمى خطأ إن كان الترميز fromEnc أو الترميز toEnc غير مدعوم أو غير صحيح أو إن لم يكن مسموحًا بالتحويل من الترميز fromEnc إلى الترميز toEnc.

ستَستعمل عمليَّة التحويل التي تجريها هذه الدالة محارف بديلة إن لم يكن بالإمكان تمثيل أحد البايتات المعطية على نحو ملائم في الترميز المراد التحويل إليه. إليك هذه الشيفرة مثلًا التي تشرح ذلك:

const buffer = require('buffer');

const newBuf = buffer.transcode(Buffer.from('€'), 'utf8', 'ascii');
console.log(newBuf.toString('ascii'));
// '?' :سيُطبع

لمَّا كان المحرف € غير قابل للتمثيل في الترميز US-ASCII، فاستُبدِل به المحرف ? في النسخة Buffer المحولة إلى ذلك الترميز.

انتبه إلى أنَّ هذه الخاصِّيَّة هي خاصِّيَّةٌ في الوحدة Buffer تُعاد عبر require('buffer')‎ وليست في Buffer العام أو نسخة Buffer.

الصنف SlowBuffer

أهمل في الإصدار v6.0.0.

الاستقرار: 0-مهمل: استعمل Buffer.allocUnsafeSlow()‎ عوضًا عنه.

يستعمل هذا الصنف لإنشاء نسخة Buffer تقع خارج المُجمِّع (pool) المحجوز مسبقًا.

عند إنشاء نسخ جديدة من Buffer، تُقتَطَع بشكل افتراضي حجوزات الذاكرة التي تقل عن 4 كيلوبايت من نسخة Buffer واحدة محجوزة مسبقًا. هذا يساعد التطبيقات على تجنب زيادة مجمَّع المهملات (garbage allocation) عبر تقليل إنشاء نسخ Buffer جديدة وحجز أجزاء من الذاكرة بشكل فردي. يحسِّن ذلك الأداء واستخدام الذاكرة عبر تقليل الحاجة إلى تتبُّع وإزالة أقل قدر ممكن من الكائنات الموجودة والمتكرِّرة.

مع ذلك، في حال احتاج المطور إلى الاحتفاظ يجزءٍ صغيرٍ من الذاكرة يقع في المجمِّع (pool) المحجوز مسبقًا لفترة زمنية غير معلومة، فيُستحسَن إنشاء نسخة Buffer بحجز جزء آخر من الذاكر يقع خارج مجمِّع الذاكرة المحجوز مسبقًا (un-pooled) عبر استعمال SlowBuffer ثمَّ نسخ البيانات التي تريد الاحتفاظ بها إليها.

// الحاجة إلى الاحتفاظ ببعض أجزاء الذاكرة
const store = [];

socket.on('readable', () => {
  const sb = SlowBuffer(10);

  // حجز جزء من الذاكرة خاص بالبيانات المراد الاحتفاظ بها
  const sb = Buffer.allocUnsafeSlow(10);

  // نسخ البيانات إلى موقع جديد
  data.copy(sb, 0, 0, 10);

  store.push(sb);
});

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

new SlowBuffer(size)‎

أهملت في الإصدار v6.0.0.

الاستقرار: 0-مهمل: استعمل التابع Buffer.allocUnsafeSlow()‎ عوضًا عن هذه الدالة.

  • size: ‏<integer> حجم الذاكرة المراد حجزه للنسخة Buffer المنشأة.

تنشئ هذه الدالة نسخة Buffer جديدة وتحجز لها من الذاكرة الحجم size المعطى. إن كانت قيمة المعامل size المعطاة أكبر من buffer.constants.MAX_LENGTH أو أصغر من الصفر، فسيُرمى الخطأ ERR_INVALID_OPT_VALUE. الجدير بالذكر أنَّه تنشأ النسخة Buffer إن أعطيت القيمة 0 للمعامل size.

انتبه إلى أنَّ هذه الدالة لا تهيئ الذاكرة التي تحجزها عند استعمالها لإنشاء نسخٍ من Buffer. نتيجةً لذلك، لا يُعرَف المحتوى الأولي للنسخة Buffer المنشأة آنذاك وقد يحوي بعض البيانات الحسَّاسة التي كتبت على تلك الذاكرة مسبقًا. إن أردت تهيئة جزء الذاكرة المحجوز ووضع قيمة أولية معروفة فيه، فاستعمل التابع buf.fill()‎.

const { SlowBuffer } = require('buffer');

const buf = new SlowBuffer(5);

console.log(buf);
// <Buffer 78 e0 82 02 01> :سيُطبع شيء شبيه بهذا

buf.fill(0);

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

ثوابت Buffer

أضيفت في الإصدار v8.2.0.

انتبه إلى أنَّ buffer.constants خاصِّيَّةٌ في الوحدة buffer تُعاد عبر require('buffer')‎ وليست في Buffer العام أو نسخة Buffer.

الخاصية buffer.constants.MAX_LENGTH

أضيفت في الإصدار v8.2.0.

تعيد هذه الخاصِّيَّة عددًا يمثل أكبر حجم مسموح لنسخة Buffer واحدة. فتكون قيمة هذا الثابت في الأنظمة ذات المعمارية 32 بت هي ‎(2^30)-1 (تقريبًا 1 غيغابايت)، وفي الأنظمة ذات المعمارية 64 بت هي ‎(2^31)-1 (تقريبًا 2 غيغابايت).

هنالك اسم بديل لهذه الخاصِّيَّة هو buffer.kMaxLength.

الخاصية buffer.constants.MAX_STRING_LENGTH

أضيفت في الإصدار v8.2.0.

تعيد هذه الخاصِّيَّة عددًا يمثل أكبر حجم مسموح لنسخة string واحدة، إذ يُحسَب هذا الحجم في واحدات الترميز UTF-16.

قد تعتمد هذه القيمة على محرك JavaScript المُستعمَل.

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=Node.js/buffer&oldid=20913"