W3cubDocs

/Crystal

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:

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

Defined in:

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

Constructors

Class Method Summary

Instance Method Summary

Macro Summary

  • flags(*values)

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

Constructor Detail

def self.from_value(value : Int) : selfSource

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

def self.from_value?(value : Int) : self?Source

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

def self.new(ctx : YAML::ParseContext, node : YAML::Nodes::Node)Source

def self.new(value : self)Source

Returns value.

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

def self.parse(string : String) : selfSource

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

def self.parse?(string : String) : self?Source

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

Class Method Detail

def self.each(&)Source

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

def self.names : Array(String)Source

Returns all enum members as an Array(String).

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

def self.valid?(value : self) : BoolSource

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.

def self.values : Array(self)Source

Returns all enum members as an Array(self).

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

Instance Method Detail

def &(other : self)Source

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

def +(other : Int)Source

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)

def -(other : Int)Source

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)

def <=>(other : self)Source

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

def ==(other : self)Source

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

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

def ^(other : self)Source

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.

def cloneSource

def each(&)Source

Iterates each values in a Flags Enum.

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

def hash(hasher)Source

def includes?(other : self)Source

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

def to_f32 : Float32Source

Returns the value of this enum member as a Float32

def to_f32! : Float32Source

Returns the value of this enum member as a Float32

def to_f64 : Float64Source

Returns the value of this enum member as a Float64

def to_f64! : Float64Source

Returns the value of this enum member as a Float64

def to_i : Int32Source

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

def to_i16 : Int16Source

Returns the value of this enum member as a Int16

def to_i16! : Int16Source

Returns the value of this enum member as a Int16

def to_i32 : Int32Source

Returns the value of this enum member as a Int32

def to_i32! : Int32Source

Returns the value of this enum member as a Int32

def to_i64 : Int64Source

Returns the value of this enum member as a Int64

def to_i64! : Int64Source

Returns the value of this enum member as a Int64

def to_i8 : Int8Source

Returns the value of this enum member as a Int8

def to_i8! : Int8Source

Returns the value of this enum member as a Int8

def to_json(json : JSON::Builder)Source

def to_s(io : IO) : NilSource

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

See also: #to_s.

def to_s : StringSource

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"

def to_u16 : UInt16Source

Returns the value of this enum member as a UInt16

def to_u16! : UInt16Source

Returns the value of this enum member as a UInt16

def to_u32 : UInt32Source

Returns the value of this enum member as a UInt32

def to_u32! : UInt32Source

Returns the value of this enum member as a UInt32

def to_u64 : UInt64Source

Returns the value of this enum member as a UInt64

def to_u64! : UInt64Source

Returns the value of this enum member as a UInt64

def to_u8 : UInt8Source

Returns the value of this enum member as a UInt8

def to_u8! : UInt8Source

Returns the value of this enum member as a UInt8

def to_yaml(yaml : YAML::Nodes::Builder)Source

def |(other : self)Source

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

def ~Source

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

Macro Detail

macro flags(*values)Source

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

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

© 2012–2020 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.35.1/Enum.html