trek::RangeEnumerator Class Reference

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

#include <range_enumerator.h>

Inherits BaseEnumerator.

Public Member Functions
Constructors, Destructor, and Other Basic Methods
	RangeEnumerator ()
	Default constructor of the class.
virtual	~RangeEnumerator ()
	Class destructor. More...
void	operator= (RangeEnumerator &right_side)
	Provides the equal operator.
bool	operator== (RangeEnumerator &right_side)
	Provides the == operator.
virtual RangeEnumerator *	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 start_value, const char *str_value_ptr, uint32_t end_value=0)
	Adds the string value as enumeration for the unsigned integer value range. 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 (start value of range) 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. Will always fail for RangeEnumerator since it has a start and end range. Another GetEnumerations() function is available for range enumerations. 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. 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 ranges of unsigned integer values to strings for enumeration.

The unsigned integer values is limited to 32 bits.

Constructor & Destructor Documentation

~RangeEnumerator()

trek::RangeEnumerator::~RangeEnumerator ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

Add()

int32_t trek::RangeEnumerator::Add	(	uint32_t	start_value,
		const char *	str_value,
		uint32_t	end_value = 0
	)

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

The range enumerator matches if the value is greater than or equal to the start value and less than or equal to the end value.

Parameters

[in]	start_value	The start value for the enumerator.
[in]	str_value	The string value.
[in]	end_value	The end value for the enumerator. Must be >= start_value.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

TREK_DATA_NULL_PTR

TREK_DATA_RANGE_ERROR

Example:

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

Get() [1/2]

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

Finds the corresponding unsigned integer value for the specified string.

This function will return the 'start' value for the range.

Parameters

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

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_DOES_NOT_EXIST

Example:

RangeEnumerator e;
uint32_t value;
 
ret_value = e.Get( "OFF", &value );
 
if( ret_value == SUCCESS )
    printf( "Start value is %u\n", value );

Get() [2/2]

int32_t trek::RangeEnumerator::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:

RANGE_ENUM_ARRAY 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::RangeEnumerator::GetEnumerations

(

StringArray &

str_array

)

Gets a list of the string enumerations.

Deletes any items in the provided array prior to insertion. It is possible for duplicate strings to be returned. For example, if you used the following ranges 0-1 = RED, 2-3 = BLUE, and 4-7 = RED, then RED will be returned twice.

Parameters

[out]

str_array

Contains all of the current string enumerations.

Example:

RANGE_ENUM_ARRAY 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::RangeEnumerator::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.

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:

RangeEnumerator 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( "Range is: %u - %u\n", start_values[ii], end_values[ii] );
}

GetEnumerations() [3/3]

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

Gets a list of the integer values. Will always fail for RangeEnumerator since it has a start and end range. Another GetEnumerations() function is available for range enumerations.

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:

RangeEnumerator 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 )
{
    // will always return TREK_DATA_NOT_ALLOWED
}

Init()

void trek::RangeEnumerator::Init ( )

virtual

Initializes the object.

Removes all current enumerations.

LoadFile()

int32_t trek::RangeEnumerator::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::RangeEnumerator::Remove

(

const char *

input

)

Removes the enumeration specifed by the string.

If more than one enumertor with this string exists, all are removed.

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;
RangeEnumerator e;
 
ret_value = e.Remove( "Off" );
 
if( ret_value )
    ;   // process error

Remove() [2/2]

int32_t trek::RangeEnumerator::Remove

(

uint32_t

input

)

Removes the enumeration specifed by the integer (start value of range)

Parameters

[in]

input

Start value of enumeration to remove.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

Example:

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

SaveFile()

int32_t trek::RangeEnumerator::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" );