عرض مصدر Ruby/Encoding/Converter/new

{{DISPLAYTITLE:التابع <code>Encoding::Converter.new‎</code> في روبي}}
يُنشئ التّابع <code>new::</code> كائنًا جديدًا من الصنف <code>[[Ruby/Encoding/Converter|Encoding::Converter]]</code>. التّرميز المصدر والتّرميز الوجهة يجب أن يكونا إما سلسلةً نصّيةً أو كائنًا من الصّنف <code>[[Ruby/Encoding|Encoding]]</code>.

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

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

* '''<code>xml => :attr</code>''': هروب على شكل <code>AttValue</code>. توضع النتيجة بعد التحويل بين علامتي اقتباس بالشكل "…". يمكن أن تستخدم هذه الصيغة على أنها قيمة خاصيّة <code>HTML</code>.
** <code>'‎&' -> '&amp;amp;‎'</code>
** <code>'‎<' -> '&amp;lt;‎'</code>
** <code>'‎>' -> '&amp;gt;‎'</code>
** <code>'‎“' -> '&amp;quot;‎'</code>
** المحارف غير المعرفة في التابع <code>CharRef <- destination_encoding</code> الست عشري مثل <code>‎&#xHH</code>.
وتكون بنية الخيار الممرر إلى التابع عندما يكون من النوع <code>integer</code> بالشكل:
*  <code>Encoding::Converter::INVALID_REPLACE</code>
* <code> Encoding::Converter::UNDEF_REPLACE</code>
* <code> Encoding::Converter::UNDEF_HEX_CHARREF</code>
* <code> Encoding::Converter::UNIVERSAL_NEWLINE_DECORATOR</code>
* <code> Encoding::Converter::CRLF_NEWLINE_DECORATOR</code>
* <code> Encoding::Converter::CR_NEWLINE_DECORATOR</code>
* <code> Encoding::Converter::XML_TEXT_DECORATOR</code>
* <code> Encoding::Converter::XML_ATTR_CONTENT_DECORATOR</code>
* <code> Encoding::Converter::XML_ATTR_QUOTE_DECORATOR</code>

== البنية العامة ==
<syntaxhighlight lang="ruby">
Encoding::Converter.new(source_encoding, destination_encoding)

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

Encoding::Converter.new(convpath)


</syntaxhighlight>

== المعاملات ==
<code>source_encoding</code>

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

<code>destination_encoding</code>

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

<code>opt</code>

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

<code>convpath</code>

يجب أن يكون هذا المعامل مصفوفة (array)، ويمكن أن تحتوي على:
* عنصرين يمثلان كائن التّرميز أو اسمه، أو
* سلاسل نصّية تمثّل أسماء المزخرِفات (decorator names).

== أمثلة ==
مثالٌ عن استخدام التابع new:<syntaxhighlight lang="ruby">
# 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>]]

</syntaxhighlight>

== انظر أيضًا ==
* التّابع <code>[[Ruby/Encoding/Converter/last error|last_error]]</code>: يُعيد الكائن <code>exception</code> عند حصول خطأٍ في آخر عملية تحويل أو يعيد القيمة <code>nil</code> إن لم يحصل أي خطأ.
* التّابع <code>[[Ruby/Encoding/Converter/destination encoding|destination_encoding]]</code>: يُعيد التّرميز الوجهة على شكل كائنٍ من الصنف <code>[[Ruby/Encoding|Encoding]]</code>.
* التّابع <code>[[Ruby/Encoding/Converter/source encoding|source_encoding]]</code>: يُعيد الترميز المصدر على شكل كائن من الصنف [[Ruby/Encoding|<code>Encoding</code>]].

== مصادر ==
* [http://ruby-doc.org/core-2.5.1/Encoding/Converter.html#method-c-new صفحة التابع new في الصنف Encoding::Converter في توثيق روبي الرسمي.]
[[تصنيف:Ruby]]
[[تصنيف:Ruby Method]]
[[تصنيف:Ruby Encoding]]
[[تصنيف:Ruby Encoding::Converter]]