abstract struct Enum
inherits Value
¶
Enum is the base type of all enums.
An enum is a set of integer values, where each value has an associated name. For example:
enum Color
Red # 0
Green # 1
Blue # 2
end
Values start with the value 0 and are incremented by one, but can be overwritten.
To get the underlying value you invoke value on it:
Color::Green.value # => 1
Each constant (member) in the enum has the type of the enum:
typeof(Color::Red) # => Color
Flags enum¶
An enum can be marked with the @[Flags] annotation. This changes the default values:
@[Flags]
enum IOMode
Read # 1
Write # 2
Async # 4
end
Additionally, some methods change their behaviour.
Enums from integers¶
An enum can be created from an integer:
Color.new(1).to_s # => "Green"
Values that don't correspond to enum's constants are allowed: the value will still be of type Color, but when printed you will get the underlying value:
Color.new(10).to_s # => "10"
This method is mainly intended to convert integers from C to enums in Crystal.
Question methods¶
An enum automatically defines question methods for each member, using
String#underscore for the method name.
* In the case of regular enums, this compares by equality (==).
* In the case of flags enums, this invokes includes?.
For example:
color = Color::Blue
color.red? # => false
color.blue? # => true
mode = IOMode::Read | IOMode::Async
mode.read? # => true
mode.write? # => false
mode.async? # => true
This is very convenient in case expressions:
case color
when .red?
puts "Got red"
when .blue?
puts "Got blue"
end
Included modules
Comparable
Class methods¶
.each
¶
Iterates each member of the enum.
It won't iterate the None and All members of flags enums.
IOMode.each do |member, value|
# yield IOMode::Read, 1
# yield IOMode::Write, 2
# yield IOMode::Async, 3
end
.names : Array(String)
¶
: Array(String)
Returns all enum members as an Array(String).
Color.names # => ["Red", "Green", "Blue"]
.valid?(value : self) : Bool
¶
(value : self) : Bool
Returns true if the given value is an enum member, otherwise false.
false if not member.
Color.valid?(Color::Red) # => true
Color.valid?(Color.new(4)) # => false
Note
This is a class method, not an instance method because
an instance method valid? is defined by the language when a user
defines an enum member named Valid.
.values : Array(self)
¶
: Array(self)
Returns all enum members as an Array(self).
Color.values # => [Color::Red, Color::Green, Color::Blue]
.from_value(value : Int) : self
¶
(value : Int) : self
Returns the enum member that has the given value, or raises if no such member exists.
Color.from_value(0) # => Color::Red
Color.from_value(1) # => Color::Green
Color.from_value(2) # => Color::Blue
Color.from_value(3) # raises Exception
.from_value?(value : Int) : self?
¶
(value : Int) : self?
Returns the enum member that has the given value, or nil if
no such member exists.
Color.from_value?(0) # => Color::Red
Color.from_value?(1) # => Color::Green
Color.from_value?(2) # => Color::Blue
Color.from_value?(3) # => nil
.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)
¶
(ctx : YAML::ParseContext, node : YAML::Nodes::Node)
Reads a serialized enum member by name from ctx and node.
See #to_yaml for reference.
Raises YAML::ParseException if the deserialization fails.
.new(pull : JSON::PullParser)
¶
(pull : JSON::PullParser)
Reads a serialized enum member by name from pull.
See #to_json for reference.
Raises JSON::ParseException if the deserialization fails.
.parse(string : String) : self
¶
(string : String) : self
Returns the enum member that has the given name, or
raises ArgumentError if no such member exists. The comparison is made by using
String#camelcase and String#downcase between string and
the enum members names, so a member named "FortyTwo" or "FORTY_TWO"
is found with any of these strings: "forty_two", "FortyTwo", "FORTY_TWO",
"FORTYTWO", "fortytwo".
Color.parse("Red") # => Color::Red
Color.parse("BLUE") # => Color::Blue
Color.parse("Yellow") # raises ArgumentError
.parse?(string : String) : self?
¶
(string : String) : self?
Returns the enum member that has the given name, or
nil if no such member exists. The comparison is made by using
String#camelcase and String#downcase between string and
the enum members names, so a member named "FortyTwo" or "FORTY_TWO"
is found with any of these strings: "forty_two", "FortyTwo", "FORTY_TWO",
"FORTYTWO", "fortytwo".
Color.parse?("Red") # => Color::Red
Color.parse?("BLUE") # => Color::Blue
Color.parse?("Yellow") # => nil
Methods¶
#&(other : self)
¶
(other : self)
Returns the enum member that results from applying a logical "and" operation between this enum member's value and other. This is mostly useful with flag enums.
(IOMode::Read | IOMode::Async) & IOMode::Read # => IOMode::Read
#+(other : Int)
¶
(other : Int)
Returns the enum member that results from adding other to this enum member's value.
Color::Red + 1 # => Color::Green
Color::Red + 2 # => Color::Blue
Color::Red + 3 # => Color.new(3)
#-(other : Int)
¶
(other : Int)
Returns the enum member that results from subtracting other to this enum member's value.
Color::Blue - 1 # => Color::Green
Color::Blue - 2 # => Color::Red
Color::Blue - 3 # => Color.new(-1)
#<=>(other : self)
¶
(other : self)
Compares this enum member against another, according to their underlying value.
Color::Red <=> Color::Blue # => -1
Color::Blue <=> Color::Red # => 1
Color::Blue <=> Color::Blue # => 0
#==(other : self)
¶
(other : self)
Returns true if this enum member and other have the same underlying value.
Color::Red == Color::Red # => true
Color::Red == Color::Blue # => false
#^(other : self)
¶
(other : self)
Returns the enum member that results from applying a logical "xor" operation between this enum member's value and other. This is mostly useful with flag enums.
#each
¶
Iterates each values in a Flags Enum.
(IOMode::Read | IOMode::Async).each do |member, value|
# yield IOMode::Read, 1
# yield IOMode::Async, 3
end
#includes?(other : self)
¶
(other : self)
Returns true if this enum member's value includes other. This
performs a logical "and" between this enum member's value and other's,
so instead of writing:
(member & value) != 0
you can write:
member.includes?(value)
The above is mostly useful with flag enums.
For example:
mode = IOMode::Read | IOMode::Write
mode.includes?(IOMode::Read) # => true
mode.includes?(IOMode::Async) # => false
#to_i : Int32
¶
: Int32
Returns the value of this enum member as an Int32.
Color::Blue.to_i # => 2
(IOMode::Read | IOMode::Write).to_i # => 3
Color.new(10).to_i # => 10
#to_json(json : JSON::Builder)
¶
(json : JSON::Builder)
Serializes this enum member by name.
For non-flags enums, the serialization is a JSON string. The value is the
member name (see #to_s) transformed with String#underscore.
enum Stages
INITIAL
SECOND_STAGE
end
Stages::INITIAL.to_json # => %("initial")
Stages::SECOND_STAGE.to_json # => %("second_stage")
For flags enums, the serialization is a JSON array including every flagged
member individually serialized in the same way as a member of a non-flags enum.
None is serialized as an empty array, All as an array containing
all members.
@[Flags]
enum Sides
LEFT
RIGHT
end
Sides::LEFT.to_json # => %(["left"])
(Sides::LEFT | Sides::RIGHT).to_json # => %(["left","right"])
Sides::All.to_json # => %(["left","right"])
Sides::None.to_json # => %([])
ValueConverter.to_json offers a different serialization strategy based on the
member value.
#to_s(io : IO) : Nil
¶
View source
(io : IO) : Nil
#to_s : String
¶
: String
Returns a String representation of this enum member.
In the case of regular enums, this is just the name of the member.
In the case of flag enums, it's the names joined by vertical bars, or "None",
if the value is zero.
If an enum's value doesn't match a member's value, the raw value is returned as a string.
Color::Red.to_s # => "Red"
IOMode::None.to_s # => "None"
(IOMode::Read | IOMode::Write).to_s # => "Read | Write"
Color.new(10).to_s # => "10"
#to_yaml(yaml : YAML::Nodes::Builder)
¶
(yaml : YAML::Nodes::Builder)
Serializes this enum member by name.
For non-flags enums, the serialization is a YAML string. The value is the
member name (see #to_s) transformed with String#underscore.
enum Stages
INITIAL
SECOND_STAGE
end
Stages::INITIAL.to_yaml # => %(--- initial\n)
Stages::SECOND_STAGE.to_yaml # => %(--- second_stage\n)
For flags enums, the serialization is a YAML sequence including every flagged
member individually serialized in the same way as a member of a non-flags enum.
None is serialized as an empty sequence, All as a sequence containing
all members.
@[Flags]
enum Sides
LEFT
RIGHT
end
Sides::LEFT.to_yaml # => %(--- [left]\n)
(Sides::LEFT | Sides::RIGHT).to_yaml # => %(--- [left, right]\n)
Sides::All.to_yaml # => %(--- [left, right]\n)
Sides::None.to_yaml # => %(--- []\n)
ValueConverter.to_yaml offers a different serialization strategy based on the
member value.
#|(other : self)
¶
(other : self)
Returns the enum member that results from applying a logical "or" operation between this enum member's value and other. This is mostly useful with flag enums.
(IOMode::Read | IOMode::Async) # => IOMode::Read | IOMode::Async
#~
¶
Returns the enum member that results from applying a logical "not" operation of this enum member's value.
Macros¶
flags(*values)
¶
(*values)
Convenience macro to create a combined enum (combines given members using | (or) logical operator)
IOMode.flags(Read, Write) # => IOMode::Read | IOMode::Write