---
title: "Enumerations"
url: https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Enumerations

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/php.md), [Python](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/swift.md).

## Enumeration Syntax and Semantics

An enumeration defines a set of named values, its enumerators:

```slice
module M
{
    enum Fruit { Apple, Pear, Orange }
}
```

This definition introduces a new type named `Fruit`. By default, the first enumerator has a value of zero, with sequentially increasing values for subsequent enumerators.

A Slice enum type introduces a new namespace scope, so the following is legal:

```slice
module M
{
    enum Fruit { Apple, Pear, Orange }
    enum ComputerBrands { Apple, Dell, HP, Lenovo }
}
```

The example below shows how to refer to an enumerator from a different scope:

```slice
module M
{
    enum Color { Red, Green, Blue }
}

module N
{
    struct Pixel
    {
        M::Color c = Blue;
    }
}
```

Slice does not permit empty enumerations.

> **Note**
>
> In Ice releases prior to Ice 3.7, an enum type did not create a new namespace and its enumerators were in the same namespace as the enum type itself. With these releases, you had to select longer enumerator names to avoid a naming clash.

## Custom Enumerator Values

Slice also permits you to assign custom values to enumerators:

```slice
const int PearValue = 7;
enum Fruit { Apple = 0, Pear = PearValue, Orange }
```

Custom values must be unique and non-negative, and may refer to Slice constants of integer types. If no custom value is specified for an enumerator, its value is one greater than the enumerator that immediately precedes it. In the example above, `Orange` has the value 8.

The maximum value for an enumerator value is the same as the maximum value for `int`, 2<sup>31</sup> - 1.

Slice does not require custom enumerator values to be declared in increasing order:

```slice
enum Fruit { Apple = 5, Pear = 3, Orange = 1 }   // Legal
```

The language mapping determines whether a program can compare two enumerators for order, and whether such a comparison follows the enumerators' values or their declaration order.

