Utility Classes

This module contains classes providing miscellaneous services. More...

Classes
class	BitVector
class	Comparator< T >
class	StaticComparator< T, C >
class	DynamicComparator< T >
class	AssocComparator< K, T, C >
class	GlobalComparator< T >
class	CompareEquiv< C >
class	HashKey< T >
class	JenkinsHasher
class	SelfHashKey< T >
class	Initializer< T >
class	MessageException
class	Option< T >
class	Pair< T1, T2 >
class	Ref< T >
class	StrongType
class	SolidType
class	TestCase
class	TestSet
class	VarArg
class	Version
class	Exception
class	UniquePtr< T >
class	SharedPtr< T >
class	LockPtr< T >
class	Flags< T >

Macros
#define	STRONG_TYPE(N, T)   OTAWA_STRONG_TYPE(N, T)
#define	CHECK_BEGIN(name)   ELM_CHECK_BEGIN(name)
#define	TEST_BEGIN(name)   ELM_TEST_BEGIN(name)
#define	TEST_END   ELM_TEST_END
#define	CHECK(tst)   ELM_CHECK(tst)
#define	CHECK_END   ELM_CHECK_END
#define	ELM_CHECK_BEGIN(name)   { elm::TestCase __case(name); __case.prepare();
#define	ELM_CHECK(tst)   __case.check(__FILE__, __LINE__, #tst, tst)
#define	ELM_CHECK_END   __case.complete(); }
#define	ELM_CHECK_EQUAL(res, ref)   __case.check_equal(__FILE__, __LINE__, #res " == " #ref, res, ref)
#define	CHECK_EQUAL(res, ref)   ELM_CHECK_EQUAL(res, ref)

Functions
t::hash	hash_jenkins (const void *block, int size)
t::hash	hash_string (const char *chars, int length)
t::hash	hash_cstring (const char *chars)
bool	hash_equals (const void *p1, const void *p2, int size)
template<class T >
const T &	min (const T &x, const T &y)
template<class T >
const T &	max (const T &x, const T &y)
template<class T >
t::hash	hash (const T &x)

Detailed Description

This module contains classes providing miscellaneous services.

• AutoComparator – implementation of the concept::Comparator using the default "==" and "<" operators.
• BitVector – compact and fast representation of vector of bits,
• HashKey – implementation of the concept::Hash concept,
• Initializer – framework for single-dependency initialization of static objects,
• STRONG_TYPE – automatic class wrapper around scalar types like enumeration (to avoid ambiguities in C++ type conversion),
• Version – unified version representation.

Other classes provides base classes to a unified exception system:

• Exception – base class of exception,
• MessageException – exception with built-in string message.

Some classes makes easier the management of structured values:

• Option – optional value,
• Pair – pair of values,

Finally, some classes provides facilities to handle references:

• LockPtr and Lock – provides an automatic pointer management system,
• Ref – mutable references.
• SharedPtr
• UniquePtr Notice that the set of pointer wrapper classes can be include with "elm/ptr.h".

deprecated

• VarArg – wrapper around the variable arguments of function,

Macro Definition Documentation

CHECK

#define CHECK

(

tst

)

ELM_CHECK(tst)

#include <include/elm/test.h>

See ELM_CHECK.

Parameters

test	Test to check.

@seealso ELM_CHECK, REQUIRE, CHECK_EQUAL, CHECK_EXCEPTION, FAIL_ON_EXCEPTION

CHECK_BEGIN

#define CHECK_BEGIN

(

name

)

ELM_CHECK_BEGIN(name)

#include <include/elm/test.h>

This is the first statement of a unit test case. Usually, a unit test case is structured as below:

CHECK_BEGIN(test case name);
CHECK(test1);
CHECK(test2);
...
CHECK_END;

This statement display a state header, each CHECK displays a check status line and TEST_END a summary of the full test case. A test case defines also an environment like in C blocks { ... }.

Parameters

name	Name of the test case (string).

Note

These macros definition may be discarded defining the ELM_NO_SHORTCUT identifier, for avoiding name clashes for example.

@seealso CHECK_END, CHECK, elm::TestCase, elm::TestSet

CHECK_END

#define CHECK_END   ELM_CHECK_END

#include <include/elm/test.h>

See CHECK_END.

@seealso CHECK_BEGIN, CHECK, elm::TestCase, elm::TestSet

CHECK_EQUAL

#define CHECK_EQUAL	(		res,
			ref
	)		ELM_CHECK_EQUAL(res, ref)

#include <include/elm/test.h>

See ELM_CHECK_EQUAL.

ELM_CHECK

#define ELM_CHECK

(

tst

)

