Home

Awesome

ffbase

ffbase is a fast C library which implements base containers & algorithms.

C language doesn't have this functionality by default (contrary to almost all other languages which have their rich standard library out of the box) and ffbase attempts to fill this hole.

ffbase is header-only (.h-only) and doesn't need to be built into .a/.so/.dll before use - you just include .h file and that's all.

Contents:

Naming

As there are no namespaces in C, everything here starts with an ff prefix. Then follows the short prefix for the namespace (or a context) and then the name of the function. For example:

All components follow this convention.

Features

String/text:

FileDescription
string.hString container
stringz.hNULL-terminated string functions
unicode.hUnicode functions

Containers:

FileDescription
slice.hSimple array container
vector.hArray container
sort.hArray sorting (merge-sort)
chain.hSimple chain
list.hDoubly-linked list
rbtree.hRed-black tree
map.hHash table
ringueue.hFixed-size lockless ring queue, multi-producer, multi-consumer
ring.hFixed-size lockless ring buffer, multi-producer, multi-consumer
fntree.hFile name tree with economical memory management

JSON:

FileDescription
json.hLow-level JSON parser
json-scheme.hJSON parser with scheme
json-writer.hJSON writer

Atomic:

FileDescription
atomic.hAtomic operations
lock.hSpinlock

Other:

FileDescription
args.hProcess command-line arguments
conf.hLow-level key-value settings parser (SSE4.2)
time.hDate/time functions
cpuid.hGet CPU features

Requirements:

Where to use

In C and C++ projects that require fast and small code without unnecessary dependencies.

How to use

  1. Clone ffbase repo:

     $ git clone https://github.com/stsaz/ffbase
    
  2. In your build script:

     -IFFBASE_DIR
    

where FFBASE_DIR is your ffbase/ directory.

  1. And then just use the necessary files:

     #include <ffbase/slice.h>
    

Use just 1 file

To avoid copying the whole ffbase repo into your project while all you need is, for example, "slices", you may just copy a few files to your project directory.

  1. Clone ffbase repo and copy the necessary files:

     $ git clone https://github.com/stsaz/ffbase
     $ mkdir YOUR_PROJECT/include/ffbase/
     $ cp ffbase/ffbase/slice.h ffbase/ffbase/base.h  YOUR_PROJECT/include/ffbase/
    

    where YOUR_PROJECT is your project's directory.

  2. Then, edit YOUR_PROJECT/include/ffbase/slice.h and remove the dependencies (marked as optional) you don't need, for example:

     #ifndef _FFBASE_BASE_H
     #include <ffbase/base.h>
     #endif
     -#include <ffbase/sort.h> // optional
     +// #include <ffbase/sort.h> // optional
    

    Or you can copy sort.h file too if you need it.

  3. In your build script:

     -IYOUR_PROJECT/include
    
  4. And then just use the necessary files:

     #include <ffbase/slice.h>
    

Configure

Use these preprocessor definitions to enable new functionality or to change the existing logic:

Preprocessor FlagDescription
FF_DEBUGUse additional assert() checks when debugging
FFBASE_HAVE_FFERR_STREnable "%E" for format strings
_FFBASE_MEM_ALLOCDon't define ffmem_* allocation functions (user must define them)
FFBASE_MEM_ASSERTCall assert() when memory allocation fails
FFBASE_OPT_SIZEMark heavy functions as extern. User must compile the appropriate .c files manually.

To enable SSE4.2 code use -msse4.2 compiler flag and provide storage for int _ffcpu_features.

Develop

Add new file

Header:

/** ffbase: description
Year, Author Name
*/

Unique ID for the optional .h files, so their includers can disable the functionality:

#define _FFBASE_SORT_H

Don't use any standard functions directly, otherwise it will be impossible to substitute the lower level functions. For example, don't use memcpy() - use ffmem_copy() instead. This gives us the ability to easily add functionality such as counting the number of bytes copied per thread, before actually calling memcpy().

Test

cd test
make
./fftest all

on FreeBSD:

gmake

on Linux for Windows:

make OS=windows

To another directory:

mkdir /tmp/ffbase
cd /tmp/ffbase
make -Rrf MYSRC/ffbase/test/Makefile SRCDIR=MYSRC/ffbase
cp -ruv MYSRC/ffbase/test/data /tmp/ffbase
./fftest all

Commit

Message: