الفرق بين المراجعتين ل"Ruby/Encoding/Converter/primitive convert"
(أنشأ الصفحة ب'{{DISPLAYTITLE:التابع Encoding::Converter.primitive_convert في روبي}} يحوّل التابع <code>primitive_convert</code> ترميز جميع المحت...') |
ط |
||
(3 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة) | |||
سطر 1: | سطر 1: | ||
− | {{DISPLAYTITLE:التابع Encoding::Converter.primitive_convert في روبي}} | + | {{DISPLAYTITLE:التابع <code>Encoding::Converter.primitive_convert</code> في روبي}} |
− | |||
يحوّل التابع <code>primitive_convert</code> ترميز جميع المحتويات المخزَّنة مؤقتًا (buffer) في مخزن معين أو مجال محدد منها -من ترميز المصدر إلى ترميز الوجهة- ثم يضع الناتج في مخزَّن محدَّد. | يحوّل التابع <code>primitive_convert</code> ترميز جميع المحتويات المخزَّنة مؤقتًا (buffer) في مخزن معين أو مجال محدد منها -من ترميز المصدر إلى ترميز الوجهة- ثم يضع الناتج في مخزَّن محدَّد. | ||
− | يحذف التّابع <code>primitive_convert</code> الجزء المحوّل من المخزن source_buffer المصدر، ويضعه في المخزن destination_buffer الوجهة أو يخزنِّه مؤقتًا في كائن من الصنف<code>[[Ruby/Encoding/Converter|Encoding::Converter]]</code> بعد تحويله بالتأكيد. | + | يحذف التّابع <code>primitive_convert</code> الجزء المحوّل من المخزن <code>source_buffer</code> المصدر، ويضعه في المخزن <code>destination_buffer</code> الوجهة أو يخزنِّه مؤقتًا في كائن من الصنف<code>[[Ruby/Encoding/Converter|Encoding::Converter]]</code> بعد تحويله بالتأكيد. |
يوقف التّابع <code>primitive_convert</code> عملية التحويل عند تحقّق أحد الشّروط التالية: | يوقف التّابع <code>primitive_convert</code> عملية التحويل عند تحقّق أحد الشّروط التالية: | ||
− | * وجود سلسلة بايت غير صالحة (invalid_byte_sequence:) في المخزن source_buffer المصدر | + | * وجود سلسلة بايت غير صالحة (<code>invalid_byte_sequence:</code>) في المخزن <code>source_buffer</code> المصدر . يُعيد التابعان <code>[[Ruby/Encoding/Converter/primitive errinfo|primitive_errinfo]]</code> و <code>[[Ruby/Encoding/Converter/last error|last_error]]</code> تفاصيل الخطأ. |
− | * نهايةٌ غير متوقعةٍ (incomplete_input:) للمخزن source_buffer المصدر، إذ يحدث هذا فقط عندما يكون partial_input: غير محدد. يُعيد التابعان <code>[[Ruby/Encoding/Converter/primitive errinfo|primitive_errinfo]]</code> و<code>[[Ruby/Encoding/Converter/last error|last_error]]</code>تفاصيل الخطأ. | + | * نهايةٌ غير متوقعةٍ (<code>incomplete_input:</code>) للمخزن <code>source_buffer</code> المصدر، إذ يحدث هذا فقط عندما يكون <code>partial_input:</code> غير محدد. يُعيد التابعان <code>[[Ruby/Encoding/Converter/primitive errinfo|primitive_errinfo]]</code> و <code>[[Ruby/Encoding/Converter/last error|last_error]]</code> تفاصيل الخطأ. |
− | * محرفٌ غير قابلٍ لإعادة التمثيل (:undefined_conversion) في الترميز الهدف، يُعيد التابعان <code>[[Ruby/Encoding/Converter/primitive errinfo|primitive_errinfo]]</code> و <code>[[Ruby/Encoding/Converter/last error|last_error]]</code> تفاصيل الخطأ. | + | * محرفٌ غير قابلٍ لإعادة التمثيل (<code>:undefined_conversion</code>) في الترميز الهدف، يُعيد التابعان <code>[[Ruby/Encoding/Converter/primitive errinfo|primitive_errinfo]]</code> و <code>[[Ruby/Encoding/Converter/last error|last_error]]</code> تفاصيل الخطأ. |
− | * بعد توليد بعض المخرجات، وقبل انتهاء المدخلات (after_output:)، إذ يحدث هذا فقط عندما يُحدَّد <code>after_output:</code>. | + | * بعد توليد بعض المخرجات، وقبل انتهاء المدخلات (<code>after_output:</code>)، إذ يحدث هذا فقط عندما يُحدَّد <code>after_output:</code>. |
− | * امتلاءالمخزن destination_buffer الوجهة (destination_buffer_full:)، إذ يحدث هذا فقط عندما لا تساوي قيمة المعامل <code>destination_bytesize</code> القيمة <code>nil</code>. | + | * امتلاءالمخزن <code>destination_buffer</code> الوجهة (<code>destination_buffer_full:</code>)، إذ يحدث هذا فقط عندما لا تساوي قيمة المعامل <code>destination_bytesize</code> القيمة <code>nil</code>. |
− | * كون المخزن source_buffer المصدر فارغًا (source_buffer_empty:)، يحدث هذا فقط عندما يُحدّد partial_input:. | + | * كون المخزن <code>source_buffer</code> المصدر فارغًا (<code>source_buffer_empty:</code>)، يحدث هذا فقط عندما يُحدّد <code>partial_input:</code>. |
− | * انتهاء عملية التحويل (finished:). | + | * انتهاء عملية التحويل (<code>finished:</code>). |
== البنية العامة == | == البنية العامة == | ||
+ | <syntaxhighlight lang="ruby"> | ||
primitive_convert(source_buffer, destination_buffer) → symbol | primitive_convert(source_buffer, destination_buffer) → symbol | ||
سطر 23: | سطر 23: | ||
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> مكان ومجال إضافة الناتج المحوَّل في المخزن <code>destination_buffer</code> بدقة. | ||
== المعاملات == | == المعاملات == | ||
− | === 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. القيمة الافتراضية لهذا المعامل هي: | + | يحدد موضع البداية حيث سيُخزَّن الناتج المُحوَّل (بالبايت) بدءًا من بداية المخزن <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 إلى عدم وجود حد أقصى لتخزين الناتج المحول. القيمة الافتراضية لهذا المعامل هي: | + | يحدد أكبر عدد من البايتات التي تمثل المجال الأقصى الذي سيُخزَّن فيه الناتج المُحوَّل في المخزن <code>destination_buffer</code>. يجب أن يكون عدد صحيحًا أو قيمة عدميَّة. تشير القيمة <code>nil</code> إلى عدم وجود حد أقصى لتخزين الناتج المحول. القيمة الافتراضية لهذا المعامل هي: <code>nil</code>، إذا لم يُعطَ. |
− | === opt === | + | === <code>opt</code> === |
− | يجب أن يكون | + | يجب أن يكون <code>nil</code>، أو <code>hash</code>، أو <code>integer</code>. تعني القيمة <code>nil</code> أنه لا يوجد رايات (flags). القيمة الافتراضية لهذا المعامل هي: <code>nil</code>، إذا لم يُعطَ. |
− | العناصر المتاحة لقيمة المعامل opt هي: | + | العناصر المتاحة لقيمة المعامل <code>opt</code> هي: |
− | * إن اسُعمل النوع | + | * إن اسُعمل النوع <code>hash</code>، فيمكن أن يتكون من: |
− | ** partial_input => true: قد يكون المخزن المصدر جزءًا من مصدرٍ أكبر. | + | ** <code>partial_input => true</code>: قد يكون المخزن المصدر جزءًا من مصدرٍ أكبر. |
− | ** after_output => true: يوقف التحويل بعد توليد قسم من المخرجات وقبل انتهاء المدخلات. | + | ** <code>after_output => true</code>: يوقف التحويل بعد توليد قسم من المخرجات وقبل انتهاء المدخلات. |
− | * أما إن استعمل النوع | + | * أما إن استعمل النوع <code>integer</code>، فيمكن أن يتكون من:: |
− | ** Encoding::Converter::PARTIAL_INPUT | + | ** <code>Encoding::Converter::PARTIAL_INPUT</code> |
− | ** Encoding::Converter::AFTER_OUTPUT | + | ** <code>Encoding::Converter::AFTER_OUTPUT</code> |
النتائج المحتملة: | النتائج المحتملة: | ||
− | + | * <code>invalid_byte_sequence:</code> | |
− | < | + | * <code>incomplete_input:</code> |
− | + | * <code>undefined_conversion:</code> | |
− | < | + | * <code>after_output:</code> |
− | + | * <code>destination_buffer_full:</code> | |
− | < | + | * <code>source_buffer_empty:</code> |
− | + | * <code>finished:</code> | |
− | < | ||
− | |||
− | < | ||
− | |||
− | < | ||
− | |||
− | < | ||
== القيم المعادة == | == القيم المعادة == | ||
− | يعاد كائن من النوع 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") | ||
− | |||
ret = ec.primitive_convert(src="pi", dst="", nil, 100) | ret = ec.primitive_convert(src="pi", dst="", nil, 100) | ||
− | |||
p [ret, src, dst] #=> [:finished, "", "\x00p\x00i"] | p [ret, src, dst] #=> [:finished, "", "\x00p\x00i"] | ||
ec = Encoding::Converter.new("UTF-8", "UTF-16BE") | ec = Encoding::Converter.new("UTF-8", "UTF-16BE") | ||
− | |||
ret = ec.primitive_convert(src="pi", dst="", nil, 1) | ret = ec.primitive_convert(src="pi", dst="", nil, 1) | ||
− | |||
p [ret, src, dst] #=> [:destination_buffer_full, "i", "\x00"] | p [ret, src, dst] #=> [:destination_buffer_full, "i", "\x00"] | ||
− | |||
ret = ec.primitive_convert(src, dst="", nil, 1) | ret = ec.primitive_convert(src, dst="", nil, 1) | ||
− | |||
p [ret, src, dst] #=> [:destination_buffer_full, "", "p"] | p [ret, src, dst] #=> [:destination_buffer_full, "", "p"] | ||
− | |||
ret = ec.primitive_convert(src, dst="", nil, 1) | ret = ec.primitive_convert(src, dst="", nil, 1) | ||
− | |||
p [ret, src, dst] #=> [:destination_buffer_full, "", "\x00"] | p [ret, src, dst] #=> [:destination_buffer_full, "", "\x00"] | ||
+ | ret = ec.primitive_convert(src, dst="", nil, 1) | ||
+ | p [ret, src, dst] #=> [:finished, "", "i"] | ||
− | |||
− | + | </syntaxhighlight> | |
== انظر أيضًا == | == انظر أيضًا == | ||
− | * التّابع primitive_errinfo: يُعيد معلوماتٍ مهمّةً حول آخر خطأٍ حدث في مصفوفة مكونة من خمسة عناصر. | + | * التّابع <code>[[Ruby/Encoding/Converter/primitive errinfo|primitive_errinfo]]</code>: يُعيد معلوماتٍ مهمّةً حول آخر خطأٍ حدث في مصفوفة مكونة من خمسة عناصر. |
− | * التّابع asciicompat_encoding: يُعيد التّرميز المتوافق مع ASCII المقابل للترميز المعطى. | + | * التّابع <code>[[Ruby/Encoding/Converter/asciicompat encoding|asciicompat_encoding]]</code>: يُعيد التّرميز المتوافق مع ASCII المقابل للترميز المعطى. |
− | * التّابع destination_encoding: يُعيد التّرميز الوجهة على شكل كائنٍ من الصنف Encoding. | + | * التّابع <code>[[Ruby/Encoding/Converter/destination encoding|destination_encoding]]</code>: يُعيد التّرميز الوجهة على شكل كائنٍ من الصنف <code>[[Ruby/Encoding|Encoding]]</code>. |
− | * التّابع source_encoding: يُعيد الترميز المصدر على شكل كائن من الصنف Encoding. | + | * التّابع <code>[[Ruby/Encoding/Converter/source encoding|source_encoding]]</code>: يُعيد الترميز المصدر على شكل كائن من الصنف <code>[[Ruby/Encoding|Encoding]]</code>. |
− | * التّابع insert_output: يضيف سلسلةً نصيّةً إلى محوِّل التّرميز، إذ سيحويل ترميز هذه السلسلة إلى ترميز الوجهة نفسه وتوضع في نهاية مخرجات عملية التحويل. | + | * التّابع <code>[[Ruby/Encoding/Converter/insert output|insert_output]]</code>: يضيف سلسلةً نصيّةً إلى محوِّل التّرميز، إذ سيحويل ترميز هذه السلسلة إلى ترميز الوجهة نفسه وتوضع في نهاية مخرجات عملية التحويل. |
− | * التّابع finish: يُنهي محوّل الترميز، ويُعيد الجزء الأخير من السلسلة النصيّة التي يحول ترميزها حينذاك. | + | * التّابع <code>[[Ruby/Encoding/Converter/finish|finish]]</code>: يُنهي محوّل الترميز، ويُعيد الجزء الأخير من السلسلة النصيّة التي يحول ترميزها حينذاك. |
== مصادر == | == مصادر == | ||
سطر 108: | سطر 94: | ||
[[تصنيف:Ruby]] | [[تصنيف:Ruby]] | ||
[[تصنيف:Ruby Method]] | [[تصنيف:Ruby Method]] | ||
+ | [[تصنيف:Ruby Encoding]] | ||
[[تصنيف:Ruby Encoding::Converter]] | [[تصنيف:Ruby Encoding::Converter]] |
المراجعة الحالية بتاريخ 10:43، 18 أكتوبر 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
: يُنهي محوّل الترميز، ويُعيد الجزء الأخير من السلسلة النصيّة التي يحول ترميزها حينذاك.