Numerus roman numerals library header. More...

#include "numerus_error_codes.h"

Functions
char *	numerus_double_to_roman (double double_value, int *errcode)
	Converts a double value to a roman numeral with its value. More...

char *	numerus_int_to_roman (long int_value, int *errcode)
	Converts a long integer value to a roman numeral with its value. More...

char *	numerus_int_with_twelfth_to_roman (long int_part, short twelfths, int *errcode)
	Converts an integer value and a number of twelfths to a roman numeral with their sum as value. More...

double	numerus_roman_to_double (char roman, int errcode)
	Converts a roman numeral to its value expressed as a double. More...

long	numerus_roman_to_int (char roman, int errcode)
	Converts a roman numeral to its value floored and expressed as long integer. More...

long	numerus_roman_to_int_part_and_twelfths (char roman, short twelfths, int *errcode)
	Converts a roman numeral to its value expressed as pair of its integer part and number of twelfths. More...

double	numerus_parts_to_double (long int_part, short twelfths)
	Converts a value expressed as sum of an integer part and a number of twelfths to a double. More...

long	numerus_double_to_parts (double value, short *twelfths)
	Splits a double value to a pair of its integer part and a number of twelfths. More...

void	numerus_shorten_and_same_sign_to_parts (long int_part, short twelfths)
	Shortens the twelfths by adding the remainder to the int part so that they have the same sign. More...

short	numerus_is_zero (char roman, int errcode)
	Verifies if the roman numeral is of value 0 (zero). More...

short	numerus_is_long_numeral (char roman, int errcode)
	Verifies if the passed roman numeral is a long roman numeral (if contains a correct number of underscores). More...

