trek::Enumerator Class Reference

This class maps unsigned integer values to strings for enumeration. More...

#include <enumerator.h>

Inherits BaseEnumerator.

Public Member Functions
Constructors, Destructor, and Other Basic Methods
	Enumerator ()
	Default constructor of the class.
	Enumerator (Enumerator &input)
	Copy constructor of the class.
virtual	~Enumerator ()
	Class destructor. More...
void	operator= (Enumerator &right_side)
	Provides the equal operator.
bool	operator== (Enumerator &right_side)
	Provides the == operator.
virtual Enumerator *	Clone ()
	Returns an exact copy of the object;.
virtual void	Init ()
	Initializes the object. More...
Setup Methods
These methods control setting up the API.
int32_t	Add (uint32_t int_value, const char *str_value_ptr, uint32_t end_value=0)
	Adds the string values as enumeration for the unsigned integer value. More...
int32_t	Remove (const char *input)
	Removes the enumeration specifed by the string. More...
int32_t	Remove (uint32_t input)
	Removes the enumeration specifed by the integer. More...
void	RemoveAll ()
	Removes all enumerations.
Get Methods
int32_t	Get (const char *str_value, uint32_t *int_value)
	Finds the corresponding unsigned integer value for the specified string. More...
int32_t	Get (uint32_t int_value, char *output_str, uint32_t *size_of_output)
	Finds the corresponding string value for the specified unsigned integer. More...
uint32_t	GetNumberOfEnumerations ()
	Returns the current number of enumerations.
void	GetEnumerations (StringArray &str_array)
	Gets a list of the string enumerations. More...
int32_t	GetEnumerations (uint32_t *uint_array, uint32_t *num_available)
	Gets a list of the integer values. More...
int32_t	GetEnumerations (uint32_t *start_array, uint32_t *end_array, uint32_t *num_available)
	Gets a list of the start and end values for which enumerators exist. For an Enumerator, the start and end values will always be the same. More...
Serialization Methods
These methods help read and write the class to disk or memory. Most users will not be interested in these. Those that are can continue reading.
int32_t	LoadFile (const char *filename)
	Loads the Enumerator definition from the specified file. More...
int32_t	SaveFile (const char *filename)
	Saves the Enumerator definition to the specified file. More...

Detailed Description

This class maps unsigned integer values to strings for enumeration.

The unsigned integer values is limited to 32 bits.

Constructor & Destructor Documentation

~Enumerator()

trek::Enumerator::~Enumerator ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

Add()

int32_t trek::Enumerator::Add	(	uint32_t	int_value,
		const char *	str_value,
		uint32_t	end_value = 0
	)

Adds the string values as enumeration for the unsigned integer value.

Parameters

[in]	int_value	The integer value.
[in]	str_value	The string value.
[in]	end_value	This parameter defaults to zero and is ignored by the method.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

TREK_DATA_NULL_PTR

Example:

Enumerator e;
int32_t ret_value; 
 
// don't forget to check return values
ret_value = e.Add( 0, "OFF" );
ret_value = e.Add( 1, "ON" );

Get() [1/2]

int32_t trek::Enumerator::Get	(	const char *	str_value,
		uint32_t *	int_value
	)

Finds the corresponding unsigned integer value for the specified string.

If return code is SUCCESS, then the int_value contains a valid value.

Parameters

[in]	str_value	String value to find.
[out]	int_value	Corresponding integer value.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NULL_PTR

Example:

Enumerator e;
uint32_t value;
 
ret_value = e.Get( "OFF", &value );
 
if( ret_value )
    ;   // process error

Get() [2/2]

int32_t trek::Enumerator::Get	(	uint32_t	int_value,
		char *	output_str,
		uint32_t *	size_of_output
	)

Finds the corresponding string value for the specified unsigned integer.

If return code is SUCCESS, then the output_str contains a valid value.

Parameters

[in]	int_value	Integer value to find.
[out]	output_str	Corresponding string value.
[in,out]	size_of_output	The size of the output buffer. If return code is TREK_DATA_NOT_ENOUGH_SPACE, then this value is reset to the number of bytes required for the given enumerated value.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NOT_ENOUGH_SPACE

TREK_DATA_NULL_PTR

Example:

Enumerator e;
char str_value[10];
uint32_t size_of_output = 10;
 
