التابع 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: يُنهي محوّل الترميز، ويُعيد الجزء الأخير من السلسلة النصيّة التي يحول ترميزها حينذاك.