short	numerus_is_float_numeral (char roman, int errcode)
	Verifies if the passed roman numeral is a float roman numeral (if contains decimal characters 'S' and dot '. More...

short	numerus_sign (char roman, int errcode)
	Returns the sign of the roman numeral. More...

short	numerus_count_roman_chars (char roman, int errcode)
	Returns the number of roman characters in the roman numeral. More...

short	numerus_compare_value (char roman_bigger, char roman_smaller, int *errcode)
	Compares the values of two roman numerals, emulating the operator '>'. More...

char *	numerus_overline_long_numerals (char roman, int errcode)
	Allocates a string with a prettier representation of a long roman numeral with actual overlining. More...

char *	numerus_create_pretty_value_as_double (double double_value)
	Allocates a string with a prettier representation of a double value of a roman numeral as integer part and shortened twelfth. More...

char *	numerus_create_pretty_value_as_parts (long int_part, short twelfths)
	Allocates a string with a prettier representation of a value as an integer and a number of twelfths, with the twelfths shortened. More...

const char *	numerus_explain_error (int error_code)
	Returns a pointer to the human-friendly text description of any NUMERUS_ERROR_* error code. More...

int	numerus_cli (int argc, char **args)
	Starts a command line interface that converts any typed value to a roman numeral or vice-versa. More...

Variables
const double	NUMERUS_MAX_VALUE
	The maximum value a roman numeral may have. More...

const double	NUMERUS_MIN_VALUE
	The minimum value a roman numeral may have. More...

const long	NUMERUS_MAX_LONG_NONFLOAT_VALUE
	The maximum value a roman numeral with underscores without decimals may have.

const long	NUMERUS_MIN_LONG_NONFLOAT_VALUE
	The minimum value a roman numeral with underscores without decimals may have. More...

const double	NUMERUS_MAX_NONLONG_FLOAT_VALUE
	The maximum value a roman numeral without underscores with decimals may have. More...

const double	NUMERUS_MIN_NONLONG_FLOAT_VALUE
	The minimum value a roman numeral without underscores with decimals may have. More...

const short	NUMERUS_MAX_LENGTH
	The maximum length a roman numeral string may have, including '\0'. More...

const char *	NUMERUS_ZERO
	The roman numeral of value 0 (zero). More...

int	numerus_error_code
	The global error code variable to store any errors during conversions. More...

Detailed Description

Numerus roman numerals library header.

Copyright: Copyright © 2015-2016, Matjaž Guštin dev@m.nosp@m.atja.nosp@m.z.it http://matjaz.it. All rights reserved.

License:: This file is part of the Numerus project which is released under the BSD 3-clause license.

This header allows access to all public functionality of Numerus.

Definition in file numerus.h.

Function Documentation

int numerus_cli	(	int	argc,
		char **	args
	)

Starts a command line interface that converts any typed value to a roman numeral or vice-versa.

The argc and args arguments of the main may be passed to it. This allows any command line parameters passed to the numerus executable to be interpreted as if they were written withing the command line interface. To avoid this option, set argc to 0 and args to anything, e.g. NULL.

Parameters

argc	int number of main arguments. Set to 0 to disable parsing of main arguments.
args	array of main arguments to be parsed as commands.

Returns: int status code: 0 if everything went ok or a NUMERUS_ERROR_* otherwise.

Definition at line 285 of file numerus_cli.c.

short numerus_compare_value	(	char *	roman_bigger,
		char *	roman_smaller,
		int *	errcode
	)

Compares the values of two roman numerals, emulating the operator '>'.

Returns a positive value is the value of the first parameter is bigger than the second, a negative one if the opposite or zero if they have the same value, making it also a check for numeral equality, since two roman numerals have the same value only if they are the same numeral.

The comparison status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occured during the comparison and the returned value is zero. The error code may help find the specific error.

Parameters

*roman_bigger	string containing the roman numeral to compare with roman_smaller
*roman_smaller	string with a roman numeral to compare with the first parameter
*errcode	int where to store the comparison status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: 1 if the first parameter has a bigger value, 0 if they have the same, -1 if the second is bigger.

Definition at line 344 of file numerus_utils.c.

short numerus_count_roman_chars	(	char *	roman,
		int *	errcode
	)

Returns the number of roman characters in the roman numeral.

Does not perform a syntax check or a value check, but does check for illegal characters. The length value does not count the underscores or whitespace.

The analysis status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occurred during the analysis and the returned value is negative. The error code may help find the specific error.

Parameters

*roman	string containing the roman numeral.
*errcode	int where to store the analysis status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: short with the number of roman characters excluding underscores.

Definition at line 266 of file numerus_utils.c.

char* numerus_create_pretty_value_as_double ( double double_value )

Allocates a string with a prettier representation of a double value of a roman numeral as integer part and shortened twelfth.

Remember to free() the pretty-printed value when it's not useful anymore. If a malloc() error occurs during the operation, the returned value is NULL.

Example: -12.5 becomes "-12, -1/2".

Parameters

double_value double value to be converted in a pretty string.

Returns: char* allocated string with the prettier version of the value or NULL if malloc() fails.

Definition at line 574 of file numerus_utils.c.

char* numerus_create_pretty_value_as_parts	(	long	int_part,
		short	twelfths
	)

Allocates a string with a prettier representation of a value as an integer and a number of twelfths, with the twelfths shortened.

Remember to free() the pretty-printed value when it's not useful anymore. If a malloc() error occurs during the operation, the returned value is NULL.

Example: -3, 2 (= -3 + 2/12) becomes "-2, -5/6" (= -2 -10/12).

Parameters

int_part	long integer part of a value to be added to the twelfths and converted to a pretty string.
twelfths	short integer as number of twelfths (1/12) to be added to the integer part and converted to a pretty string.

Returns: char* allocated string with the prettier version of the value or NULL if malloc() fails.

Definition at line 597 of file numerus_utils.c.

long numerus_double_to_parts	(	double	value,
		short *	twelfths
	)

Splits a double value to a pair of its integer part and a number of twelfths.

The twelfths are obtained by rounding the double value to the nearest twelfths. The number of twelfths is stored in the passed parameter, while the integer part is returned directly.

Parameters

value	double to be split into integer part and number of twelfths.
*twelfths	number of twelfths. NULL is interpreted as 0 twelfths.

Returns: long as the integer part of the value of the roman numeral.

Definition at line 728 of file numerus_utils.c.

char* numerus_double_to_roman	(	double	double_value,
		int *	errcode
	)

Converts a double value to a roman numeral with its value.

Accepts any long within [NUMERUS_MAX_VALUE, NUMERUS_MIN_VALUE]. The decimal part of the value is also converted.

Remember to free() the roman numeral when it's not useful anymore.

The conversion status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the the error code is different than NUMERUS_OK, an error occurred during the conversion and the returned string is NULL. The error code may help find the specific error.

Parameters

double_value	double precision floating point value to be converted to roman numeral.
*errcode	int where to store the conversion status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: char* a string containing the roman numeral or NULL when an error occurs.

Definition at line 726 of file numerus_core.c.

const char* numerus_explain_error ( int error_code )

Returns a pointer to the human-friendly text description of any NUMERUS_ERROR_* error code.

Useful to be printed on stderr, stdout or a log file. The error code is hard-coded so no need to free() it afterwards.

Parameters

error_code one of the NUMERUS_ERROR_* error codes or NUMERUS_OK.

Returns: char* pointer to a constant string with the human-friendly text description of the error code.

Definition at line 689 of file numerus_utils.c.

char* numerus_int_to_roman	(	long	int_value,
		int *	errcode
	)

Converts a long integer value to a roman numeral with its value.

Accepts any long within [NUMERUS_MAX_LONG_NONFLOAT_VALUE, NUMERUS_MIN_LONG_NONFLOAT_VALUE].

Remember to free() the roman numeral when it's not useful anymore.

The conversion status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the the error code is different than NUMERUS_OK, an error occurred during the conversion and the returned string is NULL. The error code may help find the specific error.

Parameters

int_value	long integer to be converted to roman numeral.
*errcode	int where to store the conversion status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: char* a string containing the roman numeral or NULL when an error occurs.

Definition at line 700 of file numerus_core.c.

char* numerus_int_with_twelfth_to_roman	(	long	int_part,
		short	twelfths,
		int *	errcode
	)

Converts an integer value and a number of twelfths to a roman numeral with their sum as value.

Accepts any pair of integer value and twelfths so that their sum is within [NUMERUS_MAX_VALUE, NUMERUS_MIN_VALUE].

Remember to free() the roman numeral when it's not useful anymore.

The conversion status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the the error code is different than NUMERUS_OK, an error occurred during the conversion and the returned string is NULL. The error code may help find the specific error.

Parameters

int_part	long integer part of a value to be added to the twelfths and converted to roman numeral.
twelfths	short integer as number of twelfths (1/12) to be added to the integer part and converted to roman numeral.
*errcode	int where to store the conversion status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: char* a string containing the roman numeral or NULL when an error occurs.

Definition at line 757 of file numerus_core.c.

short numerus_is_float_numeral	(	char *	roman,
		int *	errcode
	)

Verifies if the passed roman numeral is a float roman numeral (if contains decimal characters 'S' and dot '.

').

Does not perform a syntax check or a value check, just searches for 'S' and dot '.'. It's case INsensitive.

The analysis status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occurred during the analysis and the returned value is false. The error code may help find the specific error.

Parameters

*roman	string containing the roman numeral.
*errcode	int where to store the analysis status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: short as boolean: true if the numeral contains 'S' or dot '.', false otherwise.

Definition at line 186 of file numerus_utils.c.

short numerus_is_long_numeral	(	char *	roman,
		int *	errcode
	)

Verifies if the passed roman numeral is a long roman numeral (if contains a correct number of underscores).

Does not perform a syntax check or a value check, just searches for underscores. Zero underscores means it's not a long roman numeral, two means it is. Other numbers of underscores result in an error different than NUMERUS_OK.

The analysis status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occurred during the analysis and the returned value is false. The error code may help find the specific error.

Parameters

*roman	string containing the roman numeral.
*errcode	int where to store the analysis status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: short as boolean: true if the numeral is long, false otherwise.

Definition at line 128 of file numerus_utils.c.

short numerus_is_zero	(	char *	roman,
		int *	errcode
	)

Verifies if the roman numeral is of value 0 (zero).

Ignores any leading minus. It's case INsensitive.

The analysis status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occurred during the analysis and the returned value is false. The error code may help find the specific error.

Parameters

*roman	string containing the roman numeral.
*errcode	int where to store the analysis status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: short as boolean: true if the numeral is NUMERUS_ZERO, false otherwise.

Definition at line 98 of file numerus_utils.c.

char* numerus_overline_long_numerals	(	char *	roman,
		int *	errcode
	)

Allocates a string with a prettier representation of a long roman numeral with actual overlining.

Generates a two lined string (newline character is '
') by overlining the part between underscores. The string is just copied if the roman numeral is not long.

Remember to free() the pretty-printed roman numeral when it's not useful anymore and (depending on your necessity) also the roman numeral itself.

Example:

                 ___
-_CXX_VIII  =>  -CXXVIII
VIII        =>   VIII

The prettifying process status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occurred during the prettifying process and the returned string is NULL. The error code may help find the specific error.

Parameters

*roman	string containing the roman numeral.
*errcode	int where to store the comparison status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: char* allocated string with the prettier version of the roman numeral or NULL if malloc() fails.

Definition at line 441 of file numerus_utils.c.

double numerus_parts_to_double	(	long	int_part,
		short	twelfths
	)

Converts a value expressed as sum of an integer part and a number of twelfths to a double.

Parameters

int_part	long integer part of a value to be added to the twelfths and converted to double.
twelfths	short integer as number of twelfths (1/12) to be added to the integer part and converted to double.

Returns: double value as the sum of the integer part and the twelfths.

Definition at line 712 of file numerus_utils.c.

double numerus_roman_to_double	(	char *	roman,
		int *	errcode
	)

Converts a roman numeral to its value expressed as a double.

Accepts many variations of roman numerals:

it's case INsensitive
accepts negative roman numerals (with leading minus '-')
accepts long roman numerals (with character between underscores to denote the part that has a value multiplied by 1000)
accepts decimal value of the roman numerals, those are twelfths (with the characters 'S' and dot '.')
all combinations of the above

The parsing status of the roman numeral (any kind of wrong syntax) is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the the error code is different than NUMERUS_OK, an error occurred during the conversion and the returned value is outside the possible range of values of roman numerals. The error code may help find the specific error.

Parameters

*roman	string with a roman numeral
*errcode	int where to store the conversion status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: double value of the roman numeral or a value outside the the possible range of values when an error occurs.

Definition at line 474 of file numerus_core.c.

long numerus_roman_to_int	(	char *	roman,
		int *	errcode
	)

Converts a roman numeral to its value floored and expressed as long integer.

Accepts many variations of roman numerals:

it's case INsensitive
accepts negative roman numerals (with leading minus '-')
accepts long roman numerals (with character between underscores to denote the part that has a value multiplied by 1000)
accepts decimal value of the roman numerals, those are twelfths (with the characters 'S' and dot '.')
all combinations of the above

The parsing status of the roman numeral (any kind of wrong syntax) is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the the error code is different than NUMERUS_OK, an error occurred during the conversion and the returned value is outside the possible range of values of roman numerals. The error code may help find the specific error.

Parameters

*roman	string with a roman numeral
*errcode	int where to store the conversion status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: long value of the roman numeral or a value outside the the possible range of values when an error occurs.

Definition at line 508 of file numerus_core.c.

long numerus_roman_to_int_part_and_twelfths	(	char *	roman,
		short *	twelfths,
		int *	errcode
	)

Converts a roman numeral to its value expressed as pair of its integer part and number of twelfths.

Accepts many variations of roman numerals:

it's case INsensitive
accepts negative roman numerals (with leading minus '-')
accepts long roman numerals (with character between underscores to denote the part that has a value multiplied by 1000)
accepts decimal value of the roman numerals, those are twelfths (with the characters 'S' and dot '.')
all combinations of the above

The parsing status of the roman numeral (any kind of wrong syntax) is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the the error code is different than NUMERUS_OK, an error occurred during the conversion and the returned value is outside the possible range of values of roman numerals. The error code may help find the specific error.

The number of twelfths is stored in the passed parameter, while the integer part is returned directly.

Parameters

*roman	string with a roman numeral
*errcode	int where to store the conversion status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).
*twelfths	number of twelfths from 0 to 11. NULL is interpreted as 0 twelfths.

Returns: long as the integer part of the value of the roman numeral or a value outside the the possible range of values when an error occurs.

Definition at line 545 of file numerus_core.c.

void numerus_shorten_and_same_sign_to_parts	(	long *	int_part,
		short *	twelfths
	)

Shortens the twelfths by adding the remainder to the int part so that they have the same sign.

It's useful when the twelfths are more than 11 (or -11 if negative). The transformation is performed so that the parts will carry the same sign for better readability.

Example: -3, 2 (= -3 + 2/12) becomes -2, -10 (= -2 -10/12).

Modifies the passed parameters themselves. The sign of the twelfth will be the same of the int part (the int part leads) which is necessary also for a correct conversion to of the parts to roman numeral.

Parameters

*int_part	long integer part of a value.
*twelfths	twelfth of the value.

Returns: void since modifies the passed values.

Definition at line 548 of file numerus_utils.c.

short numerus_sign	(	char *	roman,
		int *	errcode
	)

Returns the sign of the roman numeral.

Does not perform a syntax check or a value check, just searches for the sign. If the numeral has value zero, returns 0; if the numeral has a leading minus '-', returns -1; otherwise +1.

The analysis status is stored in the errcode passed as parameter, which can be NULL to ignore the error, although it's not recommended. If the error code is different than NUMERUS_OK, an error occurred during the analysis and the returned value is 0 (zero). The error code may help find the specific error.

Parameters

*roman	string containing the roman numeral.
*errcode	int where to store the analysis status: NUMERUS_OK or any other error. Can be NULL to ignore the error (NOT recommended).

Returns: short with the sign of the roman numeral: 0 if has value zero, -1 if negative, +1 if positive.

Definition at line 232 of file numerus_utils.c.

Variable Documentation

int numerus_error_code

The global error code variable to store any errors during conversions.

It may contain any of the NUMERUS_ERROR_* error codes or NUMERUS_OK.

Definition at line 105 of file numerus_core.c.

const short NUMERUS_MAX_LENGTH

The maximum length a roman numeral string may have, including '\0'.

The roman numeral "-_MMMDCCCLXXXVIII_DCCCLXXXVIIIS....." (value: -3888888, -11/12) + \0 is a string long 36+1 = 37 chars.

Definition at line 93 of file numerus_core.c.

const double NUMERUS_MAX_NONLONG_FLOAT_VALUE

The maximum value a roman numeral without underscores with decimals may have.

If you floor() this value, you get the maximum value the standard roman syntax allows.

Definition at line 67 of file numerus_core.c.

const double NUMERUS_MAX_VALUE

The maximum value a roman numeral may have.

This is for a positive long and float roman numeral. It exceeds the actual maximum value by 1/24 because conversion functions round the value to the nearest 12th.

Definition at line 40 of file numerus_core.c.

const long NUMERUS_MIN_LONG_NONFLOAT_VALUE

The minimum value a roman numeral with underscores without decimals may have.

It's the opposite of NUMERUS_MAX_LONG_NONFLOAT_VALUE.s

Definition at line 48 of file numerus_core.c.

const double NUMERUS_MIN_NONLONG_FLOAT_VALUE

The minimum value a roman numeral without underscores with decimals may have.

If you ceil() this value, you get the minimum value the standard roman syntax allows.

Definition at line 76 of file numerus_core.c.

const double NUMERUS_MIN_VALUE

The minimum value a roman numeral may have.

It's the opposite of NUMERUS_MAX_VALUE. This is for a negative long and float roman numeral. It is below the actual maximum value by 1/24 because conversion functions round the value to the nearest 12th.

Definition at line 58 of file numerus_core.c.

const char* NUMERUS_ZERO

The roman numeral of value 0 (zero).

Both for positive and negative zero.

Definition at line 84 of file numerus_core.c.

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation