Info

Main Page of Documentation

Table of Contents

• Memory management
• Setting values
• Accessing the Info
• Checking if the Info has a certain key
• Checking the size
• Removing specific keys
• Removing all keys
• Using Info in Info
• Further information

---

This page describes the C interface of CoSimIO::Info. See here for more information and the native (C++) interface.

Memory management

The CoSimIO_Info object is allocated with CoSimIO_CreateInfo and freed with CoSimIO_FreeInfo. This is crucial as otherwise memory is leaked!

// create CoSimIO_Info
CoSimIO_Info info = CoSimIO_CreateInfo();

// use info
// ...

// don't forget to free it after using it
CoSimIO_FreeInfo(info);

Setting values

The Set... methods can be used to set values in the Info. The first argument is the key (given as char*), the second is the value.

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

CoSimIO_FreeInfo(info);

One Info object can hold several types:

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);
CoSimIO_Info_SetDouble(info, "tolerance", 0.01);
CoSimIO_Info_SetBool(info, "is_converged", 1);
CoSimIO_Info_SetString(info, "identifier", "fluid");

CoSimIO_FreeInfo(info);

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

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);
CoSimIO_Info_SetInt(info, "echo_level", 2);      // this is allowed
CoSimIO_Info_SetDouble(info, "echo_level", 1.5); // this is allowed

CoSimIO_FreeInfo(info);

Accessing the Info

After setting some values in the Info, they can be accessed with the Get... functions:

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

int echo_level = CoSimIO_Info_GetInt(info, "echo_level");

CoSimIO_FreeInfo(info);

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

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

double echo_level = CoSimIO_Info_GetDouble(info, "echo_level"); // Error, type mismatch, also tells which type was expected

CoSimIO_FreeInfo(info);

Checking if the Info has a certain key

The Has method can be used to check if the Info contains a specific key.

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

int has_echo_level = CoSimIO_Info_Has(info, "echo_level"); // returns 1
int has_tolerance  = CoSimIO_Info_Has(info, "tolerance");  // returns 0

CoSimIO_FreeInfo(info);

Checking the size

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

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

CoSimIO_Info_Size(info); // returns 1

CoSimIO_Info_SetDouble(info, "tolerance", 0.01);
CoSimIO_Info_SetBool(info, "is_converged", 1);
CoSimIO_Info_SetString(info, "identifier", "fluid");

CoSimIO_Info_Size(info); // returns 4

CoSimIO_FreeInfo(info);

Removing specific keys

The method CoSimIO_Info_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 = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

CoSimIO_Info_Erase(info, "echo_level");
CoSimIO_Info_Erase(info, "tolerance"); // does not throw!

CoSimIO_FreeInfo(info);

Removing all keys

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

CoSimIO_Info info = CoSimIO_CreateInfo();

CoSimIO_Info_SetInt(info, "echo_level", 1);

CoSimIO_Info_Clear(info);  // removes everything form info

CoSimIO_FreeInfo(info);

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_CreateInfo();
CoSimIO_Info info_2 = CoSimIO_CreateInfo();

CoSimIO_Info_SetInfo(info_1, "sub_info", info_2); // this makes a copy of info_2

CoSimIO_Info retrieved_info = CoSimIO_Info_GetInfo(info, "sub_info"); // this is copied hence needs to be freed

CoSimIO_FreeInfo(info_1);
CoSimIO_FreeInfo(info_2);
CoSimIO_FreeInfo(retrieved_info);

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.