__case.check(__FILE__, __LINE__, #tst, tst)

#include <include/elm/test.h>

Same as CHECK.

ELM_CHECK_BEGIN

#define ELM_CHECK_BEGIN

(

name

)

{ elm::TestCase __case(name); __case.prepare();

#include <include/elm/test.h>

Same as CHECK_BEGIN.

ELM_CHECK_END

#define ELM_CHECK_END   __case.complete(); }

#include <include/elm/test.h>

Same as CHECK_END

ELM_CHECK_EQUAL

#define ELM_CHECK_EQUAL	(		res,
			ref
	)		__case.check_equal(__FILE__, __LINE__, #res " == " #ref, res, ref)

#include <include/elm/test.h>

Test if the result of a test is equal to a reference value.

Parameters

res	Result of the test.
ref	Reference value.

@seealso CHECK, REQUIRE, CHECK_EXCEPTION, FAIL_ON_EXCEPTION

STRONG_TYPE

#define STRONG_TYPE	(		N,
			T
	)		OTAWA_STRONG_TYPE(N, T)

#include <include/elm/util/strong_type.h>

As type defined with "typedef" command just create aliases to types, they cannot be used to resolve overloading. To circumvent this problem, this macro provide a wrapper around the defined type that is usable as the original type and that provide overload facilities.

This class is usually replaced this kind of declaration:

typedef type_exp type_name;

by :

typedef StrongType<type_exp> type_name;

Parameters

N	Name of the new type.
T	Encapsulated type.

Deprecated:

TEST_BEGIN

#define TEST_BEGIN

(

name

)

ELM_TEST_BEGIN(name)

#include <include/elm/test.h>

This macro is used to create and to record an integrated test case. Following the macro must be inserted the checked tests with macros based on CHECK and the test must be ended by the macro TEST_END.

The test cases may be specified independently but may be also grouped inside a test set, implemented by the class elm::TestSet. This class is a singleton, elm::TestSet::def, containing the list of uses cases. The list of test cases can be explored using elm::TestSet::Iterator.

In this case, the macro TEST_BEGIN and TEST_END must be used as in the example below:

TEST_BEGIN(my_test)
    CHECK(test1);
    CHECK(test2);
    ...
TEST_END

Parameters

test	Name of the test (must be unquoted !).

@seealso TEST_END, CHECK, elm::TestCase, elm::TestSet

TEST_END

#define TEST_END   ELM_TEST_END

#include <include/elm/test.h>

End a test declared with TEST_BEGIN.

@seealso TEST_BEGIN, CHECK, elm::TestCase, elm::TestSet

Function Documentation

hash()

t::hash hash ( const T &  x )

inline

#include <include/elm/hash.h>

Hash the given value according an existing HashKey implementation for type T. If no hash key is available for the given type, revert to Jenkins hashing that may be inexact in case of padding bytes inside an object!

Parameters

x	Value to hash.

Returns

Hashed x.

References HashKey< T >::hash().

Referenced by HashKey< T * >::computeHash(), HashKey< const T * >::computeHash(), HashKey< sys::Path >::hash(), and elm::hash_jenkins().

hash_cstring()

t::hash hash_cstring

(

const char *

chars

)

#include <include/elm/hash.h>

Use a classical compiler string hashing algorithm (see "The Compilers" by Aho, Sethi, Ullman).

Referenced by HashKey< CString >::hash().

hash_equals()

bool hash_equals	(	const void *	p1,
		const void *	p2,
		int	size
	)

#include <include/elm/hash.h>

Test equality of two memory blocks.

Parameters

p1	First memory block.
p2	Second memory block.
size	Block size.

Returns

True if they equals, byte to byte, false else.

hash_jenkins()

t::hash hash_jenkins	(	const void *	block,
		int	size
	)

#include <include/elm/hash.h>

Perform hashing according Jenkins approach (https://en.wikipedia.org/wiki/Jenkins_hash_function).

References elm::hash(), and elm::io::p().

Referenced by HashKey< K >::hash().

hash_string()

t::hash hash_string	(	const char *	chars,
		int	length
	)

#include <include/elm/hash.h>

Use a classical compiler string hashing algorithm (see "The Compilers" by Aho, Sethi, Ullman).

Referenced by HashKey< String >::hash().

max()

const T & max ( const T &  v1, const T &  v2  )

inline

#include <include/elm/compare.h>

Get the maximum of two values using Comparator<T>.

Parameters

v1	First value.
v2	Second value.

Returns

Maximum of v1 and v2.

Referenced by AbstractBlockAllocatorWithGC::AbstractBlockAllocatorWithGC(), Output::print(), elm::quicksort(), AbstractTree::rotateLeft(), and AbstractTree::rotateRight().

min()

const T & min ( const T &  v1, const T &  v2  )

inline

#include <include/elm/compare.h>

Get the minimum of two values using Comparator<T>.

Parameters

v1	First value.
v2	Second value.

Returns

Minimum of v1 and v2.

Referenced by Array< elm::String >::copy(), WAHVector::includes(), BitVector::meets(), MD5::put(), BitVector::resize(), AbstractTree::rotateLeft(), and AbstractTree::rotateRight().