To actually use the library various headers need to be included. For this example we use:

aprillibrary.h defines our library class and the initialisation functions. Also, since we've decided to create a world in this example we also include world.h for the definition of World class.

All the definitions in the library are wrapped in following namespace:

using namespace april;

As a final preparation we also define a constant:

enum    Constants       {
    WORLD_ENERGY = 10000
};

to be the total ammount of energy in our world.

initAprilLibrary() needs to be called before making use of the library and will be latter matched by a endAprilLibrary().

    if ( initAprilLibrary() == false )
    {
        cerr << "Error! Failed to initialise april library!\n";
        return 1;
    }

It makes sure to load additional components that the library uses and creates the library singleton that will track resources. The library will fail to work without this initial step.

We are now ready to create our first world:

World * w = new World( "world-name", WORLD_ENERGY );

cout << "World has been created!\n";

We're required to provide a name and the total amount of energy that this world has. The name is used when saving settings and to identify the world in the messages that the library generates. The energy will be a hard limit for all actions that take place in the world. Creating things and performing actions will be limited by this factor.

Now that we have a world let's do something with it:

    cout << "Total ammount of energy in the world: " << w->energy() <<"\n";
    cout << "Unbounded energy in the world: " << w->energyFree() <<"\n";
    cout << "Bounded (\"used\") energy: " << w->energyBounded() <<"\n";

Most of the objects in april library are reference-counted using the implementation in libbbb. The macros simply increment/decrement a counter in release builds, while in debug builds they maintain a list of references with the file, line, function name and pointer address all stored. The constructor creates a reference that is transmitted to the caller, so we have a reference for the World object.

DEC_REF(w,w);

However, the library also owns a reference to the object, so previous opperation will not cause the library to be destroyed. To achieve that goal we may use

AprilLibrary::remWorld( w );

cout << "World has been destroyed!\n";

or we can let endAprilLibrary() take care of this.

The last step is optional - terminate the library. However, it is recomended, mostly in debug builds when the memory tracking is in effect and may spot memory leaks:

endAprilLibrary();

Example 1 - Hello world

april-core library

Example 3 - Running a world