Numerus utility functions for roman numerals and values manipulation. More...

#include <math.h>
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdbool.h>
#include "numerus_internal.h"

Functions
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...

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...

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...

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...

Detailed Description

Numerus utility functions for roman numerals and values manipulation.

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 file contains functions that analyze roman numerals, perform some checks on them or convert some values in other formats. Functions that create a more human-readable output are also placed in this file.

Definition in file numerus_utils.c.

Function Documentation

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.

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.

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.

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.