map

Scripts > Class elements and c++ instructions > Interpreted C++ instructions > Container > map

A container class map manages a list of pairs of values. All pairs of a list have the same data types. There are, however, different map types depending on type of the contained pairs. (See the table above)

Syntax

mstrbool <identifier>

mstrint <identifier>

mstruint <identifier>

mstrdbl <identifier>

mstrchar <identifier>

mstrstr <identifier>

mstrnode <bezeichner>

mstrdnode <identifier>

Description

The map types are typedefs of the class CTT_Map< value_type > in the exported code. CTT_Map is derived from std::map< value_type >.

A map variable is a list of pairs of values. Each pair consists of a key word and its value. The pairs are sorted alphabetically according to the key. Thus a map has a good performance, when searching for a key, but not so good performance when searching for a value.

A map is always in a certain state: one of the pairs is the current pair. This pair is denoted by the cursor (pointer). The cursor also can be invalid: it can be positioned before or behind the elements (pairs). In this case the property hasCurrent is false and to access the key or value makes no sense. The cursor can be positioned and the properties of the current pair of strings can read or manipulated.

All map classes have the same methods. These are

1.) the read only methods of the general cursor class:

bool                isValid() const

bool                hasCurrent() const

bool                empty() const        

unsigned int        size() const

bool                gotoNext()

bool                gotoPrev()

value_type        value() const

bool                containsValue(const value_type& ) const

bool                findValue(const value_type& xValue)

bool                findNextValue(const value_type& xValue)

bool                findPrevValue(const value_type& xValue)

2.) getCursor() const

By this method an external cursor is connected with the map.

Example:

mstrnode m;

mstrnode::cursor cr =  m.getCursor();

cr now points to the same data element as the internal cursor, but further both can be placed independently from each other.

3. In addition to these general methods the map as well as an external cursor of a map has the read only methods:

str key() const

returns the key of the current element or an empty string, if there is no current pair.

bool containsKey(const str& xsKey) const

returns true, if a key xsKey is contained in the map.

bool findKey(const str& xsKey)

searches for the key xsKey. If the key is contained in the map the according element becomes the actual element and the function returns true. Otherwise false will be returned.

4.) Methods, which change the content of a map:

void reset()

Positions the cursor before/behind the list of elements of the map.

void clear()

removes all elements and resets all cursors.

bool add(const str& key, const value_type& xValue)

inserts an element into the map with the key key and the value value. If the insertion succeeded, true is returned. If there was already a pair with the key key inside of the map, false will be returned and the value will not be overwritten. All cursors are reset.

bool remove()

removes the current element from the map and returns true. If there is no current element or if an error occurs, false will be returned. All cursors are reset.

bool remove(const str& xsKey)

removes the element with the key xsKey from the map and returns true. If the key isn't contained in the map or an error occures, false will be returned. All cursors are reset.

bool setValue(const value_type& xValue)

changes the value of the current element and returns true. If there is no current element or if an error occurs, false will be returned.

5.) Direct element access

If you have a mstrstr named m, you can insert elements or access their values directly by

m[key]

This either returns the value of the element with the key key, or inserts an element with key, if it does not yet exist. So by

m["one"] = "two";

you insert a value with the key "one" and the value "two" and by

str s = m["one"];

you can copy the value "two" into the string s. If a new element is inserted, all cursors are reset.

Attention: if there was not inserted a value for the key before, the latter statement will automatically insert an empty string as value for the key "one" and copy the empty string to s. If you want to test, if the key exists in the map, you have to use the findKey function above.

This page belongs to the TextTransformer Documentation