DataType
# Enumeration
forsearch
DataType
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## Description
An Enumeration (or enum) is a data type that consists of a group of named values (called elements). By default, the elements are numbered consecutively, starting with zero, but you can assign any Integer value to an element.
## Methods
table-centered_column_4
| Name | Parameters | Returns | Shared |
|----------------------------------|-----------------------------------------------------|------------------------------------|--------|
| `Contains` | value As Enumeration | `Boolean` | |
## Method descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
Enumeration.Contains
**Contains**(value As Enumeration) As `Boolean`
> Returns `True` if the value is found within the binary Enumeration.
## Notes
Enumerations are added to classes (and modules) using Insert \> Enumeration. From the Enum Editor, you can add the named values. In your code, you refer to an enum by its name and refer to its elements by using dot notation. For example:
EnumName.EnumElement
So why should you use an Enum instead of an Integer constant? An Integer constant is a great way to refer to a constant value using a name. But since it is equivalent to an Integer, you cannot restrict its usage. With an enum, you can enforce that only the specific set of values are allowed.
Although Enumerations only accept Integer constants, the Enumeration values cannot be treated as Integers in your code because an Enumeration is a separate type. Likewise, Integer values cannot be assigned to an Enumeration. Should you need to get the Integer value of an Enumeration, you need to cast it to an integer.
You refer to an Enum in your code using dot notation. If the Enum is in a module and has Global scope it is referred to as:
*EnumName*.EnumValue
If it is in a module and has Public scope, it uses the module name in the notation:
*ModuleName.EnumName*.EnumValue
If it is in a class then you have to use the full notation irrespective of the scope:
*ClassName.EnumName*.EnumValue
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Passing as parameters
An Enumeration can be used to restrict the values that can be passed (for example to a method) to only those defined in the Enumeration. This is done by defining the passed parameters as of type Enumeration.
So if you have a method declared as
``` xojo
Sub Test(x As Integer)
End Sub
```
and you do
``` xojo
Test(123) ' This code compiles even if the value makes no sense
```
any range checks have to be in your code for the method and then you have to raise an error or do "something intelligent" to signal the out of bounds value
If however you use an enum (CodeNames in this case):
Enum CodeNames
- Foo = 0
- Bar = 1
- Baz = 2
``` xojo
Sub Test(x As CodeNames) ' <<<<<<<<<< passing the enum instead of just an integer
End Sub
Test(123) ' This wont compile !!!!
```
then the compiler has, at compile time, detected the error in your code.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Supported binary operations
For binary enumerations, supported operations include `Or`, `And`, `Xor`, automatic conversion to and from `Integer` as well as comparisons (`=`, `\<`, `\>`, `\>=`, `\<=`).
Note
Binary
enumerations are not currently supported for Android.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Use with extends
You can use the `Extends` feature to create extension methods that can convert an Enumeration to its String value. For example, consider this Enumeration that is on a module:
Enum SomeEnum
- Foo = 0
- Bar = 1
- Baz = 2
On the same module you can create an extension method like this that will return the Enumeration element name as a String:
``` xojo
Public Function StringValue(Extends e As SomeEnum) As String
Select Case e
Case SomeEnum.Foo
Return "Foo"
Case SomeEnum.Bar
Return "Bar"
Case SomeEnum.Baz
Return "Baz"
End Select
End Function
```
You can also create a method to do the reverse, which is assign a String to an Enum and have it set the correct element:
``` xojo
Public Sub StringValue(Extends ByRef e As SomeEnum, Assigns value As String)
Select Case value
Case "Foo"
e = SomeEnum.Foo
Case "Bar"
e = SomeEnum.Bar
Case "Baz"
e = SomeEnum.Baz
Else ' Set a default for an invalid input
e = SomeEnum.Foo
End Select
End Sub
```
With the above two methods, you can now write code like this to get an Enumeration value as a String and to set it using a String:
``` xojo
Var e As SomeEnum
e = SomeEnum.Baz
Var s As String = e.StringValue ' s = "Baz"
e.StringValue = "Bar" ' e = SomeEnum.Bar
e.StringValue = "Biz" ' e = SomeEnum.Foo (the default specified in the method)
```
This technique might be useful for situations when you want to save Enumeration values, such as to a database or JSON. You should not rely on it for your regular coding as it avoids the type checking benefits that an Enumeration brings.
## Sample code
Consider a global Enumeration named SecurityLevels that has four elements: Unauthorized, Minimal, Maximum, and Forced. Their Integer values range from 0 to 3.
To assign a level of Minimal to a variable of type SecurityLevels:
``` xojo
Var level As SecurityLevels
level = SecurityLevels.Minimal
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
The level variable can only be assigned Enum elements. You cannot just assign its Integer value:
``` xojo
level = 1 ' Compile error
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
You can, however, get the Integer value of an element by casting it to an Integer:
``` xojo
Var levelInt As Integer
levelInt = Integer(SecurityLevel.Minimal) ' levelInt = 1
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
You can also cast an Integer to an Enum.
``` xojo
Var level As SecurityLevel
level = SecurityLevel(1) ' No compile or runtime error even if the Integer is not valid
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
To pass an Enumeration to a method, use its type name:
``` xojo
Sub SetSecurityLevel(level As SecurityLevel)
If level = SecurityLevel.Minimal Then
' Do something
End If
End Sub
```
## Compatibility
| | |
|-----------------------|-----|
| **Project Types** | All |
| **Operating Systems** | All |
`Enumerations` topic