AlliedModders - [TUT] Enumerations (enum)

Introduction:

Enumerations are basically data structures.
They allow you to:
create a block of data and set different values into it.

create your own constants with automatic incrementing.

create your own tags for variables.

Basic Syntax:

The basic syntax for enumerations is as follows:

Code:

enum [[_:]TagName] [(IncrementType)] { [TagForConstant:]Constant1 [= Value1], [TagForConstant:]Constant2 [= Value2], ... [TagForConstant:]ConstantN [= ValueN] }

Let's analyze each piece of the syntax:
First, the data encapsulated in square brackets [] are optional for syntax.

[_:]TagName
This is the name of the tag that you would be creating.
The tag name has a value that is the size of the enumeration, which is the last constant value + 1.
If you put the optional _: before the tag name, it means that it is no longer a tag.

(IncrementType)
This is the method used to give each constant a value in the enumeration.
The syntax for this is: operator= value
The default for this is (+= 1) so that each constant is 1 more than the constant before it.

[TagForConstant:]Constant1 [= Value1]
This is the name of the constant that is being created and also optionally giving it a value.
The first constant is 0 if it is not given a value.
Remember, the last constant being listed does not have a comma after it!

Creating Tags:

Creating your own tags is easy.
Here is an example of the bool tag:

Code:

enum bool { false, true }

It creates the bool tag, and creates 2 constants.
false is equal to bool:0 because the first constant starts at 0.
true is equal to bool:1 because the default increment is the constant before it + 1.
bool is also a constant that equals bool:2, because true is the last constant and is bool:1.

Creating tags for handles is done with an enumeration to create the tag and a constant defined for a handle.
Example:

Code:

enum Array { Invalid_Array = 0 }

This creates the Array tag for cellarrays and also a constant Invalid_Array that is equal to an invalid array handle.

Using Tags on Variables:

Using tags is simple. If you've worked with bools or Floats in AMXX before, then you have used tags before.
You can create variables that are tagged with a specific tag:

Code:

new myInteger = 1 new bool:myBoolean = true new Float:myFloat = 1.0

Remember that variables that use tags that have defined constants are not limited to those constants.
Example:

Code:

new bool:myBoolean = bool:2

The problem with doing so is that true and false are only 1 and 0 respectively, so if you checked that variable to true, it would say it is not equal to true.

Constants:

Enumerations can be useful to create a list of constants without having to define each one.
Example:

Code:

#define CONSTANT1 0 #define CONSTANT2 1 #define CONSTANT3 2 #define CONSTANT_SIZE 3

This could be annoying to try to add/edit/delete constants because you may have to edit more than one line.
Here is how an enumeration would look for this:

Code:

enum _:CONSTANT_SIZE { CONSTANT1, CONSTANT2, CONSTANT3 }

You can do something like this to create a list of constants that represent bits:

Code:

enum (<<= 1) // each value is the value before it shifted left once { BIT1 = 1, // start with 1 because that is the first bit BIT2, // 1 << 1 = 2 BIT3, // 2 << 1 = 4 BIT4 // 4 << 1 = 8 }

If you have constants defined for player tasks so that you can have different tasks for each player at a time, you may have this:

Code:

#define TASK_ID_1 1000 #define TASK_ID_2 2000 #define TASK_ID_3 3000 // ... set_task(1.0, "TaskHandler", id + TASK_ID_1) // ... public TaskHandler(taskid) { new id = taskid - TASK_ID_1 }

Well you may have different constant values for your task ids, so you can do this easily to copy that style shown above:

Code:

enum (+= 1000) // task ids are 1000 apart { TASK_ID_1 = 1000, // start with 1000 TASK_ID_2, TASK_ID_3 }

Data structures:

Data structures allow you to put different types of data in an array.
Here is an example code that could use a data structure:

Code:

new g_iKills[ 33 ] new g_iDeaths[ 33 ] new Float:g_flSpeed[ 33 ]; // g_iKills[ id ] = kills for id // g_iDeaths[ id ] = deaths for id // g_flSpeed[ id ] = run speed for id

To put this into a data structure, you could do this:

Code:

enum _:PlayerData { Player_Kills, Player_Deaths, Float:Player_Speed } new g_ePlayerData[ 33 ][ PlayerData ] // g_ePlayerData[ id ][ Player_Kills ] = kills for id // g_ePlayerData[ id ][ Player_Deaths ] = deaths for id // g_ePlayerData[ id ][ Player_Speed ] = run speed for id

When using tags for structure constants that are used as an array index (ie. Player_Speed), you may need to tag the array itself when setting/getting a value.
Example:

Code:

g_ePlayerData[ id ][ Player_Speed ] = 250.0 // If the above code gives a tag mismatch warning, you can change it to this: g_ePlayerData[ id ][ Player_Speed ] = _:250.0 // ... if( g_ePlayerData[ id ][ Player_Speed ] == 250.0 ) // If the above code gives a tag mismatch warning, you can change it to this: if( Float:g_ePlayerData[ id ][ Player_Speed ] == 250.0 )

With data structures, you can even create arrays and strings.
Example:

Code:

new g_szName[ 33 ][ 32 ]; new g_szAuthID[ 33 ][ 32 ]; new g_iUserID[ 33 ]; // can be changed to enum _:PlayerInfo { Player_Name[ 32 ], Player_AuthID[ 35 ], Player_UserID } new g_ePlayerData[ 33 ][ PlayerInfo ]

When using arrays and strings inside data structures, there are a few rules:

Code:

sizeof( Player_Name ) charsmax( Player_Name )

Those 2 lines are invalid because Player_Name is not a variable that has a size.
The constant Player_Name just reserves indexes 0-31 for the data structure, and Player_AuthID starts are 32 and stops at 66.
To get the size of those arrays/strings from a data structure, there are 2 ways:

Method #1:

Code:

Player_AuthID // sizeof( Player_Name ) Player_AuthID - 1 // charsmax( Player_Name ) // ... Player_UserID - Player_AuthID // sizeof( Player_AuthID ) Player_UserID - Player_AuthID - 1 // charsmax( Player_AuthID )

Method #2:

Code:

new eTempData[ PlayerData ] // ... sizeof( eTempData[ Player_Name ] ) charsmax( eTempData[ Player_Name ] ) // ... sizeof( eTempData[ Player_AuthID ] ) charsmax( eTempData[ Player_AuthID ] )

Method #2 is the best way because it ensures proper sizes in the event that an enum is modified.
Also, it would be the most practical way since the only reason you're using a data structure is to create an array that uses it.
So you should use the variable that uses the data structure for readability.

When using variable arrays that are sized by a data structure in functions, the data structure cannot have a tag.
Example:

Code:

enum PlayerData // PlayerData is a tag { Player_Kills, Player_Deaths, Float:Player_Speed } // ... new ePlayerData[ PlayerData ] ePlayerData[ Player_Kills ] = 0 ePlayerData[ Player_Deaths ] = 0 ePlayerData[ Player_Speed ] = 250.0 // this line will throw an error // because it does not accept arrays from data structures that are tagged set_task( 1.0, "TaskSetPlayerData", id, ePlayerData, PlayerData )

To fix that, you just need to untag the data structure:

Code:

enum _:PlayerData // PlayerData is no longer a tag { Player_Kills, Player_Deaths, Float:Player_Speed } // ... new ePlayerData[ PlayerData ] ePlayerData[ Player_Kills ] = 0 ePlayerData[ Player_Deaths ] = 0 ePlayerData[ Player_Speed ] = 250.0 // this line will work properly set_task( 1.0, "TaskSetPlayerData", id, ePlayerData, PlayerData )

I think this tutorial is complete.
If I confused any information or left anything out, please let me know.
Feedback and suggestions are welcome.