Numerus  v2.0.0
Roman numerals conversion and manipulation C library.
Numerus Documentation
The most awesomnest roman numerals library

Numerus is a comprehensive C library that allows conversion and manipulation of roman numerals - now with it's own shell.

What is this?

Roman numerals are the numeric system used in ancient Rome based on combinations of letters from the Latin alphabet to signify values. Wikipedia has a nice article on them.

This library allows you to convert roman numerals to values and values to roman numerals, adds some extensions to them to support big and float values that other converters of the same kind usually don't, focuses on optimization, clean code and error handling. Also offers a Numerus shell to convert values on-the-fly or by pipelining (on Unix-like OS) without the need to incorporate the library in an existing project.

For a shorter explanation on how roman numerals works in Numerus and what Numerus supports, check the Numerus syntax page.

Download, compile and use

1. Download

Download a zip/tarball of the library and unpack it or clone the repository. On a Unix-like OS, you can also use the command line with:

1 # Wget users
2 wget -qO - | tar -zx ; cd Numerus-*
4 # Curl users
5 curl -fsSL | tar -zx ; cd Numerus-*
7 # Git users
8 git clone ; cd Numerus

2a. Using the Numerus CLI

Then, if you desire to just use Numerus directly with its build-in command line interface (CLI) without incorporating it into an existing project, compile it with cmake and run it. On a Unix-like OS, do it with the following one-liner in the Numerus root folder:

1 # Creates a `bin` directory, builds Numerus into it and runs it
2 mkdir -p bin ; cd bin ; cmake .. ; make ; ./numerus ; cd -
  • Hint 1: type the help command in the CLI for assistance
  • Hint 2: check the Numerus syntax page for some rules on how to write roman numerals.

2b. Using Numerus in your project

To use it as a library, add it to your project, include the Numerus header file and you're good to go!

#include "numerus.h"

You'll probably need the conversion functions: those are the first 6 functions in the Numerus header file. Check the Numerus usage examples for a quick tutorial on how to use Numerus and the Numerus syntax page for rules on how to write roman numerals and why Numerus uses some strange names such as long numeral. Everything else, including functions, parameters, constant and error codes is explained in the web documentation (thanks Doxygen!).

What's the point of this library?

Nobody is probably going to need YET another roman numerals conversion tool. Numerus was created:

  • mostly for fun,
  • as a coding exercise,
  • to learn how to create clean code,
  • to learn C
  • to be able to optimize code,
  • to understand what a good in-code and web documentation is and how to write it with Doxygen,
  • to get better at using git and GitHub.


Numerus is released under the BSD 3-clause license which basically allows you to do anything with it as long as you credit the original author (more or less).

Credits and thanks

Matjaž Guštin For any suggestions please contact me.

Numerus is a port of my (not-really-as-complete-as-this-one but functioning) project with the same name in Java.

The inspirations for the conversion functions were:

The SQLite3 library offered many ideas on keeping the code clean and creating a nice API.