Decimal

Data Structures
struct	M_decimal_t

Enumerations
enum	M_DECIMAL_RETVAL {   M_DECIMAL_SUCCESS = 0 ,   M_DECIMAL_OVERFLOW = 1 ,   M_DECIMAL_TRUNCATION = 2 ,   M_DECIMAL_INVALID = 3 }
enum	M_decimal_round_t {   M_DECIMAL_ROUND_NONE = 0 ,   M_DECIMAL_ROUND_TRADITIONAL = 1 ,   M_DECIMAL_ROUND_BANKERS = 2 }

Functions
void	M_decimal_create (M_decimal_t *dec)
void	M_decimal_from_int (M_decimal_t *dec, M_int64 integer, M_uint8 implied_dec)
M_int64	M_decimal_to_int (const M_decimal_t *dec, M_uint8 implied_dec)
enum M_DECIMAL_RETVAL	M_decimal_from_str (const char *string, size_t len, M_decimal_t *val, const char **endptr)
enum M_DECIMAL_RETVAL	M_decimal_to_str (const M_decimal_t *dec, char *buf, size_t buf_len)
M_int8	M_decimal_cmp (const M_decimal_t *dec1, const M_decimal_t *dec2)
enum M_DECIMAL_RETVAL	M_decimal_transform (M_decimal_t *dec, M_uint8 num_dec, M_decimal_round_t round)
void	M_decimal_reduce (M_decimal_t *dec)
M_uint8	M_decimal_num_decimals (const M_decimal_t *dec)
void	M_decimal_duplicate (M_decimal_t *dest, const M_decimal_t *src)
enum M_DECIMAL_RETVAL	M_decimal_multiply (M_decimal_t *dest, const M_decimal_t *dec1, const M_decimal_t *dec2)
enum M_DECIMAL_RETVAL	M_decimal_divide (M_decimal_t *dest, const M_decimal_t *dec1, const M_decimal_t *dec2, M_decimal_round_t round)
enum M_DECIMAL_RETVAL	M_decimal_subtract (M_decimal_t *dest, const M_decimal_t *dec1, const M_decimal_t *dec2)
enum M_DECIMAL_RETVAL	M_decimal_add (M_decimal_t *dest, const M_decimal_t *dec1, const M_decimal_t *dec2)

Detailed Description

Floating point number type. Used instead of double or float to elimiate rounding errors.

Example:

const char  *s1 = "1.01";
const char  *s2 = "0.001";
M_decimal_t  d1;
M_decimal_t  d2;
char         out[16];
 
M_mem_set(out, 0, sizeof(out));
 
M_decimal_from_str(s1, M_str_len(s1), &d1, NULL);
M_decimal_from_str(s2, M_str_len(s2), &d2, NULL);
M_decimal_add(&d1, &d1, &d2);
M_decimal_reduce(&d1);
 
if (M_decimal_to_str(&d1, out, sizeof(out)) != M_DECIMAL_SUCCESS) {
    M_printf("failure\n");
} else {
    M_printf("out='%s'\n", out);
}

Example output:

out='1.011'

---

Data Structure Documentation

M_decimal_t

struct M_decimal_t

Structure defining storage for decimal numbers.

This structure should never be touched directly. It is only made public to reduce the overhead of using this datatype (no malloc needed).

Data Fields
M_int64	num	Number represented.
M_uint8	num_dec	How many implied decimal places.

Enumeration Type Documentation

M_DECIMAL_RETVAL

enum M_DECIMAL_RETVAL

Result/Error codes for M_decimal functions.

Enumerator
M_DECIMAL_SUCCESS	Operation successful.
M_DECIMAL_OVERFLOW	An overflow occurred in the operation.
M_DECIMAL_TRUNCATION	The result was truncated/rounded in order to approximate the best result. This is true on most divide operations.
M_DECIMAL_INVALID	Invalid data.

M_decimal_round_t

enum M_decimal_round_t

Rounding formula

Enumerator
M_DECIMAL_ROUND_NONE	Truncate
M_DECIMAL_ROUND_TRADITIONAL	Traditional, aka Round Half away from Zero.
M_DECIMAL_ROUND_BANKERS	Bankers, aka Round Half to Even

Function Documentation

M_decimal_create()

void M_decimal_create

(

M_decimal_t *

dec

)

Create new zero'd out decimal number.

Parameters

[out]

dec

New decimal output.

M_decimal_from_int()

void M_decimal_from_int	(	M_decimal_t *	dec,
		M_int64	integer,
		M_uint8	implied_dec
	)

Convert to a decimal representation from an integer

Parameters

[out]	dec	New decimal output.
[in]	integer	Integer to convert to decimal.
[in]	implied_dec	Number of implied decimals in integer input.

M_decimal_to_int()

M_int64 M_decimal_to_int	(	const M_decimal_t *	dec,
		M_uint8	implied_dec
	)

Convert from a decimal representation to an integer with implied decimal places. If the conversion causes truncation, the number will be rounded. For example a decimal of 123.456, with implied decimals 2, will return 12346.

Parameters

[in]	dec	Decimal type
[in]	implied_dec	Number of implied decimal positions.

Returns

Rounded integer representation of number.

M_decimal_from_str()

enum M_DECIMAL_RETVAL M_decimal_from_str	(	const char *	string,
		size_t	len,
		M_decimal_t *	val,
		const char **	endptr
	)

Convert to a decimal representation from a string.

Parameters

[in]	string	Buffer with decimal representation.
[in]	len	Length of bytes to evaluate from string.
[out]	val	New decimal output.
[out]	endptr	Pointer to end of evaluated decimal.

Returns

One of the enum M_DECIMAL_RETVAL values.

M_decimal_to_str()

enum M_DECIMAL_RETVAL M_decimal_to_str	(	const M_decimal_t *	dec,
		char *	buf,
		size_t	buf_len
	)

Convert from a decimal representation to a string.

Parameters

[in]	dec	Decimal type.
[out]	buf	Buffer to output string representation.
[in]	buf_len	Length of output buffer.

Returns

One of the enum M_DECIMAL_RETVAL values.

M_decimal_cmp()

M_int8 M_decimal_cmp	(	const M_decimal_t *	dec1,
		const M_decimal_t *	dec2
	)

Compare 2 decimals.

Parameters

[in]	dec1	Decimal 1.
[in]	dec2	Decimal 2.

Returns

-1 if dec1 < dec2, 0 if dec1 == dec2, 1 if dec1 > dec2.

M_decimal_transform()

enum M_DECIMAL_RETVAL M_decimal_transform	(	M_decimal_t *	dec,
		M_uint8	num_dec,
		M_decimal_round_t	round
	)

Transform decimal number representation to have the specified number of decimal places (rounding if needed).

Parameters

[in,out]	dec	Decimal type.
[in]	num_dec	Number of decimal places number should be transformed to.
[in]	round	Round method to use when rounding.

Returns

One of the enum M_DECIMAL_RETVAL values.

M_decimal_reduce()

void M_decimal_reduce

(

M_decimal_t *

dec

)

Reduce the decimal representation to the smallest number of decimal places possible without reducing precision (remove trailing zeros).

Parameters

[in,out]

dec

Decimal type.

M_decimal_num_decimals()

M_uint8 M_decimal_num_decimals

(

const M_decimal_t *

dec

)

Number of decimal places present in the M_decimal_t representation.

Parameters

[in]

dec

Decimal type.

Returns

Number of decimals currently represented by type.

M_decimal_duplicate()

void M_decimal_duplicate	(	M_decimal_t *	dest,
		const M_decimal_t *	src
	)

Copy the decimal object from the source into the destination

Parameters

[out]	dest	New decimal duplicated from src.
[in]	src	Decimal type to copy.

M_decimal_multiply()

enum M_DECIMAL_RETVAL M_decimal_multiply	(	M_decimal_t *	dest,
		const M_decimal_t *	dec1,
		const M_decimal_t *	dec2
	)

Multiply the two decimals together putting the result in dest.

The destination and one of the sources may be the same. The number of resulting decimal places will be the same as the largest input.

Parameters

[out]	dest	New decimal with result.
[in]	dec1	First decimal to multiply.
[in]	dec2	Second decimal to multiply.

Returns

One of the enum M_DECIMAL_RETVAL values.

M_decimal_divide()

enum M_DECIMAL_RETVAL M_decimal_divide	(	M_decimal_t *	dest,
		const M_decimal_t *	dec1,
		const M_decimal_t *	dec2,
		M_decimal_round_t	round
	)

Divide the two decimals, putting the result in dest.

The destination and one of the sources may be the same. The maximum number of decimal places able to be represented will be.

Parameters

[out]	dest	New decimal with result.
[in]	dec1	First decimal (numerator).
[in]	dec2	Second decimal (denominator).
[in]	round	The result may not be able to be represented fully, select the rounding method if truncated.

Returns

One of the enum M_DECIMAL_RETVAL values.

M_decimal_subtract()

enum M_DECIMAL_RETVAL M_decimal_subtract	(	M_decimal_t *	dest,
		const M_decimal_t *	dec1,
		const M_decimal_t *	dec2
	)

Subtract two decimals, putting the result in dest.

The destination and one of the sources may be the same. The number of resulting decimal places will be the same as the largest input.

Parameters

[out]	dest	New decimal with result.
[in]	dec1	First decimal.
[in]	dec2	Second decimal.

Returns

One of the enum M_DECIMAL_RETVAL values.

M_decimal_add()

enum M_DECIMAL_RETVAL M_decimal_add	(	M_decimal_t *	dest,
		const M_decimal_t *	dec1,
		const M_decimal_t *	dec2
	)

Add two decimals, putting the result in dest.

The destination and one of the sources may be the same. The number of resulting decimal places will be the same as the largest input.

Parameters

[out]	dest	New decimal with result.
[in]	dec1	First decimal.
[in]	dec2	Second decimal.

Returns

One of the enum M_DECIMAL_RETVAL values