Ruby/Hash

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

ترتَّب وتحصى القيم في النوع Hash بنفس الترتيب الذي أُدرِجت فيه مفاتيحها المقابلة.

يمكن إنشاء جدول Hash بسهولة باستخدام شكله الصريح:

grades = { "Jane Doe" => 10, "Jim Doe" => 6 }

يسمح الجدول Hash باستعمال الرموز كصيغة بديلة للمفاتيح. انظر مثلًا إلى المثال التالي:

options = { :font_size => 10, :font_family => "Arial" }

و يمكن أن تُكتب أيضًا بالشكل التالي:

options = { font_size: 10, font_family: "Arial" }

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

options[:font_size]  # => 10

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

grades = Hash.new
grades["Dorothy Doe"] = 9

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

grades = Hash.new(0)

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

grades = {"Timmy Doe" => 8}
grades.default = 0

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

puts grades["Jane Doe"] # => 0

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

يعد النوع Hash طريقةً سهلةً لتمثيل هياكل البيانات مثل:

books         = {}
books[:matz]  = "The Ruby Programming Language"
books[:black] = "The Well-Grounded Rubyist"

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

Person.create(name: "John Doe", age: 27)

def self.create(params)
  @name = params[:name]
  @age  = params[:age]
end

المفاتيح في النوع Hash

يُشير كائنان إلى نفس المفتاح في الجدول Hash عندما تكون القيمة المرتبطة بأحدهما مماثلة ومساوية للقيمة المرتبطة بالمفتاح الآخر.

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

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

class Book
  attr_reader :author, :title

  def initialize(author, title)
    @author = author
    @title = title
  end

  def ==(other)
    self.class === other and
      other.author == @author and
      other.title == @title
  end

  alias eql? ==

  def hash
    @author.hash ^ @title.hash # XOR
  end
end

book1 = Book.new 'matz', 'Ruby in a Nutshell'
book2 = Book.new 'matz', 'Ruby in a Nutshell'

reviews = {}

reviews[book1] = 'Great reference!'
reviews[book2] = 'Nice and compact!'

reviews.length #=> 1

انظر أيضًا التابع Object.hash والتابع Object.eql?‎.

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

Hash[]‎

ينشئ جدول Hash جديد ويضع فيه الكائنات المعطاة.

new

ينشئ جدول Hash جديد فارغ ثم يعيده.

try_convert

يحاول تحويل الكائن المُمرَّر إليه إلى النوع Hash باستخدام التابعto_hash. 

توابع النسخة العامة

>

يعيد القيمة true إذا كان الكائن Hash الواقع على يساره مجموعةً فرعيةً من الكائن الواقع على يمينه.

=>

يعيد القيمة true إذا كان الكائن Hash الواقع على يساره مجموعةً فرعيةً من الكائن الواقع على يمينه أو يساويه تمامًا.

==

يتحقق من تساوي كائنين من النوع Hash.

<

يعيد القيمة true إذا كان الكائن الواقع على يمينه مجموعةً فرعيةً من الكائن الواقع على يساره.

=<

يعيد المعامل =< القيمة true إذا كان الكائن الواقع على يمينه مجموعةً فرعيةً من الكائن الواقع على يساره أو يساويه تمامًا.

[]

يجلب القيمة المقابلة لمفتاح معين في الجدول Hash المعطى.

=[]

يربط عند استدعائه بالشكل hsh[key] = value القيمة value المعطاة بالمفتاحkey في الجدول Hash.

any?‎

يمرر كل زوج من مفتاح/قيمة من أزواج الكائن Hash المعطى إلى كتلة معينة ثم يعيد القيمة true إن أعادت الكتلة قيمة غير القيمة false أو nil.

assoc

يبحث ضمن الكائن Hash عن طريق موازنة الكائن المُمرَّر إليه بمفاتيحه باستخدام المعامل == ثم يعيد الزوج قيمة-مفتاح (مصفوفة من عنصرين) أو nil إذا لم يعثر على أي تطابق.

clear

يزيل جميع الأزواج قيمة-مفتاح من الكائن Hash الذي استدعي معه.

compact

