التابع Encoding::Converter.primitive_errinfo في روبي
يُعيد التّابع primitive_errinfo معلوماتٍ مهمّةً حول آخر خطأٍ حدث في مصفوفة مكونة من خمسة عناصر مثل:
[result, enc1, enc2, error_bytes, readagain_bytes]
تكون result هي آخر نتيجة تحويل للتّابع primitive_convert.
تكون العناصر الأخرى ذات معنى فقط عندما تكون result هي invalid_byte_sequence:، أو incomplete_input:، أو undefined_conversion:.
تدلُّ القيمتان enc1 وenc2 على خطوة التحويل على شكل زوجٍ من السلاسل النصيّة. على سبيل المثال، يحول محولٌ (converter) من التّرميزEUC-JP إلى الترميز ISO-8859-1 سلسلة نصية بالشكل التالي: EUC-JP -> UTF-8 -> ISO-8859-1. إذًا، تكون القيمتان [enc1, enc2] إما [“EUC-JP”, “UTF-8”] أو [“UTF-8”, “ISO-8859-1”].
تُشير القيمتان error_bytes و readagain_bytes إلى سلاسل البايت التي سببت الخطأ. يكون error_bytes هو الجزء المهمل، و readagain_bytes هو الجزء المخزَّن مؤقتًا الذي سيُقرأ مجدّدًا في عملية التحويل التالية.
البنية العامة
primitive_errinfo → array
القيم المعادة
تُعاد مصفوفة ذات 5 عناصر: [result, enc1, enc2, error_bytes, readagain_bytes]
القيمة result: آخر نتيجة من التّابع primitive_errinfo.
القيمتان enc1 وenc2: يدلّان على خطوة التحويل على شكل زوجٍ من السلاسل النصيّة.
القيمتان error_bytes وreadagain_bytes: تشيران إلى سلاسل البايت التي سببت الخطأ.
أمثلة
مثالٌ عن استخدام التابع primitive_errinfo:
# \xff is invalid as EUC-JP.
ec = Encoding::Converter.new("EUC-JP", "Shift_JIS")
ec.primitive_convert(src="\xff", dst="", nil, 10)
p ec.primitive_errinfo
#=> [:invalid_byte_sequence, "EUC-JP", "UTF-8", "\xFF", ""]
# HIRAGANA LETTER A (\xa4\xa2 in EUC-JP) is not representable in ISO-8859-1.
# Since this error is occur in UTF-8 to ISO-8859-1 conversion,
# error_bytes is HIRAGANA LETTER A in UTF-8 (\xE3\x81\x82).
ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
ec.primitive_convert(src="\xa4\xa2", dst="", nil, 10)
p ec.primitive_errinfo
#=> [:undefined_conversion, "UTF-8", "ISO-8859-1", "\xE3\x81\x82", ""]
# partial character is invalid
ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
ec.primitive_convert(src="\xa4", dst="", nil, 10)
p ec.primitive_errinfo
#=> [:incomplete_input, "EUC-JP", "UTF-8", "\xA4", ""]
# Encoding::Converter::PARTIAL_INPUT prevents invalid errors by
# partial characters.
ec = Encoding::Converter.new("EUC-JP", "ISO-8859-1")
ec.primitive_convert(src="\xa4", dst="", nil, 10, Encoding::Converter::PARTIAL_INPUT)
p ec.primitive_errinfo
#=> [:source_buffer_empty, nil, nil, nil, nil]
# \xd8\x00\x00@ is invalid as UTF-16BE because
# no low surrogate after high surrogate (\xd8\x00).
# It is detected by 3rd byte (\00) which is part of next character.
# So the high surrogate (\xd8\x00) is discarded and
# the 3rd byte is read again later.
# Since the byte is buffered in ec, it is dropped from src.
ec = Encoding::Converter.new("UTF-16BE", "UTF-8")
ec.primitive_convert(src="\xd8\x00\x00@", dst="", nil, 10)
p ec.primitive_errinfo
#=> [:invalid_byte_sequence, "UTF-16BE", "UTF-8", "\xD8\x00", "\x00"]
p src
#=> "@"
# Similar to UTF-16BE, \x00\xd8@\x00 is invalid as UTF-16LE.
# The problem is detected by 4th byte.
ec = Encoding::Converter.new("UTF-16LE", "UTF-8")
ec.primitive_convert(src="\x00\xd8@\x00", dst="", nil, 10)
p ec.primitive_errinfo
#=> [:invalid_byte_sequence, "UTF-16LE", "UTF-8", "\x00\xD8", "@\x00"]
p src
#=> ""
انظر أيضًا
- التابع primitive_convert: يحوّل ترميز جميع المحتويات المخزَّنة مؤقتًا (buffer) في مخزن معين أو مجال محدد منها -من ترميز المصدر إلى ترميز الوجهة- ثم يضع الناتج في مخزَّن محدَّد.
- التّابع asciicompat_encoding: يُعيد التّرميز المتوافق مع ASCII المقابل للترميز المعطى.
- التّابع destination_encoding: يُعيد التّرميز الوجهة على شكل كائنٍ من الصنف Encoding.
- التّابع source_encoding: يُعيد الترميز المصدر على شكل كائن من الصنف Encoding.
- التّابع primitive_convert: يحوّل ترميز جميع المحتويات المخزَّنة مؤقتًا (buffer) في مخزن معين أو مجال محدد منها -من ترميز المصدر إلى ترميز الوجهة- ثم يضع الناتج في مخزَّن محدَّد.
- التّابع insert_output: يضيف سلسلةً نصيّةً إلى محوِّل التّرميز، إذ سيحويل ترميز هذه السلسلة إلى ترميز الوجهة نفسه وتوضع في نهاية مخرجات عملية التحويل.
- التّابع finish: يُنهي محوّل الترميز، ويُعيد الجزء الأخير من السلسلة النصيّة التي يحول ترميزها حينذاك.