التجزئة Hash في روبي

التجزئة Hash

هي مجموعة تشبه القاموس وتتكون من مفاتيح فريدة وقيمها. كما تسمى أيضا المصفوفات الترابطية، فهي تشبه المصفوفات Arrays، ولكن بينما تستخدم Array الأعداد الصحيحة كفهرس، تسمح Hash باستخدام أي من أنواع الكائنات.

تُرقِّم التجزئات قيمَها بنفس الترتيب الذي أُدرِجت فيه مفاتيحها المقابلة.

يمكن أن تُنشأ Hash بسهولة باستخدام شكلها الضمني:

تسمح التجزئات بصياغة بديلة للمفاتيح التي تكون رموزًا. بدلًا من

و يمكن أن تُكتب:

كل مفتاح مُسمَّي هو رمز يمكن الوصول إليه في التجزئة:

ويمكن أيضا أن تنشأ Hash من خلال التابع ‎::new:

تتخذ التجزئات قيمة افتراضية تُعاد عند الوصول إلى مفاتيح غير موجودة في التجزئة. إذا لم تتعين قيمة افتراضية تُستخدم nil. ويمكن تعيين القيمة الافتراضية بإرسالها كوسيط إلى ‎::new:

أو باستخدام التابع default=‎:

يتطلب الوصول إلى قيمة ما في Hash استخدام مفتاحها:

الاستخدامات الشائعة

تُعد التجزئات طريقة سهلة لتمثيل هياكل البيانات، مثل

كما يشيع استخدام التجزئات كطريقة للحصول على معاملات مسماة في الدوال. لاحظ أنه لا توجد أقواس مستخدمة أدناه. إذا كانت التجزئة هي الوسيط الأخير في استدعاء التابع، لا يلزم استخدام أقواس، وبالتالي إنشاء واجهة مُرتَّبة جدًا:

مفاتيح Hash

يُشير كائنان إلى نفس مفتاح التجزئة عندما تكون قيمتا hash الخاصة بهما متطابقة ويكون الكائنان eql?‎ لبعضهم البعض.

قد يستخدم صنف معرف من قِبَل المستخدم كمفتاح تجزئة إذا أُبطِل التابعَيْن hash و eql?‎ لتوفير سلوك ذو معنى. بشكل افتراضي، تشير المثيلات المنفصلة إلى مفاتيح تجزئة منفصلة.

ويستند التطبيق النموذجي للتجزئة hash على بيانات الكائن، بينما يُعين عادةً اسم مستعار للتابع eql?‎ يشير إلى التابع المُبطِل ==:

انظر أيضا Object#hash و Object#eql?‎

توابع الصنف العام

Hash[ key, value, ... ] → new_hash

Hash[ [ [key, value], ... ] ] → new_hash

Hash[ object ] → new_hash

إنشاء تجزئة جديدة ممتلئة بالكائنات المعطاة.

على غرار القيمة الحرفية { key => value, ... }. في الشكل الأول، تأتي المفاتيح والقيم في أزواج، لذلك يجب أن يكون هناك عدد زوجي من الوسائط.

يُمرر في الشكلين الثاني والثالث وسيطٌ واحدٌ ويكون إما مصفوفة من أزواج القيمة-المفتاح أو كائن قابل للتحويل إلى تجزئة.

new → new_hash

new(obj) → new_hash

new {|hash, key| block } → new_hash

إعادة تجزئة جديدة فارغة. إذا وصل بعد ذلك مفتاحٌ لا يتوافق مع إدخال تجزئة إلى هذه التجزئة، تعتمد القيمة المُعادة على نمط new يستخدم لإنشاء التجزئة. في الشكل الأول، يُعيد الوصول nil. إذا حُدِد obj ، سيُستخدم هذا الكائن وحده لكافة القيم الافتراضية. إذا حُدِدت كتلة، ستُستدعى مع كائن التجزئة والمفتاح، و يجب إعادة القيمة الافتراضية. ومن مسؤولية الكتلة تخزين القيمة في التجزئة إذا لزم الأمر.

