floaxie

Floaxie is C++14 header-only library for fast printing floating point values of arbitrary precision (float, double etc.) and parsing their textual representation back again (in ordinary or exponent notation).

What is it for?

One is obviously not worried too much about the speed of the values being printed on the console, so the primary places to use the library are readers, writers, encoders and decoders of different text-based formats (e.g. JSON, XML and so on), applications interacting through text pipes or rendering data structures.

Please, take a look also at the alternatives solving the same problem mentioned in the benchmark of @miloyip here, if floaxie doesn't suite you well.

Compiler compatibility

GCC 5
Clang 3.6
Visual Studio 2017 15.0

Printing

Grisu2 algorithm is adopted for printing floating point values. It is fast printing algorithm described by Florian Loitsch in his Printing Floating-Point Numbers Quickly and Accurately with Integers paper. Grisu2 is chosen as probably the fastest grisu version, for cases, where shortest possible representation in 100% of cases is not ultimately important. Still it guarantees the best possible efficiency of more, than 99%.

Parsing

The opposite to Grisu algorithm used for printing, an algorithm on the same theoretical base, but for parsing, is developed. Following the analogue of Grisu naming, who essentially appears to be cartoon character (Dragon), parsing algorithm is named after another animated character, rabbit, Krosh:

The algorithm parses decimal mantissa to extent of slightly more decimal digit capacity of floating point types, chooses a pre-calculated decimal power and then multiplies the two. Since the rounding problem is not uncommon during such operations, and, in contrast to printing problem, one can't just return incorrectly rounded parsing results, such cases are detected instead and slower, but accurate fallback conversion is performed (C Standard Library functions like strtod() by default). In this respect Krosh is closer to Grisu3.

Example

Printing:

#include <iostream>

#include "floaxie/ftoa.h"

using namespace std;
using namespace floaxie;

int main(int, char**)
{
	double pi = 0.1;
	char buffer[128];

	ftoa(pi, buffer);
	cout << "pi: " << pi << ", buffer: " << buffer << endl;

	return 0;
}

Parsing:

#include <iostream>

#include "floaxie/atof.h"

using namespace std;
using namespace floaxie;

int main(int, char**)
{
	char str[] = "0.1";
	char* str_end;
	double pi = 0;

	pi = atof<double>(str, &str_end);
	cout << "pi: " << pi << ", str: " << str << ", str_end: " << str_end << endl;

	return 0;
}

Building

Building is not required and completely optional, unless you would like to try the examples or tests or build the local documentation. Inside git project tree it can be done like this:

git submodule update --init # to check out common CMake modules' submodule
mkdir build && cd build
cmake -DBUILD_EXAMPLES=1 -DBUILD_TESTS=1 -DBUILD_DOCUMENTATION=1 ../ # switch on the desired flags
cmake --build . # or just `make` on systems with it

Adding to the project

git submodule add https://github.com/aclex/floaxie <desired-path-in-your-project>

Don't forget to do git submodule update --init --recursive out of your project tree to pull submodules properly.

Including to CMake project as a subproject

Since version 1.2 it's possible to include Floaxie as a subproject in any CMake project quite easily thanks to modern CMake INTERFACE_LIBRARY target facilities. Unfortunately, this works fully since CMake 3.13, so its minimum required version had to be increased.

CMakeLists.txt of a consumer CMake project would look like this (given Floaxie is cloned to floaxie subdirectory)':

project(foo)

cmake_minimum_required(VERSION 3.13)

# `EXCLUDE_FOR_ALL` here to exclude supplementary targets
# like `install` from the main project target set
add_subdirectory(peli EXCLUDE_FROM_ALL) 

add_executable(foo_main foo_main.cpp)
target_link_libraries(foo_main PUBLIC floaxie)

aclex / floaxie