abstract struct Enum

• Enum
• Value
• Object

Overview

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] attribute. 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 an 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(self)

Defined in:

Constructors

• .from_value(value) : self

  Returns the enum member that has the given value, or raises if no such member exists.

• .from_value?(value) : self?

  Returns the enum member that has the given value, or nil if no such member exists.

• .new(pull : JSON::PullParser)
• .new(pull : YAML::PullParser)
• .parse(string) : self

  Returns the enum member that has the given name, or raises ArgumentError if no such member exists.

• .parse?(string) : self?

  Returns the enum member that has the given name, or nil if no such member exists.

Class Method Summary

• .each(&block)

  Iterates each member of the enum.

• .names : Array(String)

  Returns all enum members as an Array(String).

• .values : Array(self)

  Returns all enum members as an Array(self).

Instance Method Summary

• #&(other : self)

  Returns the enum member that results from applying a logical "and" operation between this enum member's value and other.

• #+(other : Int)

  Returns the enum member that results from adding other to this enum member's value.

• #-(other : Int)

  Returns the enum member that results from subtracting other to this enum member's value.

• #<=>(other : self)

  Compares this enum member against another, according to their underlying value.

• #==(other : self)

  Returns true if this enum member and other have the same underlying value.

• #^(other : self)

  Returns the enum member that results from applying a logical "xor" operation between this enum member's value and other.

• #clone
• #each(&block)

  Iterates each values in a Flags Enum.

• #hash

  Returns a hash value.

• #includes?(other : self)

  Returns true if this enum member's value includes other.

• #to_f32 : Float32

  Returns the value of this enum member as a Float32

• #to_f64 : Float64

  Returns the value of this enum member as a Float64

• #to_i : Int32

  Returns the value of this enum member as an Int32.

• #to_i16 : Int16

  Returns the value of this enum member as a Int16

• #to_i32 : Int32

  Returns the value of this enum member as a Int32

• #to_i64 : Int64

  Returns the value of this enum member as a Int64

• #to_i8 : Int8

  Returns the value of this enum member as a Int8

• #to_json(json : JSON::Builder)
• #to_s(io : IO) : Nil

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

• #to_s : String

  Returns a String representation of this enum member.

• #to_u16 : UInt16

  Returns the value of this enum member as a UInt16

• #to_u32 : UInt32

  Returns the value of this enum member as a UInt32

• #to_u64 : UInt64

  Returns the value of this enum member as a UInt64

• #to_u8 : UInt8

  Returns the value of this enum member as a UInt8

• #to_yaml(yaml : YAML::Builder)
• #|(other : self)

  Returns the enum member that results from applying a logical "or" operation between this enum member's value and other.

• #~

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

Macro Summary

• flags(*values)

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

Constructor Detail

Color.from_value(0) # => Color::Red
Color.from_value(1) # => Color::Green
Color.from_value(2) # => Color::Blue
Color.from_value(3) # raises Exception

Color.from_value?(0) # => Color::Red
Color.from_value?(1) # => Color::Green
Color.from_value?(2) # => Color::Blue
Color.from_value?(3) # => nil

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

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

Class Method Detail

IOMode.each do |member, value|
  # yield IOMode::Read, 1
  # yield IOMode::Write, 2
  # yield IOMode::Async, 3
end

Color.names # => ["Red", "Green", "Blue"]

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

Instance Method Detail

(IOMode::Read | IOMode::Async) & IOMode::Read # => IOMode::Read

Color::Red + 1 # => Color::Green
Color::Red + 2 # => Color::Blue
Color::Red + 3 # => Color.new(3)

Color::Blue - 1 # => Color::Green
Color::Blue - 2 # => Color::Red
Color::Blue - 3 # => Color.new(-1)

Color::Red <=> Color::Blue  # => -1
Color::Blue <=> Color::Red  # => 1
Color::Blue <=> Color::Blue # => 0

Color::Red == Color::Red  # => true
Color::Red == Color::Blue # => false

(IOMode::Read | IOMode::Async).each do |member, value|
  # yield IOMode::Read, 1
  # yield IOMode::Async, 3
end

(member & value) != 0

member.includes?(value)

mode = IOMode::Read | IOMode::Write
mode.includes?(IOMode::Read)  # => true
mode.includes?(IOMode::Async) # => false

Color::Blue.to_i                    # => 2
(IOMode::Read | IOMode::Write).to_i # => 3

Color.new(10).to_i # => 10

Color::Red.to_s                     # => "Red"
IOMode::None.to_s                   # => "None"
(IOMode::Read | IOMode::Write).to_s # => "Read | Write"

Color.new(10).to_s # => "10"

(IOMode::Read | IOMode::Async) # => IOMode::Read | IOMode::Async

Macro Detail

IOMode.flags(Read, Write) # => IOMode::Read | IOMode::Write