وثائق Go قابلة للتشغيل: التعدادات وiota

Q: هل تملك Go تعدادات enum؟

ليس كميزة في اللغة. لا توجد كلمة enum. البديل المعتاد نوع مسمّى مع كتلة من الثوابت ذات النوع، تُرقَّم عادة بـ iota: يمنحك النوع توقيعات مقروءة ومكانًا تعلّق عليه توابع مثل String(). لكنه لا يمنع أحدًا من كتابة Color(42)، لذا تحقّق من القيم القادمة من الخارج.

Q: ما هو iota في Go؟

iota معرّف مُعرَّف مسبقًا يساوي فهرس السطر الحالي (مواصفة الثابت) داخل كتلة const، بدءًا من 0. ويعود إلى 0 في كل كتلة const جديدة. عندما يحذف سطر تعبيره، تكرّر Go التعبير السابق مع قيمة iota التالية، وهذا ما يجعل Red = iota; Green; Blue تنتج 0 و1 و2.

Q: كيف أجعل iota تبدأ من 1؟

اكتب First Kind = iota + 1 في السطر الأول، أو تخطَّ الصفر بالمعرّف الفارغ: _ = iota ثم First. لكن كثيرًا من مبرمجي Go يُبقون الصفر ويسمّونه Unknown أو Invalid، فيكون المتغيّر غير المهيّأ (وقيمته الصفرية 0) واضحًا أنه ليس اختيارًا حقيقيًا.

Q: كيف أطبع قيمة enum كنص في Go؟

أعطِ النوع تابع String() string. تستدعيه fmt مع %v و%s وPrintln، فتطبع fmt.Println(Green) الكلمة Green بدل 1. يمكنك كتابة التابع يدويًا بـ switch أو مصفوفة، أو توليده بـ go run golang.org/x/tools/cmd/stringer@latest -type=Color.

Q: كيف أحوّل نصًا إلى enum في Go؟

اكتب دالة تحليل تبحث عن النص، عادة في map[string]Color أو switch، وتعيد خطأ للمدخلات المجهولة: func ParseColor(s string) (Color, error). وتطبيق UnmarshalText بالمنطق نفسه يجعل JSON والخيارات ومحمّلات الإعدادات تستخدمه تلقائيًا.

لا تملك Go كلمة enum. تبني التعداد من قطعتين: نوع مسمّى، وكتلة const من قيم ذلك النوع مرقّمة بـ iota.

package main

import "fmt"

type Weekday int

const (
	Sunday    Weekday = iota // 0
	Monday                   // 1
	Tuesday                  // 2
	Wednesday                // 3
	Thursday                 // 4
	Friday                   // 5
	Saturday                 // 6
)

func isWeekend(d Weekday) bool {
	return d == Saturday || d == Sunday
}

func main() {
	fmt.Println(Monday, Friday, Saturday)
	fmt.Println("Saturday is weekend:", isWeekend(Saturday))
	fmt.Println("Tuesday is weekend:", isWeekend(Tuesday))
}

Sunday قيمته 0، وكل سطر بعده يزيد واحدًا. النوع المسمّى Weekday هو ما يجعل هذا تعدادًا لا قائمة أرقام: تقول isWeekend في توقيعها ما تتوقّعه، ويمكن إضافة توابع إلى النوع. تطبع المخرجات 1 5 6 لأن لا شيء يخبر Go بعد كيف تعرض Weekday كنص. سيأتي ذلك لاحقًا.

كيف يعمل iota

iota عدّاد يوفّره المترجم داخل كتلة const. قاعدتان تشرحان كل حيلة مبنية عليه:

يساوي iota فهرس السطر الحالي في الكتلة، بدءًا من 0، ويعود إلى 0 في كل كتلة const جديدة.
السطر الذي ليس فيه = expression يكرّر تعبير السطر السابق ونوعه، مقيَّمًا بقيمة iota الجديدة.

إذن Monday في الأعلى اختصار لـ Monday Weekday = iota، وiota الآن 1. ولأن التعبير يتكرّر، يمكن أن يكون أي تعبير ثابت، لا iota وحده:

package main

import "fmt"

type Size int64

const (
	_  Size = iota             // 0, discarded
	KB Size = 1 << (10 * iota) // 1 << 10
	MB                         // 1 << 20
	GB                         // 1 << 30
	TB                         // 1 << 40
)

const (
	A = iota * 10 // 0
	B             // 10
	C             // 20
)

const (
	X, Y = iota, iota + 100 // both on line 0: 0, 100
	Z, W                    // line 1: 1, 101
)

func main() {
	fmt.Println(KB, MB, GB, TB)
	fmt.Println(A, B, C)
	fmt.Println(X, Y, Z, W)
}

