الخرائط Map في Golang: الإنشاء وفحص المفاتيح والمرور والترتيب والحذف

إنشاء خريطة واستخدامها

يُكتب نوع الخريطة (map) بالشكل map[KeyType]ValueType. أنشئ واحدة بحرفية أو بـ make، ثم اقرأ واكتب واحذف بالمفتاح.

package main

import "fmt"

func main() {
	ages := map[string]int{
		"ana": 31,
		"bob": 25,
	}

	ages["cy"] = 40          // insert
	ages["bob"] = 26         // update
	fmt.Println(ages["ana"]) // read
	fmt.Println(len(ages))   // number of entries

	delete(ages, "ana")
	fmt.Println(ages) // fmt prints maps with keys sorted

	counts := make(map[rune]int)
	for _, r := range "hello" {
		counts[r]++ // missing keys start at zero
	}
	fmt.Println(counts['l'], counts['z'])
}

المخرجات:

31
3
map[bob:26 cy:40]
2 0

تظهر هنا ميزتان مريحتان. قراءة مفتاح مفقود تعيد القيمة الصفرية لنوع القيمة (counts['z'] تساوي 0)، وهذا يجعل العدّ بـ m[k]++ يعمل دون أي تجهيز. وتطبع fmt الخرائط بمفاتيح مرتّبة، وهذا مفيد لتتبّع الأخطاء لكنه لا يقول شيئًا عن ترتيب المرور.

تأخذ make(map[K]V, n) تلميحًا اختياريًا للحجم. تحجز مسبقًا مكانًا لنحو n مدخلًا؛ وبخلاف الشرائح لا سعة للخريطة يمكنك قراءتها.

التحقّق من وجود مفتاح: comma-ok

لأن المفتاح المفقود يُقرأ كقيمة صفرية، لا تستطيع m[k] == 0 التمييز بين "غائب" و"مخزّن كـ 0". استخدم الصيغة ذات القيمتين:

package main

import "fmt"

func main() {
	stock := map[string]int{"apple": 0, "pear": 12}

	if n, ok := stock["apple"]; ok {
		fmt.Println("apple is listed, quantity", n)
	}

	if _, ok := stock["kiwi"]; !ok {
		fmt.Println("kiwi is not listed")
	}

	fmt.Println(stock["apple"] == stock["kiwi"]) // both 0: indistinguishable without ok
}

الشكل if v, ok := m[k]; ok { ... } يحصر v وok داخل if. وهو من أشيع الأسطر في شيفرات Go.

حذف المدخلات

تزيل delete(m, key) المدخل. حذف مفتاح غير موجود لا يفعل شيئًا، وكذلك الحذف من خريطة nil. لإفراغ خريطة كاملة أضافت Go 1.21 الدالة clear(m)، التي تحتفظ بالخريطة المحجوزة لإعادة استخدامها.

حذف المدخلات أثناء range على الخريطة نفسها مسموح وآمن. المدخل المحذوف قبل أن تصل إليه الحلقة لن يظهر.

package main

import "fmt"

func main() {
	sessions := map[string]int{"a": 5, "b": 120, "c": 90, "d": 3}
	for id, idle := range sessions {
		if idle > 60 {
			delete(sessions, id) // safe during range
		}
	}
	fmt.Println(sessions)

	clear(sessions)
	fmt.Println(len(sessions))
}

المرور على العناصر: الترتيب عشوائي

تزور for k, v := range m كل مدخل مرة واحدة، بترتيب غير محدّد. يجعل وقت التشغيل نقطة البداية عشوائية عمدًا، فكثيرًا ما تختلف حلقتان على الخريطة نفسها في البرنامج نفسه. شغّل هذا بضع مرات:

package main

import "fmt"

func main() {
	m := map[string]int{"a": 1, "b": 2, "c": 3, "d": 4, "e": 5}
	for range 3 {
		for k := range m {
			fmt.Print(k, " ")
		}
		fmt.Println()
	}
}

