Documentation for Octaspire Core library version 0.29.0

About

Octaspire Core is a container, utf-8 and utility library written in standard C99. It depends only on a C99 compiler and standard library.

Octaspire Core is used by some other Octaspire projects like Dern, Maze and Lightboard, but it should be usable on many different platforms and projects where region allocator or containers like vector, hash-map, pair or utf-8 string are needed.

Octaspire Core is licensed under the Apache License, Version 2.0. See file LICENSE in the source distribution for more information.

Octaspire Core uses Semantic Versioning 2.0.0 version numbering scheme. As long as the MAJOR version number is zero anything can change at any time, even in backwards incompatible manner.

Note
This library is not yet finished, and is still a work in progress to some extent. Unit tests and use in projects like Dern, Maze and Lightboard have helped to catch and fix quite a many bugs already, but there are still some features not yet implemented and probably bugs not yet fixed. Also, English in not my native language, so please bear with me, when reading this documentation.
Note
This documentation is work in progress.

Core uses Semantic Versioning 2.0.0 version numbering scheme. As long as the MAJOR version number is zero anything can change at any time, even in backwards incompatible manner.

Building from source

Raspberry Pi, Debian and Ubuntu

To build Octaspire Core from source in Raspberry Pi, Debian or Ubuntu (16.04 LTS) system:

sudo apt-get install cmake git
git clone https://github.com/octaspire/core.git
cd core/build
cmake ..
make

Arch Linux

To build on Arch Linux (Arch Linux ARM) system:

sudo pacman -S cmake git gcc make
git clone https://github.com/octaspire/core.git
cd core/build
cmake ..
make

Haiku

To build on Haiku (Version Walter (Revision hrev51127) x86_gcc2):

pkgman install gcc_x86 cmake_x86
git clone https://github.com/octaspire/core.git
cd core/build
CC=gcc-x86 cmake ..
make

FreeBSD

To build on FreeBSD (FreeBSD-11.0-RELEASE-arm-armv6-RPI2) system:

sudo pkg install git cmake
git clone https://github.com/octaspire/core.git
cd core/build
cmake ..
make

MINIX 3

To build on MINIX 3 (minix_R3.3.0-588a35b) system:

su root
pkgin install cmake clang binutils git-base
exit
git clone git://github.com/octaspire/core
cd core/build
cmake ..
make

Other systems

On different systems the required commands can vary. In any case, You should install a C compiler, cmake and git.

Running unit tests

This is all there should be to it; when make finishes, everything should be ready.

To run the unit tests:

test/octaspire-core-test-runner
Note
Man pages are not ready yet.

Quick tour of library features

Here we take a quick look at the features of the library.

Naming

C doesn’t have namespaces. To prevent name collisions, all names in the library are prefixed with octaspire_. For example, octaspire_container_utf8_string_t is the string type and octaspire_container_utf8_string_new is one of the functions that create new strings. octaspire_container_vector_t is the vector type and octaspire_container_hash_map_t is the hash-map type.

These names can be pretty long, and quite annoying to write in the long run. I personally like to use the abbrevation features of vi/vim and emacs editors. You can see this setup in my dotfiles for nvi, vim and emacs editors. Your favorite editor or IDE might have similar functionality also available.

So, I can write ocus and hit the spacebar to get octaspire_container_utf8_string_. The table below lists some of the abbrevations I use:

ocus

octaspire_container_utf8_string_

ocve

octaspire_container_vector_

ochm

octaspire_container_hash_map_

ochme

octaspire_container_hash_map_element_

Allocator with and without regions

TODO

UTF-8 Strings

string-example.c
/***********************************************************************
 * To compile this file from the 'examples' directory:
 * c99 -Wall -Wextra -pedantic -I ../../include/ string-example.c
 *     -lm -L ../../build/ -loctaspire-core -o string-example
 **********************************************************************/
#include <stdio.h>
#include <octaspire/core/octaspire_container_utf8_string.h>

int main(void)
{
    octaspire_memory_allocator_t *allocator =
        octaspire_memory_allocator_new(0);

    octaspire_container_utf8_string_t *myStr =
        octaspire_container_utf8_string_new("Hello world!", allocator);

    printf(
        "String is \"%s\"\n",
        octaspire_container_utf8_string_get_c_string(myStr));

    octaspire_container_utf8_string_release(myStr);
    myStr = 0;

    octaspire_memory_allocator_release(allocator);
    allocator = 0;

    return 0;
}

Vector

vector-example.c
/***********************************************************************
 * To compile this file from the 'examples' directory:
 * c99 -Wall -Wextra -pedantic -I ../../include/ vector-example.c
 *     -lm -L ../../build/ -loctaspire-core -o vector-example
 **********************************************************************/
#include <stdio.h>
#include <octaspire/core/octaspire_container_utf8_string.h>
#include <octaspire/core/octaspire_container_vector.h>

int main(void)
{
    octaspire_memory_allocator_t *allocator =
        octaspire_memory_allocator_new(0);

    octaspire_container_vector_t *v = octaspire_container_vector_new(
        sizeof(octaspire_container_utf8_string_t*),
        true,
        (octaspire_container_vector_element_callback_t)
            octaspire_container_utf8_string_release,
        allocator);

    for (size_t i = 0; i < 10; ++i)
    {
        octaspire_container_utf8_string_t *s =
            octaspire_container_utf8_string_new_format(
                allocator,
                "Hello %zu world!",
                i);

        if (!octaspire_container_vector_push_back_element(v, &s))
        {
            printf("Cannot insert string to vector\n");
        }
    }

    for (size_t i = 0; i < octaspire_container_vector_get_length(v); ++i)
    {
        octaspire_container_utf8_string_t const * const s =
            octaspire_container_vector_get_element_at_const(v, i);

        printf(
            "String %zu. is: %s\n",
            i,
            octaspire_container_utf8_string_get_c_string(s));
    }

    octaspire_container_vector_release(v);
    v = 0;

    octaspire_memory_allocator_release(allocator);
    allocator = 0;

    return 0;
}

Pair

TODO

Hash map

hash-map-example.c
/***********************************************************************
 * To compile this file from the 'examples' directory:
 * c99 -Wall -Wextra -pedantic -I ../../include/ hash-map-example.c
 *     -lm -L ../../build/ -loctaspire-core -o hash-map-example
 **********************************************************************/
#include <stdio.h>
#include <octaspire/core/octaspire_container_utf8_string.h>
#include <octaspire/core/octaspire_container_hash_map.h>

int main(void)
{
    octaspire_memory_allocator_t *allocator =
        octaspire_memory_allocator_new(0);

    octaspire_container_hash_map_t * h =
        octaspire_container_hash_map_new_with_octaspire_container_utf8_string_keys(
            sizeof(float),
            false,
            (octaspire_container_hash_map_element_callback_function_t)0,
            allocator);


    for (size_t i = 0; i < 10; ++i)
    {
        octaspire_container_utf8_string_t *s =
            octaspire_container_utf8_string_new_format(allocator, "Item %zu!", i);

        float const value = i * 3.14;

        if (!octaspire_container_hash_map_put(
            h,
            octaspire_container_utf8_string_get_hash(s),
            &s,
            &value))
        {
            printf("Cannot insert element to hash map\n");
        }
    }

    for (size_t i = 0; i < octaspire_container_hash_map_get_number_of_elements(h); ++i)
    {
        octaspire_container_utf8_string_t *s =
            octaspire_container_utf8_string_new_format(allocator, "Item %zu!", i);

        octaspire_container_hash_map_element_t const * const element =
            octaspire_container_hash_map_get_const(
                h,
                octaspire_container_utf8_string_get_hash(s),
                &s);

        float const value =
            *(float const * const)octaspire_container_hash_map_element_get_value(element);

        printf(
            "%s -> %f\n",
            octaspire_container_utf8_string_get_c_string(s),
            value);

        octaspire_container_utf8_string_release(s);
        s = 0;
    }

    octaspire_container_hash_map_release(h);
    h = 0;

    octaspire_memory_allocator_release(allocator);
    allocator = 0;

    return 0;
}

Input streams from memory and files

TODO

Lower level helpers

TODO