encodeInto في JavaScript: كيف تتابع الترميز عندما لا تتسع الوجهة؟

الخلاصة السريعة

• تابع موضع النص بوحدات read، وحدد الخرج ببايتات written. [1]
• في مثالنا كتبت الوجهة الأولى ثلاثة بايتات وبقيت خانتان دون تعديل.
• توقف الاختبار ذو السعة ستة عند الموضع نفسه الذي توقف عنده ذو السعة ثلاثة.
• أكملت وجهة ثانية النص، بينما لم تحرز وجهة أصغر أي تقدم.

نص صغير ووجهة نعرف محتواها

اخترنا النص Aب🙂Z بلا مسافات: حرف لاتيني، وباء عربية، ووجه مبتسم، ثم حرف لاتيني أخير. نفذنا تجربتنا محليا في Node.js 24.19.0 وEdge 155.0.4283.45. اتفقت النتائج في البيئتين، ولم نرسل بيانات إلى شبكة أو نكتب ملفا.

كان طول السلسلة في JavaScript خمسة، وخرجها الكامل ثمانية بايتات. هذه نتائج لهذه السلسلة المحددة؛ لا نعد الأشكال المرئية ثم نساويها تلقائيا بوحدات السلسلة. احتفظنا بالنص ونتيجة الترميز الكامل مرجعا للمقارنة.

ملأنا كل وجهة مسبقا بالقيمة 238. اخترنا هذه العلامة كي نرى الخانات التي لم تكتبها العملية، بدل أن نخمن من حجم المصفوفة أن كل خانة منها أصبحت جزءا من النص.

ما الذي تعنيه الخانات الباقية؟

تضمن الدالة أن البايتات المكتوبة تكون تتابعات UTF-8 كاملة. وفي خوارزمية المعيار تتوقف العملية إذا لم تتسع الوجهة لتتابع القيمة التالية. [1] [2]

عندما أعطينا النص وجهة من خمس خانات، كان read يساوي 2 وwritten يساوي 3. صارت البايتات الأولى 65 و216 و168، وبقيت الخانتان الأخيرتان 238 و238. الجزء المكتوب يمثل Aب؛ أما الجزء المتبقي من النص فهو 🙂Z.

لهذا لا نضم العلامتين الباقيتين إلى خرج تجربتنا. ليستا بايتين أنتجتهما العملية؛ كانتا موجودتين قبل الاستدعاء ولم تتغيرا. كذلك لا نأخذ بايتين فقط لأن read يساوي اثنين: تلك الخطوة ستحذف البايت الثالث الذي سجلناه فعلا.

اختبر السعة قبل تخمين مقدار التقدم

كررنا التجربة من البداية بوجهات جديدة، مع إبقاء النص نفسه والعلامة نفسها. يعرض الجدول طول كل وجهة ثم عددي التقدم والنص الذي بقي بعدها. كل صف اختبار مستقل، فلا يحمل نتيجة الصف السابق.

في صف السعة ستة بقيت ثلاث خانات متاحة، لكن الوجه في نصنا احتاج أربعة بايتات في الترميز المقاس. لذلك بقي 🙂Z كله. وعند السعة سبعة اكتمل الوجه وبقي Z وحده؛ أما السعة ثمانية فأكملت النص.

قارن صفّي الثلاثة والستة: تضاعفت السعة، لكن العددين المقروء والمكتوب لم يتغيرا. لا يصح توقع تقدم إضافي من زيادة المساحة وحدها دون النظر إلى الجزء التالي الذي بقي في هذه التجربة.

أكمل النص في استدعاء ثان

تبدأ الكتابة من أول الوجهة المعطاة. لقراءة الخرج نأخذ نطاقه حتى written؛ وللاستكمال نمرر بقية النص ابتداء من read. [1]

الكود التالي يعيد تجربة الوجهتين ذواتي السعة خمسة. اطبع النتيجتين والوجهتين، ثم قارن ما في السجل بالجدول. لا يعيد الاستدعاء الثاني استعمال العلامات الباقية في الأولى؛ أنشأنا له وجهة مستقلة.

أعطى الاستدعاء الثاني read يساوي 3 وwritten يساوي 5. الخرجان المكتوبان، بعد جمعهما بالترتيب، هما 65 و216 و168 ثم 240 و159 و153 و130 و90. تطابق الناتج ذو الثمانية بايتات مع مرجع الترميز الكامل الذي حفظناه.

في اختبار مقابل أعطينا بقية النص 🙂Z وجهة من ثلاث خانات. عاد العددان صفرا وبقيت العلامات الثلاث كما كانت. لا يصلح تكرار الحالة نفسها بلا تغيير لتسمية هذا استكمالا ناجحا؛ سجلنا عدم تقدم، ثم استخدمنا الوجهة ذات الخمس خانات في التجربة المكتملة.

const source = "Aب🙂Z";
const encoder = new TextEncoder();
const first = new Uint8Array(5).fill(238);
const a = encoder.encodeInto(source, first);
const next = new Uint8Array(5).fill(238);
const b = encoder.encodeInto(
  source.slice(a.read), next
);
console.log(a, [...first], b, [...next]);

[1] [2]

سجل ثلاثة أشياء منفصلة

تحتوي ورقة الفحص على موضع الاستكمال في النص، وعدد بايتات الخرج، وسعة الوجهة. في الخطوة الأولى كانت القيم 2 و3 و5؛ وتشابه الأعداد أحيانا لا يجعل الخانات متبادلة المعنى.

إذا اختبرت نصا آخر، احتفظ بمدخله ومرجعه الكامل، وافحص الجزء المكتوب وحده والبقية معا. مثالنا لا يقيس سرعة الترميز ولا يختبر نصوصا تالفة أو تنسيقات ملفات. وظيفته أن يبين بدليل قابل للإعادة أين توقف الاستدعاء وما الذي أنتجه فعلا.

المراجع

1. MDN — تقدم encodeInto
   https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/encodeInto
2. WHATWG — واجهة TextEncoder
   https://encoding.spec.whatwg.org/