While some of the components of a world may be created by hand, the focus is on being able to create and recreate components. To be able to do so we use a centralised system of IDs and a set of factories described below.

The management of the IDs is govern by the UniqueId class. However, since an instance is embedded in the World, we will discuss it in this context.

We are basically storing a list of 64-bit numbers associated or not with a describing string. Setting the value for an ID (that is created if it does not exist) is done as follows:

w->insertId( 1, "some-text" );

In this case the ID 1 is created if it does not exists and the label "some-text" is associated with it.

Somehow similar is:

    cout << "'some-text' at ID: " 
         <<  w->checkAddId( "some-text" )
          << "\n";
    cout << "'different-text' at ID: " 
         <<  w->checkAddId( "different-text" )
          << "\n";

This attempts to locate the string just like World::nameForId() does but, if it not found, next free ID is allocated and the string is associated with it.

Blindly adding an ID with or without an associated string uses an internaly cached counter so that the search for a free ID is fast. This also means that the values may have gaps, with some low order IDs not used.

    cout << "ID autogenerated and no associated string: " 
         <<  w->addNewId()
         << "\n";
    cout << "ID autogenerated and associated string: " 
         <<  w->addNewId( "associated string" )
         << "\n";

Retrieving the text associated with a particular ID done as so:

    cout << "Text associated with ID 1: "
         << w->nameForId( 1 ).toLatin1().constBegin()
         << "\n"; // "some-text"

will return an empty string if the ID has not been defined, yet.

Following method only sets the text if the id is not defined. In our case, because 1 was already present the text is not modified. ID 2, however, does not exists, yet, so the text associated with ID 2 is "default-text"

    w->checkAddId( 1, "default-text" );
    w->checkAddId( 2, "default-text" );
    cout << "Text associated with ID 1: " 
         << w->nameForId( 1 ).toLatin1().constBegin()
         << "\n"; // "some-text"
    cout << "Text associated with ID 2: " 
         << w->nameForId( 2 ).toLatin1().constBegin()
         << "\n"; // "default-text"

Finding an ID based on the string is also possible. First ID that matches the search is returned or InvalidId if none is found. Note that the search is case sensitive and there is no pattern support.

    cout << "Searching '' (empty string) returns: " 
         << w->idValue( "" )
         << "\n"; // 0 = InvalidId
    cout << "Searching 'text' returns: "
         << w->idValue( "text" ) 
         << "\n"; // 0 = InvalidId
    cout << "Searching 'some-text' returns: " 
         << w->idValue( "some-text" ) 
         << "\n"; // 1
    cout << "Searching 'default-text' returns: "
         << w->idValue( "default-text" )
         << "\n"; // 2

It should also be noted that UniqueId is capable of storing and loading the list of values and associated strings, capability that is used in saving/restoring a a world.

Example 3 - Running a world

april-core library

Example 5 - DNA