try_convert(obj) → hash or nil

محاولة تحويل obj إلى تجزئة باستخدام التابع ‎#to_hash. إعادة التجزئة المُحوَّلة أو nil إذا تعذر تحويل obj لأي سبب.

توابع المثيل العام

hash < other → true or false

يُعيد true إذا كانت hash مجموعة فرعية من other.

hash <= other → true or false

إعادة true إذا كانت hash مجموعة فرعية من other أو تساوي other.

hsh == other_hash → true or false

المساواة--تتساوى تجزئتان إذا كان كل منهما يحتوي على نفس العدد من المفاتيح وإذا كان كل زوج القيمة-المفتاح يساوي (وفقًا Object#==‎) العناصر المناظرة في التجزئة الأخرى.

لا يقارن ترتيب كل التجزئات.

hash > other → true or false

إعادة true إذا كان other مجموعة فرعية من hash.

hash >= other → true or false

إعادة true إذا كان other مجموعة فرعية من hash أو يساوي hash.

hsh[key] → value

مرجع العنصر — يسترد كائن value المقابل لكائن key. إذا لم يُعثر عليه، تُعيد القيمة الافتراضية (راجع Hash::new لمزيد من التفاصيل).

hsh[key] = value → value

تعيين عنصر

يربط القيمة value المُعطاة مع المفتاح key المُعطي.

لا يجب تغيير قيمة key أثناء استخدامه كمفتاح (ستكرر السلاسل غير المجمدة unfrozen المُمررة كمفتاح وتُجمَّد).

any? [{ |(key, value)| block }] → true or false

راجع أيضًا Enumerable#any?‎

assoc(obj) → an_array or nil

البحث خلال التجزئة عن طريق مقارنة obj بالمفتاح باستخدام ==. يعيد زوج القيمة-االمفتاح (مصفوفة من عنصرين) أو nil إذا لم يعثر على أي تطابق. راجع Array#assoc.

clear → hsh

يزيل جميع أزواج القيمة-المفتاح من hsh.

compact → new_hash

يُعيد تجزئة جديدة مع إزالة أزواج القيم/المفاتيح الصفرية

compact! → hsh or nil

يزيل جميع قيم hsh من التجزئة. إعادة صفر إذا لم يُجرى أية تغييرات، وإلا يُعيد التجزئة.

compare_by_identity → hsh

يجعل hsh يقارن مفاتيحه بواسطة مُعرِّفه، أي إنها سوف تعتبر نفس الكائنات على أنها نفس المفاتيح.

compare_by_identity? → true or false

إعادة true إذا كانت hsh ستقارن مفاتيحها بواسطة مُعرِّفهم. راجع أيضا Hash#compare_by_identity.

default(key=nil) → obj

إعادة القيمة الافتراضية، القيمة مُعادة بواسطة hsh إذا كان key غير موجود في hsh. راجع أيضًا Hash::new and Hash#default=‎.

default = obj → obj

تعيين القيمة الافتراضية، القيمة المُعادة لمفتاح غير موجود في التجزئة. ليس من الممكن ضب القيمة الافتراضية على Proc التي ستنفذ على كل بحث عن مفتاح.

default_proc → anObject

إذا استُدعي Hash::new مع كتلة، سيُعيد هذه الكتلة، وإلا سيُعيد nil.

default_proc = proc_obj أو صفر

تعيين proc الافتراضية التي ستُنفَّذ عند فشل أي بحث عن مفتاح.

delete(key) → value

delete(key) {| key | block } → value

حذف زوج القيمة-المفتاح وإعادة القيمة من hsh والذي يكون مفتاحها key. ويُعيد nil إذا كان المفتاح غير موجود. إذا توفرت كتلة الشيفرة البرمجية الاختيارية وكان المفتاح غير موجود، يُمرر المفتاح وتُعاد نتيجة block.

delete_if {| key, value | block } → hsh

delete_if → an_enumerator

حذف كل أزواج القيمة-المفتاح من hsh التي تُقيَّم لها block بالقيمة true.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

dig(key, ...) → object

استخراج القيمة المتداخلة المحددة بواسطة تسلسل كائنات key عن طريق استدعاء dig في كل خطوة، وإعادة nil إذا كانت أي خطوة متوسطة nil.

each {| key, value | block } → hsh

each_pair {| key, value | block } → hsh

each → an_enumerator

each_pair → an_enumerator

استدعاء block مرة واحدة لكل مفتاح في hsh، وتمرير زوج القيمة-المفتاح كمعاملات.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

يُنتِج:

each_key {| key | block } → hsh

each_key → an_enumerator

استدعاء block مرة واحدة لكل مفتاح في hsh، وتمرير المفتاح كمعامل.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

يُنتِج:

each_pair {| key, value | block } → hsh

each_pair → an_enumerator

استدعاء block مرة واحدة لكل مفتاح في hsh، وتمرير زوج القيمة-المفتاح كمعاملات.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

يُنتِج:

each_value {| value | block } → hsh

each_value → an_enumerator

استدعاء block مرة واحدة لكل مفتاح في hsh، وتمرير المفتاح كمعامل.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

يُنتِج:

empty? → true or false

إعادة true إذا كانت hsh لا تحتوي على أزواج القيمة-المفتاح.

eql?(other) → true or false

إعادة true إذا كان كلٌ من hash و other تجزئتين بنفس المحتوى. لا يقارن ترتيب كل التجزئات.

fetch(key [, default] ) → obj

fetch(key) {| key | block } → obj

إعادة قيمة من التجزئة لمفتاح معين. إذا كان المفتاح غير موجود، هناك عدة خيارات: مع عدم وجود وسائط أخرى، سيُجرى استثناء KeyError، إذا أُعطيَ default، ستُعاد هذه إذا حُدِدت كتلة الشيفرة البرمجية الاختيارية، ثم ستُنفَّذ وتُعاد نتيجتها.

يُظهِر المثال التالي إجراء استثناء إذا كان المفتاح غير موجود ولم تُعطى قيمة افتراضية.

يُنتِج:

fetch_values(key, ...) → array

fetch_values(key, ...) { |key| block } → array

إعادة مصفوفة تحتوي على القيم المقترنة بالمفاتيح المعطاة ولكن تُجرى أيضًا KeyError عند تعذر العثور على أحد المفاتيح. راجع أيضًا Hash#values_at و Hash#fetch.

flatten → an_array

flatten(level) → an_array

إعادة مصفوفة جديدة والتي تكون تسطيح أحادي الأبعاد لهذا التجزئة. أي أن لكل مفتاح أو قيمة تكون مصفوفة، تستخرج عناصرها إلى مصفوفة جديدة. على عكس Array#flatten، لا يُسطِّح هذا التابع بشكل عَودي افتراضيًا. يُحدد الوسيط الاختياري level مستوى عودية التسطح.

has_key?(key) → true or false

إعادة true إذا كان مفتاح معين موجود في hsh.

علمًا بأن include?‎ و member?‎ لا يختبرا تساوي الأعضاء باستخدام == كما تفعل غيرها من العدَّادات.

راجع أيضًا Enumerable#include?‎

has_value?(value) → true or false

إعادة true إذا كانت القيمة المُعطاة موجودة لمفتاح ما في hsh.

hash → integer

حساب رمز التجزئة لهذه التجزئة. سيكون لتجزئتين لهما نفس المحتوى نفس رمز التجزئة (وستقارن باستخدام eql?‎).

راجع أيضًا Object#hash.

include?(key) → true or false

إعادة true إذا كان مفتاح معين موجود في hsh.

علمًا بأن include?‎ و member?‎ لا يختبرا تساوي الأعضاء باستخدام == كما تفعل غيرها من العدَّادات.

راجع أيضًا Enumerable#include?‎

to_s → string

inspect → string

إعادة محتويات هذا التجزئة كسلسلة نصية.

ويُعيَّن له أيضًا الاسم المستعار: to_s.

invert → new_hash

إعادة تجزئة جديدة مُنشأة باستخدام قيم hsh كمفاتيح والمفاتيح كقيم. إذا وُجِد بالفعل مفتاح بنفس القيمة في hsh، سيستخدم آخر واحد مُعرَّف، وستُتجاهل القيم السابقة.

إذا لم يكن هناك مفتاح بنفس القيمة، تكون #invert ذاتية الانعكاس (involutive).

الشرط، ألا يوجد مفتاح بنفس القيمة، ويمكن اختباره بمقارنة حجم التجزئة المقلوبة.

keep_if {| key, value | block } → hsh

keep_if → an_enumerator

حذف كل أزواج القيمة-المفتاح من hsh والتي تقيَّم لها block بالقيمة false.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

key(value) → key

إعادة مفتاح تواجد قيمة معينة. ويُعيد nil إذا كانت القيمة غير موجود.

key?(key) → true or false

إعادة true إذا كان مفتاح معين موجود في hsh.

علمًا بأن include?‎ و member?‎ لا يختبرا تساوي الأعضاء باستخدام == كما تفعل غيرها من العدَّادات.

راجع أيضًا Enumerable#include?‎

keys → array

إعادة مصفوفة جديدة ممتلئة بالمفاتيح من هذه التجزئة. راجع أيضًا Hash#values.

length → integer

إعادة عدد أزواج القيمة-المفتاح في التجزئة.

member?(key) → true or false

إعادة true إذا كان مفتاح معين موجود في hsh.

علمًا بأن include?‎ و member?‎ لا يختبرا تساوي الأعضاء باستخدام == كما تفعل غيرها من العدَّادات.

راجع أيضًا Enumerable#include?‎

merge(other_hash) → new_hash

merge(other_hash){|key, oldval, newval| block} → new_hash

إعادة تجزئة جديدة تحتوي على محتويات other_hash ومحتويات hsh. إذا لم تُحدد أي كتلة، ستكون قيمة العناصر ذات المفاتيح المُكررة هي نفسها من other_hash. وإلا تُحدَد قيمة كل مفتاح مكرر عن طريق استدعاء الكتلة مع المفتاح، وتكون قيمته في hsh وقيمته في other_hash.

merge!(other_hash) → hsh

merge!(other_hash){|key, oldval, newval| block} → hsh

إضافة محتويات other_hash إلى hsh. إذا لم تُحدَد أي كتلة، يُكتب فوق الإدخالات ذات المفاتيح المكررة مع القيم من other_hash، وإلا تُحدَّد قيمة كل مفتاح مكرر عن طريق استدعاء الكتلة مع المفتاح وقيمته في hsh وقيمته في other_hash.

rassoc(obj) → an_array or nil

البحث خلال التجزئة عن طريق مقارنة obj بالقيمة باستخدام ==. إعادة أول زوج القيمة-المفتاح (مصفوفة من عنصرين) يتطابق. راجع أيضًا Array#rassoc.

rehash → hsh

إعادة بناء التجزئة استنادًا إلى قيم التجزئة الحالية لكل مفتاح. إذا تغيرت قيم كائنات المفاتيح منذ إدراجها، سيعيد هذا التابع فهرسة hsh. إذا اُستدعيَ Hash#rehash بينما يجتاز مُكرِّر التجزئة، سينطلق RuntimeError في المُكرِّر.

reject {|key, value| block} → a_hash

reject → an_enumerator

إعادة تجزئة جديدة تتكون من العناصر التي تعيد الكتلة لها false.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

reject! {| key, value | block } → hsh or nil

reject! → an_enumerator

يعادل Hash#delete_if، ولكن يُعيد nil إذا لم تُجرى أية تغييرات.

replace(other_hash) → hsh

استبدال محتويات hsh بمحتويات other_hash.

select {|key, value| block} → a_hash

select → an_enumerator

إعادة تجزئة جديدة تتكون من العناصر التي تعيد الكتلة لها true.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

select! {| key, value | block } → hsh or nil

select! → an_enumerator

يعادل Hash#keep_if، ولكن يُعيد nil إذا لم تُجرى أية تغييرات.

shift → anArray or obj

يزيل زوج القيمة-المفتاح من hsh ويقوم بإعادتها كمصفوفة من العنصرين [ key, value ]، أو القيمة الافتراضية للتجزئة إذا كانت التجزئة فارغة.

size → integer

إعادة عدد أزواج القيمة-المفتاح في التجزئة.

slice(*keys) → a_hash

إعادة تجزئة تحتوي فقط على المفاتيح المُعطاة وقيمها.

store(key, value) → value

تعيين عنصر

يربط القيمة value المُعطاة مع المفتاح key المُعطي.

لا يجب تغيير قيمة key أثناء استخدامه كمفتاح (ستكرر السلاسل غير المجمدة unfrozen المُمررة كمفتاح وتُجمَّد).

to_a → array

تحويل hsh إلى مصفوفة متداخلة من المصفوفات [ key, value ].

to_h → hsh or new_hash

إعادة self. إذا استُدعي علي صنف فرعي من Hash، تحوِّل المُتلقي إلى كائن Hash.

to_hash => hsh

إعادة self.

to_proc()‎

to_s()‎

اسم المستعار لـ inspect

transform_keys {|key| block } → new_hash

transform_keys → an_enumerator

إعادة تجزئة جديدة مع نتائج تشغيل الكتلة مرة واحدة لكل مفتاح. لا يُغيّر هذا التابع القيم.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

transform_keys! {|key| block } → hsh

transform_keys! → an_enumerator

استدعاء الكتلة المعطاة مرة واحدة لكل مفتاح في hsh، واستبداله بالمفتاح الجديد الذي تعيده الكتلة، ثم تُعيد hsh. لا يُغيّر هذا التابع القيم.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

transform_values {|value| block } → new_hash

transform_values → an_enumerator

إعادة تجزئة جديدة مع نتائج تشغيل الكتلة مرة واحدة لكل قيمة. لا يُغيّر هذا التابع المفاتيح.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

transform_values! {|value| block } → hsh

transform_values! → an_enumerator

استدعاء الكتلة المعطاة مرة واحدة لكل قيمة في hsh، واستبداله بالقيمة الجديدة التي تعيدها الكتلة، ثم تُعيد hsh. لا يُغيّر هذا التابع المفاتيح.

إذا لم تُعطَى كتلة، يُعاد عدَّاد بدلًا من ذلك.

update(other_hash) → hsh

update(other_hash){|key, oldval, newval| block} → hsh

إضافة محتويات other_hash إلى hsh. إذا لم تُحدَد أي كتلة، يُكتب فوق الإدخالات ذات المفاتيح المكررة مع القيم من other_hash، وإلا تُحدَّد قيمة كل مفتاح مكرر عن طريق استدعاء الكتلة مع المفتاح وقيمته في hsh وقيمته في other_hash.

value?(value) → true or false

إعادة true إذا كانت القيمة المُعطاة موجودة لمفتاح ما في hsh.

values → array

إعادة مصفوفة جديدة ممتلئة بالقيم من hsh. راجع أيضًا Hash#keys.

values_at(key, ...) → arrayclick to toggle source

إعادة مصفوفة تحتوي على القيم المرتبطة بالمفاتيح المُعطاة. راجع أيضًا Hash.select.

مصادر

• صفحة Hash في توثيق روبي الرسمي.