struct

Enum

Inherits Comparable / Value / Object

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

Changing the Base Type

The type of the underlying enum value is Int32 by default, but it can be changed to any type in Int::Primitive.

enum Color : UInt8
  Red
  Green
  Blue
end

Color::Red.value # : UInt8

Constructors

from_value(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 ArgumentError
Source
new(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.

Source
new(value : self)

Returns value.

Source
new(pull : JSON::PullParser) : self

Reads a serialized enum member by name from pull.

See #to_json for reference.

Raises JSON::ParseException if the deserialization fails.

Source
parse(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. Dashes (-) in string have the same meaning as an underscore (_). A member named "FortyTwo" or "FORTY_TWO" is found with any of these strings: "forty_two", "FortyTwo", "FORTY_TWO", "Forty-Two", "FORTYTWO", "fortytwo".

Color.parse("Red")    # => Color::Red
Color.parse("BLUE")   # => Color::Blue
Color.parse("Yellow") # raises ArgumentError
Source

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
Source
from_value?(value : Int) : self | Nil

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
Source
names

Returns all enum members as an Array(String).

Color.names # => ["Red", "Green", "Blue"]
Source
parse?(string : String) : self | Nil

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. Dashes (-) in string have the same meaning as an underscore (_). A member named "FortyTwo", or "FORTY_TWO" is found with any of these strings: "forty_two", "FortyTwo", "FORTY_TWO", "Forty-Two", "FORTYTWO", "fortytwo".

Color.parse?("Red")    # => Color::Red
Color.parse?("BLUE")   # => Color::Blue
Color.parse?("Yellow") # => nil

If multiple members match the same normalized string, the first one is returned.

Source
valid?(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.

Source
values

Returns all enum members as an Array(self).

Color.values # => [Color::Red, Color::Green, Color::Blue]
Source

Instance methods

&(other : self) : 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
Source
+(other : Int) : self

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)
Source
-(other : Int) : self

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)
Source
<=>(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
Source
==(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
Source
==(other)

Returns false.

Source
^(other : self) : 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.

Source
|(other : self) : 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
Source
~

Returns the enum member that results from applying a logical "not" operation of this enum member's value.

Source
clone
Source
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
Source
hash(hasher)

See Object#hash(hasher)

Source
includes?(other : self) : Bool

Returns true if this enum member's value includes other. This performs a logical "and" between this enum member's value and other's.

This is mostly useful for flag enums.

For example:

mode = IOMode::Read | IOMode::Write
mode.includes?(IOMode::Read)  # => true
mode.includes?(IOMode::Async) # => false
Source
inspect(io : IO) : Nil

Returns an unambiguous String representation of this enum member. In the case of a single member value, this is the fully qualified name of the member (equivalent to #to_s with the enum name as prefix). In the case of multiple members (for a flags enum), it's a call to Enum.[] for recreating the same value.

If the value can't be represented fully by named members, the remaining value is appended.

Color::Red                     # => Color:Red
IOMode::None                   # => IOMode::None
(IOMode::Read | IOMode::Write) # => IOMode[Read, Write]

Color.new(10) # => Color[10]
Source
to_f32

Returns the value of this enum member as a Float32

Source
to_f32!

Returns the value of this enum member as a Float32

Source
to_f64

Returns the value of this enum member as a Float64

Source
to_f64!

Returns the value of this enum member as a Float64

Source
to_i

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
Source
to_i128

Returns the value of this enum member as a Int128

Source
to_i128!

Returns the value of this enum member as a Int128

Source
to_i16

Returns the value of this enum member as a Int16

Source
to_i16!

Returns the value of this enum member as a Int16

Source
to_i32

Returns the value of this enum member as a Int32

Source
to_i32!

Returns the value of this enum member as a Int32

Source
to_i64

Returns the value of this enum member as a Int64

Source
to_i64!

Returns the value of this enum member as a Int64

Source
to_i8

Returns the value of this enum member as a Int8

Source
to_i8!

Returns the value of this enum member as a Int8

Source
to_json(json : JSON::Builder) : Nil

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.

Source
to_s(io : IO) : Nil

Appends a String representation of this enum member to the given io.

See also: to_s.

Source
to_s

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"
Source
to_u128

Returns the value of this enum member as a UInt128

Source
to_u128!

Returns the value of this enum member as a UInt128

Source
to_u16

Returns the value of this enum member as a UInt16

Source
to_u16!

Returns the value of this enum member as a UInt16

Source
to_u32

Returns the value of this enum member as a UInt32

Source
to_u32!

Returns the value of this enum member as a UInt32

Source
to_u64

Returns the value of this enum member as a UInt64

Source
to_u64!

Returns the value of this enum member as a UInt64

Source
to_u8

Returns the value of this enum member as a UInt8

Source
to_u8!

Returns the value of this enum member as a UInt8

Source
to_yaml(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.

Source
value

Returns the underlying value held by the enum instance.

enum Color
  Red
  Green
  Blue
end

Color::Red.value   # => 0
Color::Green.value # => 1
Color::Blue.value  # => 2
Source

Macros

[](*values)

Convenience macro to create a combined enum (combines given members using | (or) logical operator).

Arguments can be the name of a member, a symbol representing a member name or a numerical value.

IOMode[Read]             # => IOMode[Read]
IOMode[1]                # => IOMode[Read]
IOMode[Read, Write]      # => IOMode[Read, Write]
IOMode[Read, 64]         # => IOMode[Read, 64]
IOMode[Read, :write, 64] # => IOMode[Read, Write, 64]
Source
flags(*values)

Convenience macro to create a combined enum (combines given members using | (or) logical operator)

IOMode.flags(Read, Write) # => IOMode[Read, Write]
  • Enum.[] is a more advanced alternative which also allows int and symbol parameters.
Source

Nested types