> **Warning**
>
> For an application that is still using version 1.0 of the [Ice encoding](https://docs.zeroc.com/ice/3.8/encoding/basic-data-encoding.md), changing the definition of an enumerated type **may** break backward compatibility with existing applications. For more information, please refer to the [encoding rules](https://docs.zeroc.com/ice/3.8/encoding/basic-data-encoding.md) for enumerators.

## Language Mapping

> **C++**
>
> A Slice enumeration maps to the corresponding `enum class` in C++.
>
> For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The generated C++ enumeration is:
>
> ```cpp
> enum class Fruit : std::uint8_t { Apple, Pear, Orange };
> ```
>
> The underlying type is `std::uint8_t` when the enumeration's largest enumerator value is not greater than 255, otherwise it's `std::int32_t`.
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The generated C++ definition now includes an explicit initializer for every enumerator:
>
> ```cpp
> enum class Fruit : std::uint8_t { Apple = 0, Pear = 3, Orange = 4 };
> ```
>
> ### Printing Enumerators
>
> The Slice compiler also generates `operator<<` to “print” the enumerators of the C++ enum. For example:
>
> ```cpp
> std::ostream& operator<<(std::ostream& os, Fruit value);
> ```
>
> You can suppress the generation of this operator, and tell the Slice compiler you’ll provide your own custom operator\<\<, with the `"cpp:custom-print"` metadata. For example:
>
> ```slice
> ["cpp:custom-print"] // we provide our own custom operator<< for this enum
> enum Fruit { Apple, Pear = 3, Orange }
> ```

> **C#**
>
> A Slice enumeration maps to the corresponding enumeration in C#. For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> Not surprisingly, the generated C# definition is very similar:
>
> ```csharp
> public enum Fruit { Apple, Pear, Orange }
> ```
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The generated C# definition now includes an explicit initializer for every enumerator:
>
> ```csharp
> public enum Fruit { Apple = 0, Pear = 3, Orange = 4 }
> ```

> **Java**
>
> A Slice enumeration maps to the corresponding enumeration in Java. For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The Java mapping for `Fruit` is shown below:
>
> ```java
> public enum Fruit {
>     Apple,
>     Pear,
>     Orange;
>
>     public int value();
>
>     public static Fruit valueOf(int v);
>
>     // ...
> }
> ```
>
> Given the above definitions, we can use enumerated values as follows:
>
> ```java
> Fruit f1 = Fruit.Apple;
> Fruit f2 = Fruit.Orange;
>
> if (f1 == Fruit.Apple) { // Compare with constant
>     // ...
> }
>
> if (f1 == f2) { // Compare two enums
>     // ...
> }
>
> switch (f2) {   // Switch on enum
>     case Apple:
>         // ...
>         break;
>     case Pear:
>         // ...
>         break;
>     case Orange:
>         // ...
>         break;
> }
> ```
>
> The Java mapping includes two methods of interest. The `value` method returns the Slice value of an enumerator, which is not necessarily the same as its ordinal value. The `valueOf` method translates a Slice value into its corresponding enumerator, or returns `null` if no match is found.
>
> In the `Fruit` definition above, the Slice value of each enumerator matches its ordinal value. This will not be true if we modify the definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The table below shows the new relationship between ordinal value and Slice value:
>
> | **Enumerator** | **Ordinal** | **Slice** |
> | --- | --- | --- |
> | `Apple` | 0 | 0 |
> | `Pear` | 1 | 3 |
> | `Orange` | 2 | 4 |
>
> > **Tip**
> >
> > Java enumerated types inherit implicitly from `java.lang.Enum`, which defines methods such as `ordinal` and `compareTo` that operate on the *ordinal* value of an enumerator, not its Slice value.

> **JavaScript**
>
> JavaScript does not have an enumerated type, so a Slice enumeration is emulated using JavaScript objects where each enumerator is an instance of the same type. For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The generated code is equivalent to the following JavaScript code:
>
> ```js
> class Fruit { ... }
> Fruit.Apple = new Fruit("Apple", 0);
> Fruit.Pear = new Fruit("Pear", 1);
> Fruit.Orange = new Fruit("Orange", 2);
> ```
>
> The corresponding TypeScript declarations are:
>
> ```typescript
> export class Fruit extends Ice.EnumBase {
>     static readonly Apple: Fruit;
>     static readonly Pear: Fruit;
>     static readonly Orange: Fruit;
>
>     static valueOf(value: number): Fruit | undefined;
> }
> ```
>
> Each enumerator has the read-only `name` and `value` properties of `Ice.EnumBase`, which supply the enumerator's name and value, and a `toString` method that returns its name. The static `valueOf` method returns the enumerator with a given value.
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The generated code changes accordingly:
>
> ```js
> class Fruit { ... }
> Fruit.Apple = new Fruit("Apple", 0);
> Fruit.Pear = new Fruit("Pear", 3);
> Fruit.Orange = new Fruit("Orange", 4);
> ```
>
> Given the above definitions, we can use enumerated values as follows:
>
> ```js
> const f1 = Fruit.Apple;
> const f2 = Fruit.Orange;
>
> if (f1 === Fruit.Apple) { // Compare with constant
>     // ...
> }
>
> if (f1 === f2) {         // Compare two enums
>     // ...
> }
>
> switch(f2) {             // Switch on enum
>     case Fruit.Apple:
>         // ...
>         break;
>     case Fruit.Pear:
>         // ...
>         break;
>     case Fruit.Orange:
>         // ...
>         break;
> }
>
> // Convert a value to its enumerator, or undefined if no match
> const f = Fruit.valueOf(3);
> console.log(f.name + " = " + f.value); // Outputs "Pear = 3"
> ```
>
> > **Note**
> >
> > The TypeScript declarations describe the same generated code: `Fruit` is a class, not a TypeScript `enum`, and `Fruit.Apple` is an instance of this class, not a number.

> **MATLAB**
>
> A Slice enumeration maps to the corresponding enumeration in MATLAB. For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The MATLAB mapping for `Fruit` is shown below:
>
> ```matlab
> classdef Fruit < uint8
>     enumeration
>         Apple (0)
>         Pear (1)
>         Orange (2)
>     end
>     methods(Static)
>         function r = ice_getValue(v)
>             switch v
>                 case 0
>                     r = Example.Fruit.Apple;
>                 case 1
>                     r = Example.Fruit.Pear;
>                 case 2
>                     r = Example.Fruit.Orange;
>                 otherwise
>                     throw(Ice.MarshalException(...
>                         sprintf('enumerator value %d is out of range', v)));
>             end
>         end
>     end
> end
> ```
>
> Given the above definitions, we can use enumerated values as follows:
>
> ```matlab
> f1 = Fruit.Apple;
> f2 = Fruit.Orange;
>
> if f1 == Fruit.Apple % Compare with constant
>     % ...
> end
>
> if f1 == f2          % Compare two enums
>     % ...
> end
>
> switch f2            % Switch on enum
>     case Fruit.Apple
>         % ...
>     case Fruit.Pear
>         % ...
>     case Fruit.Orange
>         % ...
> end
> ```
>
> The generated enumeration derives from `uint8` when its largest enumerator value is 255 or less, and from `int32` otherwise. You obtain the value of an enumerator by converting it to this base type, here with the `uint8` function:
>
> ```matlab
> val = uint8(Fruit.Pear);
> assert(val == 1);
> ```
>
> To convert an integer into its equivalent enumerator, call the `ice_getValue` function:
>
> ```matlab
> f = Fruit.ice_getValue(2);
> assert(f == Fruit.Orange);
> ```
>
> This function throws an exception if the given integer does not match any of the enumerators.
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The generated code changes accordingly:
>
> ```matlab
> classdef Fruit < uint8
>     enumeration
>         Apple (0)
>         Pear (3)
>         Orange (4)
>     end
>     % ...
> end
> ```

> **PHP**
>
> A Slice enumeration is mapped to a PHP class: the name of the Slice enumeration becomes the name of the PHP class; for each enumerator, the class contains a constant with the same name as the enumerator. For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The generated PHP class looks as follows:
>
> ```php
> class Fruit
> {
>     const Apple = 0;
>     const Pear = 1;
>     const Orange = 2;
> }
> ```
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The generated PHP class changes accordingly:
>
> ```php
> class Fruit
> {
>     const Apple = 0;
>     const Pear = 3;
>     const Orange = 4;
> }
> ```
>
> Since enumerated values are mapped to integer constants, application code is not required to use the generated constants. When an enumerated value enters the Ice runtime, Ice validates that the given integer is a valid value for the enumeration. However, to minimize the potential for defects in your code, we recommend using the generated constants instead of literal integers.

> **Python**
>
> A Slice enumeration maps to a Python enum.Enum class. The Slice enum name becomes the Python class name, and each enumerator becomes a class attribute with the same name.
>
> For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> Generates:
>
> ```py
> from enum import Enum
>
> class Fruit(Enum):
>
>     Apple = 0
>     Pear = 1
>     Orange = 2
> ```
>
> Each enum member has:
>
> - `value`: The underlying Slice integer value.
> - `name`: The enumerator’s name as a string.
>
> ### Usage
>
> ```py
> >>> Fruit.Apple.value == 0
> True
> >>> Fruit(0) == Fruit.Apple
> True
> >>> Fruit.Apple == 0
> False
> >>> Fruit.Pear.value
> 1
> >>> Fruit.Pear.name
> 'Pear'
> ```
>
> - To get a enumerator from its **value**, use the constructor: `Fruit(0)`. If the value is invalid, Python raises `ValueError`.
> - To get a member from its **name**, use item access: `Fruit['Apple']`. If the name is invalid, Python raises `KeyError`.
>
> For additional details, see the official [Python enum documentation.](https://docs.python.org/3/library/enum.html#enum.Enum)

> **Ruby**
>
> A Slice enumeration maps to a Ruby class with the same name, capitalized, and each enumerator maps to a constant of this class, also capitalized. Consider this enumeration:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The generated Ruby class looks as follows:
>
> ```ruby
> class Fruit
>     include Comparable
>
>     Apple = # ...
>     Pear = # ...
>     Orange = # ...
>
>     def Fruit.from_int(val)
>
>     def to_i
>
>     def to_s
>
>     def <=>(other)
>
>     def hash
>
>     # ...
> end
> ```
>
> The compiler generates a class constant for each enumerator that holds a corresponding instance of `Fruit`. The `from_int` class method returns an instance given its Slice value, while `to_i` returns the Slice value of an enumerator and `to_s` returns its Slice identifier.
>
> Given the above definitions, we can use enumerated values as follows:
>
> ```ruby
> f1 = Fruit::Apple
> f2 = Fruit::Orange
>
> if f1 == Fruit::Apple   # Compare for equality
>     # ...
>
> if f1 < f2              # Compare two enums
>     # ...
>
> case f2
> when Fruit::Orange
>     puts "found Orange"
> else
>     puts "found #{f2.to_s}"
> end
> ```
>
> Comparison operators are available as a result of including `Comparable`, which means a program can compare enumerators according to their Slice values. Note that, when using custom enumerator values, the order of enumerators by their Slice values may not match their order of declaration.
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> We can use `from_int` to examine the Slice values of the enumerators:
>
> ```ruby
> Fruit::from_int(0)  # Apple
> Fruit::from_int(1)  # nil
> Fruit::from_int(3)  # Pear
> Fruit::from_int(4)  # Orange
> ```

> **Swift**
>
> A Slice enumeration maps to a Swift enumeration that stores raw values of type `UInt8` or `Int32`. For example:
>
> ```slice
> enum Fruit { Apple, Pear, Orange }
> ```
>
> The mapped Swift enumeration is very similar:
>
> ```swift
> public enum Fruit: UInt8 {
>     case Apple = 0
>     case Pear = 1
>     case Orange = 2
>     public init() {
>         self = .Apple
>     }
> }
> ```
>
> The raw value type for the generated enumeration is `UInt8` when the largest enumerator value is 255 or less; otherwise, the raw value type is `Int32`.
>
> Suppose we modify the Slice definition to include a custom enumerator value:
>
> ```slice
> enum Fruit { Apple, Pear = 3, Orange }
> ```
>
> The generated Swift definition now includes adjusted values for each enumerators:
>
> ```swift
> public enum Fruit: UInt8 {
>     case Apple = 0
>     case Pear = 3
>     case Orange = 4
>     public init() {
>         self = .Apple
>     }
> }
> ```

## See Also

- [Constants and Literals](https://docs.zeroc.com/ice/3.8/slice/constants-and-literals.md)