يعدّ iota الأسطر لا الأسماء: ثابتان في السطر نفسه يتشاركان قيمة iota واحدة، كما يُظهر X وY.

البدء من 1، ولماذا قد لا تفعل

متغيّر من نوع تعداد لم يضبطه أحد يحمل 0، قيمته الصفرية. إذا كان 0 قيمة حقيقية مثل Sunday، فلا يمكنك التمييز بين "اختار المستخدم Sunday" و"لم يُملأ الحقل أبدًا". ثلاثة حلول شائعة:

package main

import "fmt"

type Status int

// Option 1: reserve 0 for an explicit "unknown" value.
const (
	StatusUnknown Status = iota
	StatusActive
	StatusSuspended
	StatusDeleted
)

type Level int

// Option 2: start at 1 with iota + 1.
const (
	Low Level = iota + 1
	Medium
	High
)

type Priority int

// Option 3: skip 0 with the blank identifier.
const (
	_ Priority = iota
	P1
	P2
	P3
)

type Account struct {
	Name   string
	Status Status
}

func main() {
	var a Account // Status was never set
	fmt.Println(a.Status == StatusUnknown)
	fmt.Println(Low, Medium, High)
	fmt.Println(P1, P2, P3)
}

الخيار 1 هو الأشيع في شيفرات الإنتاج، وتتبعه تعدادات Go المولَّدة من protobuf (..._UNSPECIFIED = 0). فتصبح القيمة الصفرية ذات معنى صادق.

تخطّي القيم

يستهلك المعرّف الفارغ _ قيمة iota دون إنشاء اسم. استخدمه لترك فجوات، مثلًا لمطابقة أرقام يحدّدها بروتوكول أو لإيقاف قيمة دون إعادة ترقيم البقية:

type Opcode byte

const (
	OpContinue Opcode = iota // 0
	OpText                   // 1
	OpBinary                 // 2
	_                        // 3, reserved
	_                        // 4, reserved
	_                        // 5, reserved
	_                        // 6, reserved
	_                        // 7, reserved
	OpClose                  // 8
	OpPing                   // 9
	OpPong                   // 10
)

عندما تحدّد مواصفة خارجية الأرقام، كما في رموز عمليات WebSocket هذه، فكتابتها صراحة (OpClose Opcode = 8) أوضح غالبًا من عدّ الفراغات. iota للقيم التي لا تهمّك أرقامها الدقيقة.

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

إضافة التابع String

أعطِ النوع تابع String() string فتستخدمه fmt مع %v و%s وPrintln:

package main

import "fmt"

type Weekday int

const (
	Sunday Weekday = iota
	Monday
	Tuesday
	Wednesday
	Thursday
	Friday
	Saturday
)

var weekdayNames = [...]string{
	"Sunday", "Monday", "Tuesday", "Wednesday",
	"Thursday", "Friday", "Saturday",
}

func (d Weekday) String() string {
	if d < 0 || int(d) >= len(weekdayNames) {
		return fmt.Sprintf("Weekday(%d)", int(d))
	}
	return weekdayNames[d]
}

func main() {
	fmt.Println(Monday, Friday)
	fmt.Printf("%v is day %d\n", Wednesday, Wednesday)
	fmt.Println(Weekday(9)) // out of range, still prints something useful

	today := Saturday
	fmt.Println("today:", today)
}

تفصيلتان في هذا التابع مهمّتان:

فحص الحدود. من دونه تسبّب Weekday(9).String() panic بسبب فهرس خارج النطاق، وسيحدث ذلك عاجلًا أو آجلًا، لأن لا شيء يمنع المستدعي من إنشاء Weekday(9).
الـ int(d) داخل Sprintf. تنسيق d نفسه بـ %d لا بأس به، لكن تنسيقه بـ %v سيستدعي String() مجددًا ويدخل في عودية حتى يفيض المكدّس.

ما زال %d يطبع الرقم، فتحصل على الشكلين: Wednesday is day 3.

توليد String بأداة stringer

للقوائم الطويلة تكتب أداة stringer التابع نيابة عنك:

//go:generate go run golang.org/x/tools/cmd/stringer@latest -type=Weekday

go generate ./...

تنشئ الملف weekday_string.go بتطبيق مختصر لـ String()، إضافة إلى فحص وقت الترجمة يكسر البناء إذا تغيّرت الثوابت دون إعادة التوليد. الخيار -linecomment يستخدم التعليق في آخر السطر اسمًا، وهذا مفيد للأسماء التي فيها مسافات.

التحقّق من القيم

