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 value0 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.

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 incase 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 isInt32 by default, but it can be changed to any type inInt::Primitive.

enum Color : UInt8
  Red
  Green
  Blue
end

Color::Red.value # : UInt8

Included Modules

Defined in:

enum.cr
json/to_json.cr
uri/params/to_www_form.cr
yaml/to_yaml.cr

Constructors

Class Method Summary

Macro Summary

Instance Method Summary

Instance methods inherited from module Comparable(Enum)

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

Instance methods inherited from struct Value

==(other : Log::Metadata::Value)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io : String | IO, root : String)
from_json(string_or_io : String | IO) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.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

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

Reads a serialized enum member by name fromctx andnode.

See#to_yaml for reference.

RaisesYAML::ParseException if the deserialization fails.


def self.new(value : self) #

Returnsvalue.


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

Reads a serialized enum member by name frompull.

See#to_json for reference.

RaisesJSON::ParseException if the deserialization fails.


def self.parse(string : String) : self #

Returns the enum member that has the given name, or raisesArgumentError if no such member exists. The comparison is made by using String#camelcase andString#downcase betweenstring and the enum members names. Dashes (#-) instring have the same meaning as an underscore (_). A member named&quot;FortyTwo&quot; or&quot;FORTY_TWO&quot; is found with any of these strings:&quot;forty_two&quot;,&quot;FortyTwo&quot;,&quot;FORTY_TWO&quot;, &quot;Forty-Two&quot;,&quot;FORTYTWO&quot;,&quot;fortytwo&quot;.

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

Class Method Detail

def self.each(& : self -> ) #

Iterates each member of the enum. It won't iterate theNone andAll members of flags enums.

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

def self.from_value?(value : Int) : self | Nil #

Returns the enum member that has the given value, ornil 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.names : Array(String) #

Returns all enum members as anArray(String).

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

def self.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 andString#downcase betweenstring and the enum members names. Dashes (#-) instring have the same meaning as an underscore (_). A member named&quot;FortyTwo&quot;, or&quot;FORTY_TWO&quot; is found with any of these strings:&quot;forty_two&quot;,&quot;FortyTwo&quot;,&quot;FORTY_TWO&quot;, &quot;Forty-Two&quot;,&quot;FORTYTWO&quot;,&quot;fortytwo&quot;.

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.


def self.valid?(value : self) : Bool #

Returnstrue if the givenvalue is an enum member, otherwisefalse. 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 namedValid.


def self.values : Array(self) #

Returns all enum members as anArray(self).

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

Macro Detail

macro [](*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]

macro 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.

Instance Method Detail

def &(other : self) : self #

Returns the enum member that results from applying a logical &quot;and&quot; operation between this enum member's value andother. This is mostly useful with flag enums.

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

def +(other : Int) : self #

Returns the enum member that results from addingother 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) : self #

Returns the enum member that results from subtractingother 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) #

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) #

Returnstrue if this enum member andother have the same underlying value.

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

def ==(other) #
Description copied from struct Value

Returnsfalse.


def ^(other : self) : self #

Returns the enum member that results from applying a logical &quot;xor&quot; operation between this enum member's value andother. This is mostly useful with flag enums.


def |(other : self) : self #

Returns the enum member that results from applying a logical &quot;or&quot; operation between this enum member's value andother. This is mostly useful with flag enums.

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

def ~ : self #

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


def clone #

def each(& : self -> ) #

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) #

SeeObject#hash(hasher)


def includes?(other : self) : Bool #

Returnstrue if this enum member's value includesother. This performs a logical&quot;and&quot; between this enum member's value andother'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

def inspect(io : IO) : Nil #

Returns an unambiguousString 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 toEnum.[] 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]

def to_f32 : Float32 #

Returns the value of this enum member as aFloat32


def to_f32! : Float32 #

Returns the value of this enum member as aFloat32


def to_f64 : Float64 #

Returns the value of this enum member as aFloat64


def to_f64! : Float64 #

Returns the value of this enum member as aFloat64


def to_i : Int32 #

Returns the value of this enum member as anInt32.

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

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

def to_i128 : Int128 #

Returns the value of this enum member as aInt128


def to_i128! : Int128 #

Returns the value of this enum member as aInt128


def to_i16 : Int16 #

Returns the value of this enum member as aInt16


def to_i16! : Int16 #

Returns the value of this enum member as aInt16


def to_i32 : Int32 #

Returns the value of this enum member as aInt32


def to_i32! : Int32 #

Returns the value of this enum member as aInt32


def to_i64 : Int64 #

Returns the value of this enum member as aInt64


def to_i64! : Int64 #

Returns the value of this enum member as aInt64


def to_i8 : Int8 #

Returns the value of this enum member as aInt8


def to_i8! : Int8 #

Returns the value of this enum member as aInt8


def 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 withString#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.


def to_s(io : IO) : Nil #

Appends aString representation of this enum member to the givenio.

See also:#to_s.


def to_s : String #

Returns aString 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&quot;None&quot;, 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_u128 : UInt128 #

Returns the value of this enum member as aUInt128


def to_u128! : UInt128 #

Returns the value of this enum member as aUInt128


def to_u16 : UInt16 #

Returns the value of this enum member as aUInt16


def to_u16! : UInt16 #

Returns the value of this enum member as aUInt16


def to_u32 : UInt32 #

Returns the value of this enum member as aUInt32


def to_u32! : UInt32 #

Returns the value of this enum member as aUInt32


def to_u64 : UInt64 #

Returns the value of this enum member as aUInt64


def to_u64! : UInt64 #

Returns the value of this enum member as aUInt64


def to_u8 : UInt8 #

Returns the value of this enum member as aUInt8


def to_u8! : UInt8 #

Returns the value of this enum member as aUInt8


def 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 withString#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.


def value : Int #

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