Ruby/Encoding/Converter/primitive convert

يحوّل التابع primitive_convert ترميز جميع المحتويات المخزَّنة مؤقتًا (buffer) في مخزن معين أو مجال محدد منها -من ترميز المصدر إلى ترميز الوجهة- ثم يضع الناتج في مخزَّن محدَّد.

يحذف التّابع primitive_convert الجزء المحوّل من المخزن source_buffer المصدر، ويضعه في المخزن destination_buffer الوجهة أو يخزنِّه مؤقتًا في كائن من الصنفEncoding::Converter بعد تحويله بالتأكيد.

يوقف التّابع primitive_convert عملية التحويل عند تحقّق أحد الشّروط التالية:

• وجود سلسلة بايت غير صالحة (invalid_byte_sequence:) في المخزن source_buffer المصدر  . يُعيد التابعان primitive_errinfo وlast_error تفاصيل الخطأ.
• نهايةٌ غير متوقعةٍ (incomplete_input:) للمخزن source_buffer المصدر، إذ يحدث هذا فقط عندما يكون partial_input: غير محدد. يُعيد التابعان primitive_errinfo وlast_errorتفاصيل الخطأ.
• محرفٌ غير قابلٍ لإعادة التمثيل (‎:undefined_conversion) في الترميز الهدف، يُعيد التابعان primitive_errinfo و last_error تفاصيل الخطأ.
• بعد توليد بعض المخرجات، وقبل انتهاء المدخلات (after_output:)، إذ يحدث هذا فقط عندما يُحدَّد after_output:.
• امتلاءالمخزن destination_buffer الوجهة (destination_buffer_full:)، إذ يحدث هذا فقط عندما لا تساوي قيمة المعامل destination_bytesize القيمة nil.
• كون المخزن source_buffer المصدر فارغًا (source_buffer_empty:)، يحدث هذا فقط عندما يُحدّد partial_input:.
• انتهاء عملية التحويل (finished:).

البنية العامة

primitive_convert(source_buffer, destination_buffer) → symbol

primitive_convert(source_buffer, destination_buffer, destination_byteoffset) → symbol

primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize) → symbol

primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize, opt) → symbol

يحدد المعاملان destination_byteoffset و destination_bytesize مكان ومجال إضافة الناتج المحوَّل في المخزن destination_buffer بدقة.

المعاملات

source_buffer

يجب أن يكون سلسلةً نصيةً (string) أو قيمةً عدميةً (nil). تعني القيمة العدمية، إن أعطيت، سلسلةً نصيةً فارغةً.

destination_buffer

سلسلة نصية تمثل المخزَّن المؤقت الذي سيوضع فيه ناتج عملية التحويل. بعد انتهاء عملية التحويل، يعاد حساب حجم المخزن destination_buffer ليصبح destination_byteoffset + عدد البايتات الفعلية الناتجة أو destination_bytesize (إن أعطي). يُضبَط أيضًا ترميز محتوى المخزن destination_buffer إلى الترميز destination_encoding.

destination_byteoffset

يحدد موضع البداية حيث سيُخزَّن الناتج المُحوَّل (بالبايت) بدءًا من بداية المخزن destination_buffer. يجب أن تكون عددًا صحيحًا (integer) أو قيمةً عدميةً. تعني القيمة العدمية نهاية المخزن destination_buffer أي أنَّ الناتج سيضاف في نهاية المخزَّن وفي المجال الذي يحدده المعامل destination_bytesize. القيمة الافتراضية لهذا المعامل هي: nil، إذا لم يُعطَ.

destination_bytesize

يحدد أكبر عدد من البايتات التي تمثل المجال الأقصى الذي سيُخزَّن فيه الناتج المُحوَّل في المخزن destination_buffer. يجب أن يكون عدد صحيحًا أو قيمة عدميَّة. تشير القيمة nil إلى عدم وجود حد أقصى لتخزين الناتج المحول. القيمة الافتراضية لهذا المعامل هي: nil، إذا لم يُعطَ.

opt

يجب أن يكون nil، أو hash، أو integer. تعني القيمة nil أنه لا يوجد رايات (flags). القيمة الافتراضية لهذا المعامل هي: nil، إذا لم يُعطَ.

العناصر المتاحة لقيمة المعامل opt هي:

• إن اسُعمل النوع hash، فيمكن أن يتكون من::
  • partial_input => true: قد يكون المخزن المصدر جزءًا من مصدرٍ أكبر.
  • after_output => true: يوقف التحويل بعد توليد قسم من المخرجات وقبل انتهاء المدخلات.

• أما إن استعمل النوع integer، فيمكن أن يتكون من::
  • Encoding::Converter::PARTIAL_INPUT
  • Encoding::Converter::AFTER_OUTPUT

النتائج المحتملة:

• invalid_byte_sequence:
• incomplete_input:
• undefined_conversion:
• after_output:
• destination_buffer_full:
• source_buffer_empty:
• finished:

القيم المعادة

يعاد كائن من النوع symbol.

أمثلة

مثالٌ عن استخدام التابع primitive_convert:

ec = Encoding::Converter.new("UTF-8", "UTF-16BE")

ret = ec.primitive_convert(src="pi", dst="", nil, 100)

p [ret, src, dst] #=> [:finished, "", "\x00p\x00i"]

ec = Encoding::Converter.new("UTF-8", "UTF-16BE")

ret = ec.primitive_convert(src="pi", dst="", nil, 1)

p [ret, src, dst] #=> [:destination_buffer_full, "i", "\x00"]

ret = ec.primitive_convert(src, dst="", nil, 1)

p [ret, src, dst] #=> [:destination_buffer_full, "", "p"]

ret = ec.primitive_convert(src, dst="", nil, 1)

p [ret, src, dst] #=> [:destination_buffer_full, "", "\x00"]

ret = ec.primitive_convert(src, dst="", nil, 1)

p [ret, src, dst] #=> [:finished, "", "i"]

انظر أيضًا

• التّابع primitive_errinfo: يُعيد معلوماتٍ مهمّةً حول آخر خطأٍ حدث في مصفوفة مكونة من خمسة عناصر.
• التّابع asciicompat_encoding: يُعيد التّرميز المتوافق مع ASCII المقابل للترميز المعطى.
• التّابع destination_encoding: يُعيد التّرميز الوجهة على شكل كائنٍ من الصنف Encoding.
• التّابع source_encoding: يُعيد الترميز المصدر على شكل كائن من الصنف Encoding.
• التّابع insert_output: يضيف سلسلةً نصيّةً إلى محوِّل التّرميز، إذ سيحويل ترميز هذه السلسلة إلى ترميز الوجهة نفسه وتوضع في نهاية مخرجات عملية التحويل.
• التّابع finish: يُنهي محوّل الترميز، ويُعيد الجزء الأخير من السلسلة النصيّة التي يحول ترميزها حينذاك.

مصادر

• صفحة التابع primitive_convert في الصنف Encoding::Converter في توثيق روبي الرسمي.