الفرق بين المراجعتين لصفحة: «Ruby/Encoding/Converter/primitive convert»

من موسوعة حسوب
< Ruby‏ | Encoding‏ | Converter
التعديل اللاحق ←
مرئينص الويكي
أنشأ الصفحة ب'{{DISPLAYTITLE:التابع Encoding::Converter.primitive_convert في روبي}} يحوّل التابع <code>primitive_convert</code> ترميز جميع المحت...'
 
طلا ملخص تعديل
سطر 15: سطر 15:


== البنية العامة ==
== البنية العامة ==
<syntaxhighlight lang="ruby">
primitive_convert(source_buffer, destination_buffer) → symbol
primitive_convert(source_buffer, destination_buffer) → symbol


سطر 23: سطر 24:
primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize, opt) → symbol
primitive_convert(source_buffer, destination_buffer, destination_byteoffset, destination_bytesize, opt) → symbol


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


== المعاملات ==
== المعاملات ==


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


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


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


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


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


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


* أما إن استعمل النوع integer، فيمكن أن يتكون من::
* أما إن استعمل النوع <code>integer</code>، فيمكن أن يتكون من::
** Encoding::Converter::PARTIAL_INPUT
** Encoding::Converter::PARTIAL_INPUT
** Encoding::Converter::AFTER_OUTPUT
** Encoding::Converter::AFTER_OUTPUT
النتائج المحتملة:
النتائج المحتملة:
 
* invalid_byte_sequence:
<nowiki>:</nowiki>invalid_byte_sequence
* incomplete_input:
 
* undefined_conversion:
<nowiki>:</nowiki>incomplete_input
* after_output:
 
* destination_buffer_full:
<nowiki>:</nowiki>undefined_conversion
* source_buffer_empty:
 
* finished:
<nowiki>:</nowiki>after_output
 
<nowiki>:</nowiki>destination_buffer_full
 
<nowiki>:</nowiki>source_buffer_empty
 
<nowiki>:</nowiki>finished


== القيم المعادة ==
== القيم المعادة ==
يعاد كائن من النوع symbol.
يعاد كائن من النوع <code>symbol</code>.


== أمثلة ==
== أمثلة ==
مثالٌ عن استخدام التابع primitive_convert:
مثالٌ عن استخدام التابع <code>primitive_convert</code>:<syntaxhighlight lang="ruby">
 
ec = Encoding::Converter.new("UTF-8", "UTF-16BE")
ec = Encoding::Converter.new("UTF-8", "UTF-16BE")


سطر 95: سطر 89:


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


== انظر أيضًا ==
== انظر أيضًا ==

مراجعة 17:33، 9 أكتوبر 2018


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

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Ruby/Encoding/Converter/primitive_convert&oldid=19328»