Info

Main Page of Documentation

Table of Contents

• Setting values
• Accessing the Info
• Checking if the Info has a certain key
• Getting values with a default
• Checking the size
• Removing specific keys
• Removing all keys
• Printing the Info
• Using Info in Info
• Further information

---

The CoSimIO::Info object plays a very important role in the CoSimIO. It is a map (implemented with std::map) holding key-value pairs of different value types, similar to the dict of Python. It is used as a configuration object and supports the following value types:

• int
• std::size_t
• double
• bool
• std::string
• CoSimIO::Info

Most functions in the public interface of CoSimIO have an instance of CoSimIO::Info as input and as return value to communicate with the including code.

Aside from using the CoSimIO::Info as configuration object, it can also be used to exchange metadata between codes by using the ImportInfo and ExportInfo functions (see the API documentation).

This file describes the native (C++) interface of CoSimIO::Info.

Click here for the C interface and here for the Python interface.

Setting values

The Set method can be used to set values in the Info. Note that the type of the value should be specified as template argument. The first argument is the key (given as std::string), the second is the value.

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

One Info object can hold several types:

CoSimIO::Info info;

info.Set<int>("echo_level", 1);
info.Set<double>("tolerance", 0.01);
info.Set<bool>("is_converged", true);
info.Set<std::string>("identifier", "fluid");

Overwritting an existing key with the same or a different data type is possible:

CoSimIO::Info info;

info.Set<int>("echo_level", 1);
info.Set<int>("echo_level", 2);      // this is allowed
info.Set<double>("echo_level", 1.5); // this is allowed

Accessing the Info

After setting some values in the Info, they can be accessed with the Get function (again with specifying the template of the value type):

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

int echo_level = info.Get<int>("echo_level");

If the wrong template is used an error is thrown at runtime:

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

double echo_level = info.Get<double>("echo_level"); // Error, type mismatch, also tells which type was expected

Checking if the Info has a certain key

The Has method can be used to check if the Info contains a specific key. Note that this function is not a template.

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

bool has_echo_level = info.Has("echo_level"); // returns true
bool has_tolerance  = info.Has("tolerance");  // returns false

Getting values with a default

Following the get method of the Python dict, the Get method can also be used with a default value. If the requested key exists in the Info, then the corresponding value is returned. If not, the default is returned.

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

int echo_level = info.Get("echo_level", 2); // returns 1 as "echo_level" exists
int verbosity  = info.Get("verbosity", 2);  // returns 2 as "verbosity" doesn't exist

Checking the size

Size can be used get the number of key-value pairs in the Info.

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

info.Size(); // returns 1

info.Set<double>("tolerance", 0.01);
info.Set<bool>("is_converged", true);
info.Set<std::string>("identifier", "fluid");

info.Size(); // returns 4

Removing specific keys

The method Erase can be used to remove keys from the Info. Note that it does not throw even if the key doesn’t exist.

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

info.Erase("echo_level");
info.Erase("tolerance"); // does not throw!

Removing all keys

The method Clear can be used to remove all keys from the Info.

CoSimIO::Info info;

info.Set<int>("echo_level", 1);

info.Clear(); // removes everything form info

Printing the Info

The Info can be printed to a stream:

CoSimIO::Info info;

info.Set<int>("echo_level", 1);
info.Set<std::string>("identifier", "fluid");

std::cout << info;

/* This prints to standard output:
CoSimIO-Info; containing 2 entries
  name: echo_level | value: 1 | type: int
  name: identifier | value: fluid | type: string
*/

Using Info in Info

Aside from the basic types (int, double, bool, std::string) it is also possible to store an Info in an Info object. The interface is the same as for the other datatypes:

CoSimIO::Info info_1;
CoSimIO::Info info_2;

info_1.Set<CoSimIO::Info>("info", info_2); // this makes a copy of info_2

This makes it possible to build more complex and hierarchical structures of information. Note that the Info is stored as a copy.

Further information

For more information check the implementation and the tests.