يعيد كائن Hash جديد يحوي جميع الأزواج قيم/مفاتيح للكائن الذي استدعي معه باستثناء الأزواج المعدومة (أي ذات القيمة nil).

compact!

يزيل جميع الأزواج قيمة/مفتاح المعدومة (أي ذات القيمة nil) من الكائن الذي استدعي معه.

compare_by_identity

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

compare_by_identity?‎

يتحقق إذا كان الكائن Hash الذي استدعي معه سيقارن مفاتيحه بواسطة مُعرِّفاتهم.

default

يعيد القيمة الافتراضية للمفتاح المُمرَّر إليه؛ أي يعيد القيمة التي سيعيدها الكائنHash إذا كان المفتاح غير موجود فيه.

=default

يضبط عند استدعائه بالشكل default = obj القيمة الافتراضية obj وهي القيمة التي ستُعاد لمفتاح غير موجود في الكائن Hash.

default_proc

يعيد الكتلة التي استُدعي التابع new معها عند إنشاء الكائن Hashالمعطى، وإلا سيُعيد القيمة nil.

=default_proc

يضبط إن استدعي بالشكل default_proc = proc_obj القيمة الافتراضية للكتلة التي ستُنفَّذ عند فشل أية عملية بحث عن مفتاح للكائن Hash المعطى.

delete

يحذف زوجًا ذا مفتاح محدَّد ويعيد قيمته من الكائن Hash الذي استدعي معه.

delete_if

يحذف كل زوج قيمة-مفتاح يحقق شرطًا معيَّنًا من أزواج الكائن Hash المعطى.

dig

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

each

يستدعي الكتلة المعطاة مرةً واحدةً لكل مفتاح من مفاتيح أزواج الكائن Hash الذي استدعي معه بعد تمرير مفتاح وقيمة الأزواج إليها.

each_key

يستدعي الكتلة المعطاة مرةً واحدةً لكل مفتاح من مفاتيح أزواج الكائن Hash الذي استدعي معه بعد تمرير مفتاح كل زوج إليها.

each_pair

يستدعي الكتلة المعطاة مرةً واحدةً لكل مفتاح من مفاتيح أزواج الكائن Hash الذي استدعي معه بعد تمرير مفتاح وقيمة الأزواج إليها.

each_value

يستدعي الكتلة المعطاة مرةً واحدةً لكل مفتاح من مفاتيح أزواج الكائن Hash الذي استدعي معه بعد تمرير قيمة كل زوج إليها.

empty?‎

يتحقق إذا كان الكائن Hash الذي استدعي معه فارغًا أي لا يحتوي على أية أزواج.

eql?‎

يتحقق إذا كان كائنان من نفس النوع (النوع Hash) ولهما نفس المحتوى. لا يؤخذ ترتيب الأزواج بالحسبان.

fetch

يعيد قيمة من الكائن Hash لمفتاح معين.

fetch_values

يعيد مصفوفة تحتوي على القيم المقترنة بالمفاتيح المعطاة.

flatten

يعيد مصفوفة جديدة والتي تكون تسطيح أحادي الأبعاد للكائن Hash الذي استدعي معه.

has_key?‎

يتحقق إذا كان مفتاحٌ معيَّن موجودًا في الكائن Hash المعطى.

has_value?‎

يعيد إذا كانت قيمةٌ معيَّنةٌ موجودةً في الكائن Hash المعطى ومرتبطة بمفتاح.

hash

يحسب الشيفرة hash للكائن Hash المستدعى معها.

include?‎

يعيد إذا كان مفتاحٌ معيَّن موجودًا في الكائن Hash المعطى.

inspect

يعيد محتوى الكائن Hash الذي استدعي معه في سلسلة نصية.

invert

يعيد كائن جديد من النوع Hash يحوي قيم الكائن Hash الذي استدعي معه كمفاتيح ومفاتيحه كقيم فيه.

keep_if

يبقي كل زوج قيمة-مفتاح يحقق شرطًا معيَّنًا من أزواج الكائن Hash المعطى.

key

يعيد المفتاح المقابل لقيمة معيَّنة في الكائن Hash الذي استدعي معه.

key?‎

يتحقق إذا كان مفتاحٌ محدَّدٌ موجودًا في الكائن Hash المستدعى معه.

keys

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

length

