enum.dd

Ddoc

$(SPEC_S Enums,

$(GRAMMAR
$(GNAME EnumDeclaration):
    $(D enum) $(GLINK EnumTag) $(GLINK EnumBody)
    $(D enum) $(GLINK EnumBody)
    $(D enum) $(GLINK EnumTag) $(D :) $(GLINK EnumBaseType) $(GLINK EnumBody)
    $(D enum) $(D :) $(GLINK EnumBaseType) $(GLINK EnumBody)

$(GNAME EnumTag):
    $(I Identifier)

$(GNAME EnumBaseType):
    $(GLINK2 declaration, Type)

$(GNAME EnumBody):
    $(GLINK EmptyEnumBody)
    $(GLINK EnumMembersBody)

$(GNAME EmptyEnumBody):
    $(D ;)

$(GNAME EnumMembersBody):
    $(D {) $(GLINK EnumMembers) $(D })

$(GNAME EnumMembers):
    $(GLINK EnumMember)
    $(GLINK EnumMember) $(D ,)
    $(GLINK EnumMember) $(D ,) $(I EnumMembers)

$(GNAME EnumMember):
    $(I Identifier)
    $(I Identifier) $(D =) $(ASSIGNEXPRESSION)
    $(GLINK2 declaration, Type) $(I Identifier) $(D =) $(ASSIGNEXPRESSION)
)

	$(P Enum declarations are used to define a group of constants.
	They come in these forms:
	)
	$(OL
	$(LI Named enums, which have an $(I EnumTag).)
	$(LI Anonymous enums, which do not have an $(I EnumTag).)
	$(LI Manifest constants.)
	)

$(H2 Named Enums)

	$(P
	Named enums are used to declare related
	constants and group them by giving them a unique type.
	The $(I EnumMembers)
	are declared in the scope of the enum $(I EnumTag).
	The enum $(I EnumTag) declares a new type, and all
	the $(I EnumMembers) have that type.
	)

	$(P This defines a new type $(CODE X) which has values
	$(CODE X.A=0), $(CODE X.B=1), $(CODE X.C=2):)

------
enum X { A, B, C }	// named enum
------


	$(P If the $(I EnumBaseType) is not explicitly set, and the first
	$(I EnumMember) has an $(ASSIGNEXPRESSION), it is set to the type of that
	$(ASSIGNEXPRESSION). Otherwise, it defaults to
	type $(CODE int).)

	$(P Named enum members may not have individual $(I Type)s.
	)


	$(P A named enum member can be implicitly cast to its $(I EnumBaseType),
	but $(I EnumBaseType) types
	cannot be implicitly cast to an enum type.
	)

	$(P The value of an $(I EnumMember) is given by its $(ASSIGNEXPRESSION).
	If there is no $(ASSIGNEXPRESSION) and it is the first $(I EnumMember),
	its value is $(CODE $(GLINK EnumBaseType).init).
	)

	$(P If there is no $(ASSIGNEXPRESSION) and it is not the first $(I EnumMember),
	it is given the value of the previous $(CODE $(I EnumMember)+1).
	If the value of the previous $(I EnumMember) is $(CODE $(GLINK EnumBaseType).max),
	it is an error.
	If the value of the previous $(CODE $(I EnumMember)+1) is the same as the
	value of the previous $(I EnumMember), it is an error. (This can happen
	with floating point types.)
	)

	$(P All $(I EnumMember)s are in scope for the $(ASSIGNEXPRESSION)s.
	)

---
enum A = 3;
enum B {
  A = A // error, circular reference
}
enum C {
  A = B,  // A = 4
  B = D,  // B = 4
  C = 3,  // C = 3
  D       // D = 4
}
enum E : C {
  E1 = C.D,
  E2      // error, C.D is C.max
}
---


	$(P An $(I EmptyEnumBody) signifies an opaque enum - the enum members are
	unknown.)

$(H3 Enum Default Initializer)

	$(P The $(CODE .init) property of an enum type is the value
	of the first member of that enum.
	This is also the default initializer for the enum type.
	)

------
enum X { A=3, B, C }
X x;      // x is initialized to 3
------

$(H3 Enum Properties)

	$(P Enum properties only exist for named enums.
	)

	$(TABLE1
	$(CAPTION Named Enum Properties)
	$(TROW $(D .init), First enum member value)
	$(TROW $(D .min), Smallest value of enum)
	$(TROW $(D .max), Largest value of enum)
	$(TROW $(D .sizeof), Size of storage for an enumerated value)
	)

	$(P For example:)

---
enum X { A=3, B, C }
X.min    // is X.A
X.max    // is X.C
X.sizeof // is same as int.sizeof
---

	$(P The $(I EnumBaseType) of named enums must support comparison
	in order to compute the $(CODE .max) and $(CODE .min) properties.
	)


$(H2 Anonymous Enums)

	$(P If the enum $(I Identifier) is not present, then the enum
	is an $(I anonymous enum), and the $(I EnumMembers) are declared
	in the scope the $(I EnumDeclaration) appears in.
	No new type is created.
	)

	$(P The $(I EnumMembers) can have different types.
	Those types are given by the first of:
	)

	$(OL
	$(LI The $(I Type), if present.)
	$(LI The $(I EnumBaseType), if present.)
	$(LI The type of the $(I AssignExpression), if present.)
	$(LI The type of the previous $(I EnumMember), if present.)
	$(LI $(CODE int))
	)


------
enum { A, B, C }  // anonymous enum
------

	$(P Defines the constants A=0, B=1, C=2, all of type int.)

	$(P Enums must have at least one member.
	)

	$(P The value of an $(I EnumMember) is given by its $(ASSIGNEXPRESSION).
	If there is no $(ASSIGNEXPRESSION) and it is the first $(I EnumMember),
	its value is the $(CODE .init) property of the $(I EnumMember)'s type.
	)

	$(P If there is no $(ASSIGNEXPRESSION) and it is not the first $(I EnumMember),
	it is given the value of the previous $(CODE $(I EnumMember)+1).
	If the value of the previous $(I EnumMember) is the $(CODE .max) property
	if the previous $(I EnumMember)'s type,
	it is an error.
	If the value of the previous $(CODE $(I EnumMember)+1) is the same as the
	value of the previous $(I EnumMember), it is an error. (This can happen
	with floating point types.)
	)

	$(P All $(I EnumMember)s are in scope for the $(ASSIGNEXPRESSION)s.
	)

------
enum { A, B = 5+7, C, D = 8+C, E }
------

	$(P Sets A=0, B=12, C=13, D=21, and E=22, all of type int.)

---
enum : long { A = 3, B }
---

	$(P Sets A=3, B=4 all of type long.)

---
enum : string {
  A = "hello",
  B = "betty",
  C     // error, cannot add 1 to "betty"
}
---

---
enum {
  A = 1.2f,  // A is 1.2f of type float
  B,         // B is 2.2f of type float
  int C = 3, // C is 3 of type int
  D          // D is 4 of type int
}
---

$(H2 Manifest Constants)

	$(P If there is only one member of an anonymous enum, the { } can
	be omitted:
	)

---
enum i = 4;      // i is 4 of type int
enum long l = 3; // l is 3 of type long
---

	$(P Such declarations are not lvalues, meaning their address
	cannot be taken.  They exist only in the memory of the compiler.)
	
---
enum size = __traits(classInstanceSize, Foo);  // evaluated at compile-time
---
	
	$(P Using manifest constants is an idiomatic D method 
	to force compile-time evaluation of an expression.)


)

Macros:
	TITLE=Enums
	WIKI=Enum
	CATEGORY_SPEC=$0