Containers

Detailed Description

There are several container classes that can hold elements of different types (Array, Array_, Array2, Map, Dic, Stack, HashMap).

Currently these containers can only contain elements of POD types or classes that do not hold pointers into themselves (all ASL classes are fine). These classes are reference-counted, so they are copied by reference. If a separate copy is required, use the clone() method:

Array<int> a = { 1, 2, 3 };
Array<int> b = a;               // b is the same as a
Array<int> c = a.clone();       // c is a separate copy of a

In C++11 compilers you can use range-based for loops to iterate over their items:

for(float x: numbers)
{
    sum += x;
}

Maps (Map, Dic, HashMap), can be iterated like this in C++11:

for(auto& e : constants)
{
    file << e.key << " = " e.value << '\n';
}

Or this way in C++17:

for(auto& [name, value] : constants)
{
    file << name << " = " value << '\n';
}

For older compilers there are special macros for iterating, foreach and foreach2 loops. The first iterates on the values of elements. And the second on both the keys and values of elements.

float sum = 0;
 
foreach(float x, numbers)
{
    sum += x;
}
 
Dic<int> ages;
ages["John"] = 23;
ages["Bob"] = 55;
 
foreach2(String& name, int age, ages)
{
    cout << name << " is " << age << " years old" << endl;
}

In order to support iterating the elements contained, these classes implement an Enumerator. These are similar to iterators but don't have to come in pairs (begin and end). Just one Enumerator knows how to go to the next element and when to stop iterating.

All containers have an all() enumerator that represents all its elements. All enumerators must implement operator * to dereference the currently pointed element, and may implement operator ~ to get their associated key, if any. For example, in an Array, they key is the integer index associated to each element. And in a Dic, the key is the element's name, a string.

This way, enumerating is done like this: (the keyword auto is useful if your compiler supports it)

for(Array<T>::Enumerator e = container.all(); e; ++e)
{
    cout << ~e << ':' << *e << endl;
}

That way, if container was a Dic, it would be printing the names and values of all elements.

Classes
class	Array< T >
	An Array is a contiguous and resizable array of any type of elements. More...
class	Array2< T >
	A simple 2-dimensional dynamic array or matrix. More...
class	Array_< T, N >
	This class represents a fixed-length array. More...
class	HashMap< K, T >
	This class implements a hash map, an unordered map of keys to values. More...
class	Map< K, T >
	An associative container linking keys of type K with values of type T. More...
class	Dic< T >
	Dic is a particular case of Map in which keys are strings. More...
class	Set< T >
	A set is a container of unique elements in any order. More...
class	Stack< T >
	This class represents a stack of elements of any type. More...

Macros
#define	foreach(variable, set)
	A for loop for containers resembling C++11 range-based for supporting old compilers. More...
#define	foreach2(key, variable, set)
	A for loop for associative containers resembling C++17 range-based for with structured binding. More...

Typedefs
typedef Array< byte >	ByteArray
	An alias for Array<byte>

Functions
template<class T >
Array< T >	array (const T &a0, const T &a1)
	Creates an array with the 2 elements given as arguments (there are overloads from 1 to 6 elements)
template<class T >
Array_< T, 2 >	array_ (const T &a0, const T &a1)
	Creates an array with the 2 elements given as arguments (there are overloads from 1 to 6 elements)
template<typename T >
void	shuffle (T *a, int n, Random &rnd=random)
	Shuffles an array of elements in place (n items starting at a). More...
template<typename E >
void	shuffle (E &a, Random &rnd=random)
	Shuffles an array of elements in place. More...
Dic< String >	split (const String &s, const String &sep1, const String &sep2)
	Parses a string and creates a Dic using sep1 as pair separator, and sep2 as key/value separator. More...

Macro Definition Documentation

foreach

#define foreach	(		variable,
			set
	)

A for loop for containers resembling C++11 range-based for supporting old compilers.

In each iteration, variable takes the value of each element in set. Variable can have a type declaration (equaling the type of elements of set) and an even be a reference. In newer compilers just use for(auto& x : a)

foreach(int& x, array)
    x *= 2;              // multiplies each element of the array times 2

This will not work for temporary containers (i.e. returned by functions).

foreach2

#define foreach2	(		key,
			variable,
			set
	)

A for loop for associative containers resembling C++17 range-based for with structured binding.

Similar to foreach but using two variables: the first will take the value of each key and the second will take its associated value. In newer compilers just use for(auto& x : a), or for(auto& [name, value] : a) [C++17]

foreach2(String& name, float value, variables)
{
    cout << name << " has the value " value << endl;
}

Function Documentation

shuffle() [1/2]

void asl::shuffle	(	E &	a,
		Random &	rnd = random
	)

Shuffles an array of elements in place.

Deprecated:

Use Random::shuffle()

shuffle() [2/2]

void asl::shuffle	(	T *	a,
		int	n,
		Random &	rnd = random
	)

Shuffles an array of elements in place (n items starting at a).

Deprecated:

Use Random::shuffle()

split()

Dic<String> asl::split ( const String &  s, const String &  sep1, const String &  sep2  )

inline

Parses a string and creates a Dic using sep1 as pair separator, and sep2 as key/value separator.

It is the opposite of join().

Deprecated:

Use String::split(s1, s2)