أي شيفرة تعتمد مخرجاتها على ترتيب الخريطة خطأ ينتظر تشغيلًا مختلفًا. الاختبارات التي تقارن مرورًا مطبوعًا على خريطة هي المثال الكلاسيكي.

المفاتيح المرتّبة

لزيارة خريطة بترتيب المفاتيح، احصل على المفاتيح ورتّبها وافهرس الخريطة بها. جعلت Go 1.23 هذا سطرًا واحدًا بمكرِّرات الحزمتين maps وslices:

package main

import (
	"cmp"
	"fmt"
	"maps"
	"slices"
)

func main() {
	prices := map[string]float64{"tea": 2.5, "coffee": 3.2, "juice": 4.0, "water": 1.0}

	for _, k := range slices.Sorted(maps.Keys(prices)) {
		fmt.Printf("%-7s %.2f\n", k, prices[k])
	}

	keys := slices.Collect(maps.Keys(prices)) // unsorted slice of keys
	fmt.Println(len(keys))

	// Sort by value instead: sort the keys with a custom comparison.
	byPrice := slices.Collect(maps.Keys(prices))
	slices.SortFunc(byPrice, func(a, b string) int {
		return cmp.Compare(prices[a], prices[b])
	})
	fmt.Println(byPrice)
}

في Go 1.22 وما قبله لم تكن maps.Keys موجودة في المكتبة القياسية. والمكافئ حلقة:

keys := make([]string, 0, len(m))
for k := range m {
	keys = append(keys, k)
}
sort.Strings(keys)

دوال مساعدة أخرى في maps: maps.Values وmaps.Clone (نسخة سطحية) وmaps.Equal وmaps.Copy(dst, src) وmaps.DeleteFunc.

أنواع المفاتيح الصالحة

يجب أن تكون المفاتيح قابلة للمقارنة بـ ==: الأرقام والنصوص والقيم المنطقية والمؤشرات والقنوات ومصفوفات الأنواع القابلة للمقارنة والبنى التي كل حقولها قابلة للمقارنة وقيم الواجهات. لا يمكن أن تكون الشرائح والخرائط والدوال مفاتيح.

map[[]int]bool{}       // compile error: invalid map key type []int
map[[2]int]bool{}      // fine: arrays are comparable
map[struct{ X, Y int }]string{} // fine: a struct key for a grid position

المفتاح من نوع بنية هو الطريقة المعتادة للفهرسة بعدة قيم معًا، بدل ضمّ النصوص.

مفاتيح الواجهات تُترجم حتى عندما يكون النوع الديناميكي غير قابل للمقارنة، ثم تسبّب panic وقت التشغيل: تخزين []int في map[any]int يفشل برسالة runtime error: hash of unhashable type []int.

مفاتيح الأعداد العشرية تعمل، لكن NaN لا يساوي نفسه، فيمكن إدراج مفتاح NaN مرارًا دون أن يُقرأ أبدًا. تجنّب المفاتيح العشرية.

خريطة من البنى

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

package main

import "fmt"

type User struct {
	Name  string
	Score int
}

func main() {
	users := map[string]User{"u1": {Name: "Ana"}}
	// users["u1"].Score = 10 // compile error: cannot assign to struct field users["u1"].Score in map

	u := users["u1"] // copy out
	u.Score = 10
	users["u1"] = u // write back
	fmt.Println(users["u1"])

	// Or store pointers, and modify in place.
	ptrs := map[string]*User{"u2": {Name: "Bob"}}
	ptrs["u2"].Score += 5
	fmt.Println(*ptrs["u2"])
}

اختر القيم عندما تكون المدخلات صغيرة وتُستبدل كاملة. واختر المؤشرات عندما تحدّث الحقول كثيرًا أو تشارك السجل نفسه من عدة أماكن. مع المؤشرات يعيد المفتاح المفقود nil، فتسبّب ptrs["nope"].Score حالة panic.

