abstract struct Enum

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:

puts Color.new(1) # => prints "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:

puts Color.new(10) # => prints "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. If 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

Defined in:

enum.cr
json/to_json.cr
yaml/to_yaml.cr

Class Method Summary

Instance Method Summary

Macro Summary

Instance methods inherited from module Comparable(T)

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=

Instance methods inherited from struct Value

==(other) ==

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other)
===(other : YAML::Any)
===(other : JSON::Any) ===, =~(other) =~, class class, clone clone, crystal_type_id crystal_type_id, dup dup, hash hash, inspect
inspect(io : IO) inspect, itself itself, not_nil! not_nil!, tap(&block) tap, to_json to_json, to_pretty_json(io : IO)
to_pretty_json to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try

Class methods inherited from class Object

==(other : Class) ==, ===(other) ===, cast(other) : self cast, from_json(string_or_io) : self from_json, from_yaml(string : String) : self from_yaml, hash hash, inspect(io) inspect, name : String name, to_s(io) to_s, |(other : U.class) |

Class Method Detail

def self.from_value(value) : 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) # => Exception

[View source]
def self.from_value?(value) : 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

[View source]
def self.names : Array(String) #

Returns all enum members as an Array(String).

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

[View source]
def self.new(pull : JSON::PullParser) #

[View source]
def self.new(pull : YAML::PullParser) #

[View source]
def self.parse(string) : self #

Returns the enum member that has the given name, or raises if no such member exists. The comparison is made by using String#camelcase between string and the enum members names.

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

[View source]
def self.parse?(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 between string and the enum members names.

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

[View source]
def self.values : Array(self) #

Returns all enum members as an Array(self).

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

[View source]

Instance Method Detail

def &(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

[View source]
def +(other : Int) #

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

Color::Red + 1 # => Color::Blue
Color::Red + 2 # => Color::Green
Color::Red + 3 # => 3

[View source]
def -(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 # => -1

[View source]
def <=>(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

[View source]
def ==(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

[View source]
def ^(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.


[View source]
def hash #

Returns a hash value. This is the hash of the underlying value.


[View source]
def includes?(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

[View source]
def to_f32 : Float32 #

Returns the value of this enum member as a Float32


[View source]
def to_f64 : Float64 #

Returns the value of this enum member as a Float64


[View source]
def to_i : 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

[View source]
def to_i16 : Int16 #

Returns the value of this enum member as a Int16


[View source]
def to_i32 : Int32 #

Returns the value of this enum member as a Int32


[View source]
def to_i64 : Int64 #

Returns the value of this enum member as a Int64


[View source]
def to_i8 : Int8 #

Returns the value of this enum member as a Int8


[View source]
def to_json(io) #

[View source]
def to_s(io : IO) : Nil #

Appends a String representation of this enum member to the given IO. See #to_s.


[View source]
def to_s : 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 commas, 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"

[View source]
def to_u16 : UInt16 #

Returns the value of this enum member as a UInt16


[View source]
def to_u32 : UInt32 #

Returns the value of this enum member as a UInt32


[View source]
def to_u64 : UInt64 #

Returns the value of this enum member as a UInt64


[View source]
def to_u8 : UInt8 #

Returns the value of this enum member as a UInt8


[View source]
def to_yaml(yaml : YAML::Generator) #

[View source]
def |(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

[View source]
def ~ #

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


[View source]

Macro Detail

macro flags(*values) #

Convenience macro to create an ored enum from the given members.

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

[View source]