التعداد في Go ليس مغلقًا. أي قيمة من النوع الأساسي تتحوّل إليه، والثوابت عديمة النوع تتحوّل ضمنيًا:

var d Weekday = 42     // compiles
d = Weekday(userInput) // compiles

لذا افحص القيم القادمة من خارج شيفرتك (JSON، قواعد البيانات، الخيارات، الحزم الأخرى):

package main

import (
	"fmt"
	"strings"
)

type Color int

const (
	ColorUnknown Color = iota
	Red
	Green
	Blue
	colorCount // unexported sentinel: always last
)

var colorNames = map[Color]string{
	Red:   "red",
	Green: "green",
	Blue:  "blue",
}

func (c Color) String() string {
	if name, ok := colorNames[c]; ok {
		return name
	}
	return fmt.Sprintf("Color(%d)", int(c))
}

func (c Color) IsValid() bool {
	return c > ColorUnknown && c < colorCount
}

func ParseColor(s string) (Color, error) {
	for c, name := range colorNames {
		if strings.EqualFold(name, s) {
			return c, nil
		}
	}
	return ColorUnknown, fmt.Errorf("unknown color %q", s)
}

func main() {
	fmt.Println(Green.IsValid(), Color(7).IsValid(), ColorUnknown.IsValid())

	for _, in := range []string{"BLUE", "purple"} {
		c, err := ParseColor(in)
		if err != nil {
			fmt.Println("error:", err)
			continue
		}
		fmt.Println("parsed:", c)
	}
}

الثابت الحارس غير المُصدَّر colorCount في نهاية الكتلة يُبقي IsValid صحيحة عندما تضيف ألوانًا جديدة، لأنه يقع دائمًا بعد آخر قيمة حقيقية بواحد.

switch على تعداد

تُستهلك التعدادات عادة عبر switch. لا تتحقّق Go من أن switch يغطّي كل قيمة، لذا أضف default يبلغ عن المفاجأة:

func (c Color) Hex() string {
	switch c {
	case Red:
		return "#ff0000"
	case Green:
		return "#00ff00"
	case Blue:
		return "#0000ff"
	default:
		return "#000000"
	}
}

أداة الفحص الخارجية exhaustive (المضمّنة في golangci-lint) تبلغ عن عبارات switch على أنواع التعداد التي تفوّت حالة، وهذا يعطيك معظم ما يقدّمه فحص شمول التعدادات في لغات أخرى.

تعدادات أعلام البتات

عندما تتجمّع القيم، مثل الصلاحيات، استخدم بتًا واحدًا لكل قيمة بـ 1 << iota:

package main

import (
	"fmt"
	"strings"
)

type Permission uint8

const (
	Read    Permission = 1 << iota // 1
	Write                          // 2
	Execute                        // 4
)

func (p Permission) Has(flag Permission) bool {
	return p&flag != 0
}

func (p Permission) String() string {
	if p == 0 {
		return "none"
	}
	var parts []string
	for _, f := range []struct {
		flag Permission
		name string
	}{{Read, "read"}, {Write, "write"}, {Execute, "execute"}} {
		if p.Has(f.flag) {
			parts = append(parts, f.name)
		}
	}
	return strings.Join(parts, "|")
}

func main() {
	p := Read | Write
	fmt.Println(p, int(p))
	fmt.Println("can write:", p.Has(Write))
	fmt.Println("can execute:", p.Has(Execute))

	p |= Execute // add a flag
	p &^= Write  // remove a flag (AND NOT)
	fmt.Println(p)

	var none Permission
	fmt.Println(none)
}

يجمع | الأعلام، ويفحصها &، ويمسحها &^ (معامل AND NOT في Go). النوع الأساسي عديم الإشارة هو الخيار الصحيح هنا: uint8 يتّسع لـ 8 أعلام، وuint64 لـ 64.

تعدادات نصية

عندما تُخزَّن القيمة أو تُرسل كنص في كل الأحوال، يتجنّب النوع المبني على النص طبقة التحويل:

type Env string

const (
	EnvDev     Env = "dev"
	EnvStaging Env = "staging"
	EnvProd    Env = "prod"
)

تُطبع القيم وتُسلسَل بشكل مقروء دون تابع String()، ويحمل عمود قاعدة البيانات "prod" بدل رقم يعتمد على ترتيب التعريف. المقابل: المقارنات مقارنات نصوص، وأعلام البتات مستحيلة، والتحقّق ما زال عليك، لأن Env("banana") تُترجم أيضًا.

التعدادات وJSON

يُسلسَل التعداد الصحيح كرقم افتراضيًا. لقراءة الأسماء وكتابتها بدلًا من ذلك، طبّق encoding.TextMarshaler وencoding.TextUnmarshaler. تستخدمهما encoding/json للقيم ولمفاتيح الخرائط:

package main

import (
	"encoding/json"
	"fmt"
)

type Level int

const (
	LevelUnknown Level = iota
	LevelLow
	LevelHigh
)

var levelNames = []string{"unknown", "low", "high"}

func (l Level) String() string {
	if l < 0 || int(l) >= len(levelNames) {
		return fmt.Sprintf("Level(%d)", int(l))
	}
	return levelNames[l]
}

func (l Level) MarshalText() ([]byte, error) {
	return []byte(l.String()), nil
}

func (l *Level) UnmarshalText(b []byte) error {
	for i, name := range levelNames {
		if name == string(b) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("invalid level %q", b)
}

type Alert struct {
	Message string `json:"message"`
	Level   Level  `json:"level"`
}

func main() {
	out, err := json.Marshal(Alert{Message: "disk full", Level: LevelHigh})
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println(string(out))

	var a Alert
	err = json.Unmarshal([]byte(`{"message":"cpu","level":"low"}`), &a)
	fmt.Println(a.Level, err)

	err = json.Unmarshal([]byte(`{"message":"cpu","level":"extreme"}`), &a)
	fmt.Println(err)
}

لـ MarshalText مستقبِل قيمة فتعمل على Level و*Level كليهما؛ أما UnmarshalText فتحتاج مستقبِل مؤشر لأنها تغيّر القيمة. التابعان نفساهما يجعلان النوع يعمل مع TextVar في الحزمة flag ومع معظم مكتبات الإعدادات.

مزالق

التحويل الضمني للحرفيات. الدالة التي تأخذ Weekday تقبل أيضًا الثابت عديم النوع 42. القيم ذات النوع من نوع آخر وحدها تُرفض.
نسيان النوع في السطر الأول. في const ( Red = iota; Green; Blue ) الثلاثة ثوابت صحيحة عديمة النوع، لا قيم Color، فلا تنطبق عليها توابع Color. اكتب Red Color = iota ليحمل التعبير المكرّر النوع.
إعادة ترتيب التعدادات المخزّنة. إدراج قيمة في منتصف كتلة iota يغيّر بصمت الأرقام المحفوظة في مكان آخر.
العودية في String. داخل String() لا تنسّق المستقبِل بـ %v أو %s أبدًا. حوّله إلى النوع الأساسي أولًا.

الأسئلة الشائعة

هل تملك Go تعدادات enum؟

ليس كميزة في اللغة. لا توجد كلمة enum. البديل المعتاد نوع مسمّى مع كتلة من الثوابت ذات النوع، تُرقَّم عادة بـ iota:

type Color int

const (
	Red Color = iota
	Green
	Blue
)

يمنحك النوع توقيعات مقروءة ومكانًا تعلّق عليه توابع مثل String(). لكنه لا يمنع أحدًا من كتابة Color(42)، لذا تحقّق من القيم القادمة من الخارج.

ما هو iota في Go؟

iota معرّف مُعرَّف مسبقًا يساوي فهرس السطر الحالي (مواصفة الثابت) داخل كتلة const، بدءًا من 0. ويعود إلى 0 في كل كتلة const جديدة. عندما يحذف سطر تعبيره، تكرّر Go التعبير السابق مع قيمة iota التالية، وهذا ما يجعل Red = iota; Green; Blue تنتج 0 و1 و2.

كيف أجعل iota تبدأ من 1؟

اكتب First Kind = iota + 1 في السطر الأول، أو تخطَّ الصفر بالمعرّف الفارغ: _ = iota ثم First. لكن كثيرًا من مبرمجي Go يُبقون الصفر ويسمّونه Unknown أو Invalid، فيكون المتغيّر غير المهيّأ (وقيمته الصفرية 0) واضحًا أنه ليس اختيارًا حقيقيًا.

كيف أطبع قيمة enum كنص في Go؟

أعطِ النوع تابع String() string. تستدعيه fmt مع %v و%s وPrintln، فتطبع fmt.Println(Green) الكلمة Green بدل 1. يمكنك كتابة التابع يدويًا بـ switch أو مصفوفة، أو توليده بـ go run golang.org/x/tools/cmd/stringer@latest -type=Color.

كيف أحوّل نصًا إلى enum في Go؟

اكتب دالة تحليل تبحث عن النص، عادة في map[string]Color أو switch، وتعيد خطأ للمدخلات المجهولة: func ParseColor(s string) (Color, error). وتطبيق UnmarshalText بالمنطق نفسه يجعل JSON والخيارات ومحمّلات الإعدادات تستخدمه تلقائيًا.

مفاهيم ذات صلة