خرائط الشرائح تعمل بالطريقة نفسها مع الإلحاق: groups[k] = append(groups[k], v) لا تحتاج تهيئة، لأن المفتاح المفقود يعطي شريحة nil وappend تتعامل مع nil.

الخرائط شبيهة بالمراجع

قيمة الخريطة تشير إلى بيانات مشتركة. إسناد خريطة أو تمريرها إلى دالة لا ينسخ المدخلات: يرى المتغيّران الخريطة نفسها.

package main

import (
	"fmt"
	"maps"
)

func addDefault(m map[string]int) {
	m["default"] = 1 // visible to the caller
}

func main() {
	a := map[string]int{"x": 1}
	b := a
	b["y"] = 2
	addDefault(a)
	fmt.Println(a)

	c := maps.Clone(a) // independent shallow copy
	c["x"] = 100
	fmt.Println(a["x"], c["x"])
}

لهذا تستطيع الدالة ملء خريطة دون إعادتها، بخلاف شريحة تلحق بها.

panic الخريطة nil

القيمة الصفرية للخريطة هي nil. الخريطة nil تُقرأ كخريطة فارغة، لكن الكتابة فيها تسبّب panic.

package main

import "fmt"

type Cache struct {
	data map[string]string
}

func main() {
	var m map[string]int
	fmt.Println(m["x"], len(m)) // reading nil is fine

	defer func() {
		fmt.Println("recovered:", recover())
	}()

	var c Cache       // data is nil
	c.data["k"] = "v" // panics
	fmt.Println("not reached")
}

المخرجات:

0 0
recovered: assignment to entry in nil map

حالة البنية هي التي تلدغ عمليًا. هيّئ حقول الخرائط في دالة بناء (func NewCache() *Cache { return &Cache{data: map[string]string{}} }) أو بكسل قبل أول كتابة.

الوصول المتزامن

الخرائط غير آمنة للاستخدام المتزامن. إذا كتبت goroutine بينما تقرأ أخرى أو تكتب، قد يوقف وقت التشغيل البرنامج برسالة fatal error: concurrent map writes (أو concurrent map read and map write). هذا خطأ قاتل لا panic، فلا يستطيع recover التقاطه.

احمِ الخريطة بـ mutex:

package main

import (
	"fmt"
	"sync"
)

type Counter struct {
	mu sync.Mutex
	m  map[string]int
}

func (c *Counter) Inc(key string) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.m[key]++
}

func main() {
	c := Counter{m: make(map[string]int)}
	var wg sync.WaitGroup
	for i := range 100 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			c.Inc([]string{"red", "green"}[i%2])
		}()
	}
	wg.Wait()
	fmt.Println(c.m["red"], c.m["green"])
}

يطبع هذا دائمًا 50 50. استخدم sync.RWMutex عندما تفوق القراءات الكتابات بكثير. توجد sync.Map لحالتين ضيقتين (مفاتيح تُكتب مرة وتُقرأ مرات كثيرة، أو goroutines تعمل على مفاتيح منفصلة)؛ ولكل ما عدا ذلك فإن mutex مع خريطة عادية أبسط وأسرع عادة. المزيد في صفحة mutex.

مرجع سريع

الخريطة ذات القيم struct{} هي أيضًا نوع المجموعة في Go؛ راجع المجموعات.

أخطاء شائعة

• الكتابة في خريطة nil. أنشئها دائمًا بـ make، بما في ذلك حقول الخرائط في البنى.
• الاعتماد على ترتيب المرور. رتّب المفاتيح.
• استخدام m[k] != 0 لفحص الوجود. استخدم comma-ok.
• تعديل حقل بنية عبر m[k].Field. انسخها خارجًا ثم أعد كتابتها، أو خزّن مؤشرات.
• مشاركة خريطة بين goroutines دون قفل. لا يمكن التعافي من الانهيار.