Ruby/Encoding/Converter/new

يُنشئ التّابع new:: كائنًا جديدًا من الصنف Encoding::Converter. التّرميز المصدر والتّرميز الوجهة يجب أن يكونا إما سلسلةً نصّيةً أو كائنًا من الصّنف Encoding.

يقبل التّابع new:: اختياريًّا أن يمرر إليه خيارٌ من النوع hash أو integer. عندما يكون من النوع hash، فمن الممكن أن يحتوي على ‎:invalid => nil وغيرها. وعندما يكون من النوع integer، فإنه يجب أن يكون منطقيًّا (logical)، أو أحد الثوابت المعرَّفة مثل Encoding::Converter::INVALID_REPLACE وغيرها.

تكون بنية الخيار الممرر إلى التابع عندما يكون من النوع hash بالشكل:

• invalid => nil: يرمي خطأً عند سلسلة بايتٍ غير صالحةٍ (القيمة الافتراضية).
• invalid => :replace: يستبدل سلسلة البايت غير الصّالحة.
• undef => nil: يرمي استثناءً عند تحويلٍ غير معرّف (القيمة الافتراضية).
• undef => :replace: يستبدل التحويلات غير المعرّفة.
• replace => string: يستبدل سلسلة ("?" أو "\uFFFD" إذا لم يُحَّدد أي شيء).
• newline => :universal: ينشئ مُزخرِفًا لتحويل CRLF و CR إلى LF.
• newline => :crlf: ينشئ مُزخرِفًا لتحويل LF إلى CRLF.
• newline => :cr: ينشئ مُزخرِفًا لتحويل LF إلى CR.
• universal_newline => true: ينشئ مُزخرِفًا لتحويل CRLFو CR إلى LF.
• crlf_newline => true: بنشئ مُزخرِفًا لتحويل LF إلى CRLF.
• cr_newline => true: ينشئ مُزخرِفًا لتحويل LF إلى CR.
• xml => :text: هروب على شكل CharData. يمكن أن تستخدم هذه الصيغة على أنها (HTML 4.0 #PCDATA).
  • '‎&' -> '&‎'
  • '‎<' -> '&lt;‎'
  • '‎>' -> '>‎'
  • المحارف غير المعرفة في التابع CharRef <- destination_encoding ست عشرية مثل ‎&#xHH.

• xml => :attr: هروب على شكل AttValue. توضع النتيجة بعد التحويل بين علامتي اقتباس بالشكل "…". يمكن أن تستخدم هذه الصيغة على أنها قيمة خاصيّة HTML.
  • '‎&' -> '&‎'
  • '‎<' -> '&lt;‎'
  • '‎>' -> '>‎'
  • '‎“' -> '"‎'
  • المحارف غير المعرفة في التابع CharRef <- destination_encoding الست عشري مثل ‎&#xHH.

وتكون بنية الخيار الممرر إلى التابع عندما يكون من النوع integer بالشكل:

•  Encoding::Converter::INVALID_REPLACE
•  Encoding::Converter::UNDEF_REPLACE
•  Encoding::Converter::UNDEF_HEX_CHARREF
•  Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR
•  Encoding::Converter::CRLF_NEWLINE_DECORATOR
•  Encoding::Converter::CR_NEWLINE_DECORATOR
•  Encoding::Converter::XML_TEXT_DECORATOR
•  Encoding::Converter::XML_ATTR_CONTENT_DECORATOR
•  Encoding::Converter::XML_ATTR_QUOTE_DECORATOR

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

Encoding::Converter.new(source_encoding, destination_encoding)

Encoding::Converter.new(source_encoding, destination_encoding, opt)

Encoding::Converter.new(convpath)

المعاملات

source_encoding

سلسلةً نصّيةً (string) أو كائنًا يمثَّل التّرميز المصدر الذي يراد إنشاء كائن منه.

destination_encoding

سلسلةٌ نصّيةٌ (string) أو كائنٌ يمثَّل التّرميز الوجهة الجديد.

opt

يجب أن يكون هذا المعامل قيمةً عدميّةً (nil)، أو خريطةً (hash)، أو عددًا صحيحًا (integer).

convpath

يجب أن يكون هذا المعامل مصفوفة (array)، ويمكن أن تحتوي على:

• عنصرين يمثلان كائن التّرميز أو اسمه، أو
• سلاسل نصّية تمثّل أسماء المزخرِفات (decorator names).

أمثلة

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

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

# Usually, decorators such as newline conversion are inserted last.
ec = Encoding::Converter.new("UTF-16BE", "UTF-8", :universal_newline => true)
p ec.convpath #=> [[#<Encoding:UTF-16BE>, #<Encoding:UTF-8>],
              #    "universal_newline"]

# But, if the last encoding is ASCII incompatible,
# decorators are inserted before the last conversion.
ec = Encoding::Converter.new("UTF-8", "UTF-16BE", :crlf_newline => true)
p ec.convpath #=> ["crlf_newline",
              #    [#<Encoding:UTF-8>, #<Encoding:UTF-16BE>]]

# Conversion path can be specified directly.
ec = Encoding::Converter.new(["universal_newline", ["EUC-JP", "UTF-8"], ["UTF-8", "UTF-16BE"]])
p ec.convpath #=> ["universal_newline",
              #    [#<Encoding:EUC-JP>, #<Encoding:UTF-8>],
              #    [#<Encoding:UTF-8>, #<Encoding:UTF-16BE>]]

انظر أيضًا

• التّابع last_error: يُعيد الكائن exception عند حصول خطأٍ في آخر عملية تحويل أو يعيد القيمة nil إن لم يحصل أي خطأ.
• التّابع destination_encoding: يُعيد التّرميز الوجهة على شكل كائنٍ من الصنف Encoding.
• التّابع source_encoding: يُعيد الترميز المصدر على شكل كائن من الصنف Encoding.

مصادر

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