يعيد عدد الأزواج قيمة-مفتاح الموجودة في الكائن Hash الذي استدعي معه.

member?‎

يتحقق إذا كان مفتاحٌ معيَّن موجودًا في الكائن Hash المعطى.

merge

يدمج كائنين من النوع Hash مع بعضهما بعضًا في كائن جديد من النوع Hash ثم يعيده.

merge!‎

يضيف محتويات الكائن Hash الذي مُمرِّر إليه إلى الكائن الذي استدعي معه.

rassoc

يبحث خلال الكائن Hash الذي استدعي معه عن طريق مقارنة القيمة التي مُمرِّرت إليه مع قيم ذلك الكائن باستخدام المعامل == ثم يعيد أول زوج قيمة-مفتاح متطابق.

rehash

يعيد بناء الكائن Hash استنادًا إلى القيم الحالية لكل مفتاح.

reject

يعيد كائن جديد من النوع Hash يتكون من الأزواج التي ترفضها الكتلة المعطاة.

reject!‎

يحذف الأزواج التي ترفضها الكتلة المعطاة من الكائن Hash الذي استدعي معه. 

replace

يُبدِّل محتويات الكائن المُمرَّر إليه مكان محتويات الكائن Hash الذي استدعي معه.

select

يعيد كائن جديد من النوع Hash يتكون من العناصر التي تعيد الكتلة المعطاة معها القيمة true.

select!‎

يحذف الأزواج التي تقبلها الكتلة المعطاة من الكائن Hash الذي استدعي معه. 

shift

يزيل زوجًا من قيمة-مفتاح من الكائن Hash الذي استدعي معه ويعيده في مصفوفة، أو يعيد القيمة الافتراضية لهذا الكائن إذا كان فارغًا.

size

يعيد عدد الأزواج القيمة-المفتاح الموجودة في الكائن Hash الذي استدعي معه.

slice

يعيد كائنًا من النوع Hash يحتوي فقط على مفاتيح محدَّدة وقيمها.

store

يربط قيمة محددة مع مفتاح محدد في الكائن Hash الذي استدعي معه.

to_a

يحول الكائن Hash الذي استدعي معه إلى مصفوفة متشعبة من المصفوفات [ key, value ].

to_h

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

to_hash

يعيد الكائن Hash المعطى نفسه.

to_s

يعيد محتوى الكائن Hash الذي استدعي معه في سلسلة نصية.

transform_keys

يعيد كائن جديد من النوع Hash مع ناتج تنفيذ الكتلة المعطاة مرةً واحدةً لكل مفتاح من مفاتيح الكائن Hash الذي استدعي معه.

transform_keys!‎

يستدعي الكتلة المعطاة مرةً واحدةً لكل مفتاح من مفاتيح الكائن Hash المعطى، ويستبدل به المفتاح الجديد الذي تعيده الكتلة، ثم يعيد هذا الكائن.

transform_values

يعيد كائن جديد من النوع Hash مع ناتج تنفيذ الكتلة المعطاة مرةً واحدةً لكل قيمة من قيم الكائن Hash الذي استدعي معه.

transform_values!‎

يستدعي الكتلة المعطاة مرةً واحدةً لكل قيمة من قيم الكائن Hash المعطى، ويستبدل به القيمة الجديد التي تعيدها الكتلة، ثم يعيد هذا الكائن. لا يُغيّر هذا التابع المفاتيح.

update

يضيف محتويات الكائن المُمرَّر إليه إلى الكائن Hash الذي استدعي معه.

value?‎

يتحقق إذا كانت القيمة المُمرَّرة إليه موجودةً ومرتبطةً بمفتاح ما في الكائن Hash المعطى.

values

يعيد مصفوفة جديدة تحوي قيم الكائن Hash الذي استدعي معه.

values_at

يعيد مصفوفةً تحتوي على القيم المرتبطة بمفاتيح محدَّدة من الكائن Hash الذي استدعي معه.

ملاحظات إضافية

تأتي بعض التوابع التي يستخدمها البعض مع الكائن Hash من الوحدة Enumerable.

إذا لم تعثر على ما تبحث عنه في هذا التوثيق، فاطلع على توثيق Enumerable.

مصادر

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