ret_value = e.Get( 0, str_value, &size_of_output );
 
if( ret_value )
    ;   // process error
else
    printf("%s\n", str_value);

GetEnumerations() [1/3]

void trek::Enumerator::GetEnumerations

(

StringArray &

str_array

)

Gets a list of the string enumerations.

Deletes any items in the provided array prior to insertion.

Parameters

[out]

str_array

Contains all of the current string enumerations.

Example:

Enumerator e;
StringArray str_values;
 
e.GetEnumerations( str_values );
 
for( uint32_t ii = 0; ii < str_values.Size(); ii++ )
    printf("index %u = %s\n", ii, str_values.GetAt(ii) );

GetEnumerations() [2/3]

int32_t trek::Enumerator::GetEnumerations	(	uint32_t *	start_array,
		uint32_t *	end_array,
		uint32_t *	num_available
	)

Gets a list of the start and end values for which enumerators exist. For an Enumerator, the start and end values will always be the same.

The number of items needed can be found by a call to GetNumberOfEnumerations().

Parameters

[out]	start_array	Contains all of the start integer values.
[out]	end_array	Contains all of the end integer values.
[in,out]	num_available	The number of available slots in the array on input. Set to the number of valid items in the array on output.

Returns

SUCCESS

TREK_DATA_NOT_ENOUGH_SPACE

TREK_DATA_NULL_PTR

Example:

Enumerator e;
int32_t ret_value;
uint32_t int_values[10], end_values[10];
uint32_t num_available = 10;
 
ret_value = e.GetEnumerations( start_values, end_values, &num_available );
 
if( ret_value == SUCCESS )
{
    // start and end are same for this type of enumerator
    uint32_t ii = 0;
    for( ii = 0; ii < num_available; ii++ )
        printf( "Enumerated Value: %u\n", start_values[ii] );
}

GetEnumerations() [3/3]

int32_t trek::Enumerator::GetEnumerations	(	uint32_t *	uint_array,
		uint32_t *	num_available
	)

Gets a list of the integer values.

The number of items needed can be found by a call to GetNumberOfEnumerations().

Parameters

[out]	uint_array	Contains all of the current integer values.
[in,out]	num_available	The number of available slots in the array on input. Set to the number of valid items in the array on output.

Returns

SUCCESS

TREK_DATA_NOT_ENOUGH_SPACE

TREK_DATA_NULL_PTR

Example:

Enumerator e;
int32_t ret_value;
uint32_t int_values[10];
uint32_t num_available = 10;
 
ret_value = e.GetEnumerations( int_values, &num_available );
 
if( ret_value == SUCCESS )
{
    uint32_t ii = 0;
    for( ii = 0; ii < num_available; ii++ )
        printf( "Enumerated Value: %u\n", int_values[ii] );
}

Init()

void trek::Enumerator::Init ( )

virtual

Initializes the object.

Removes all current enumerations.

LoadFile()

int32_t trek::Enumerator::LoadFile

(

const char *

filename

)

Loads the Enumerator definition from the specified file.

Reads an XML format for the Enumerator. It can be written in with SaveFile.

Parameters

[in]

filename

The file to load the Enumerator object from.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Other return codes

Example:

Enumerator e;
 
ret_value = e.LoadFile( "my_file.xml" );

Remove() [1/2]

int32_t trek::Enumerator::Remove

(

const char *

input

)

Removes the enumeration specifed by the string.

Parameters

[in]

input

String value of enumeration to remove.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NULL_PTR

Example:

int32_t ret_value;
Enumerator e;
 
ret_value = e.Remove( "Off" );
 
if( ret_value )
    ;   // process error

Remove() [2/2]

int32_t trek::Enumerator::Remove

(

uint32_t

input

)

Removes the enumeration specifed by the integer.

Parameters

[in]

input

Integer value of enumeration to remove.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

Example:

Enumerator e;
 
ret_value = e.Remove( 1 );
 
if( ret_value )
    ;   // process error

SaveFile()

int32_t trek::Enumerator::SaveFile

(

const char *

filename

)

Saves the Enumerator definition to the specified file.

Writes an XML format for the Enumerator. It can be read in with LoadFile.

Parameters

[in]

filename

The file to save the Enumerator object to.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Other return codes

Example:

Enumerator e;
 
ret_value = e.SaveFile( "my_file.xml" );