CSD Conversion Functions

Functions for converting between decimal and CSD representations. More...

Classes
class	csd::invalid_csd_format
	Exception thrown when invalid CSD characters are encountered. More...

Functions
auto	csd::to_csd (double decimal_value, int places) -> std::string
auto	csd::to_csd_i (int decimal_value) -> std::string
auto	csd::to_csdnnz (double decimal_value, unsigned int nnz) -> std::string
	Convert a floating-point number to CSD with limited non-zero digits.
auto	csd::to_csdnnz_i (int decimal_value, unsigned int nnz) -> std::string
	Convert an integer to CSD with limited non-zero digits.
CONSTEXPR14 auto	csd::to_decimal_using_switch (const char *csd) -> double
CONSTEXPR14 auto	csd::to_decimal_integral (const char *&csd) -> int
	Convert the integral part of a CSD string to a decimal.
CONSTEXPR14 auto	csd::to_decimal_fractional (const char *csd) -> double
	Convert the fractional part of a CSD string to a decimal.
CONSTEXPR14 auto	csd::to_decimal (const char *csd) -> double
	Convert the CSD string to a decimal.
CONSTEXPR14 auto	csd::to_decimal_i (const char *csd) -> int
	Convert CSD string to integer.

Variables
constexpr int	csd::MAX_DECIMAL_PLACES = 20
	Maximum number of decimal places supported by CSD conversion.
constexpr unsigned int	csd::MIN_NONZERO_DIGITS = 1
	Minimum value for non-zero digit count in CSDNNZ functions.

Detailed Description

Functions for converting between decimal and CSD representations.

Function Documentation

to_csd()

auto csd::to_csd ( double  decimal_value, int  places  ) -> std::string

extern

@brief Convert a floating-point number to CSD representation
@ingroup csd_functions

Converts a double precision floating point number to a string
representation in Canonical Signed Digit (CSD) format with a
specified number of decimal places.

The CSD format ensures that:
- Each digit is either '0', '+', or '-'
- No two consecutive digits are non-zero
- The representation has the minimal number of non-zero digits

Example:
@code
to_csd(28.5, 2) returns "+00-00.+"
// Calculation: 2^5 - 2^2 + 2^0 + 2^(-1) = 32 - 4 + 1 + 0.5 = 28.5
@endcode

\[ x = \sum_{i} s_i 2^i, \quad s_i \in \{-1, 0, 1\} \]

@param[in] decimal_value The number to convert to CSD format. Can be positive,
                        negative, or zero.
@param[in] places The number of decimal places to include in the CSD representation.
                 Must be non-negative. Use 0 for integer values.

@return String representation of the input number in CSD format.
        The string contains only '0', '+', '-', and '.' characters.

@throws std::invalid_argument If places is negative or if the conversion
                              fails due to numerical limitations.

@see to_csd_i() for integer-only conversion
@see to_decimal() for reverse conversion

to_csd_i()

auto csd::to_csd_i ( int  decimal_value ) -> std::string

extern

@brief Convert an integer to CSD representation
@ingroup csd_functions

Converts an integer to a string representation in Canonical Signed Digit (CSD) format.
This function is optimized for integer values and produces a CSD string without
a decimal point.

Example:
@code
to_csd_i(28) returns "+00-00"
// Calculation: 2^5 - 2^2 = 32 - 4 = 28

to_csd_i(0) returns "0"
@endcode

\[ n = \sum_{i} s_i 2^i, \quad s_i \in \{-1, 0, 1\} \]

@param[in] decimal_value The integer to convert to CSD format. Can be positive,
                        negative, or zero.

@return String representation of the input integer in CSD format.
        The string contains only '0', '+', and '-' characters.

@throws std::invalid_argument If the conversion fails due to numerical limitations.

@see to_csd() for floating-point conversion
@see to_decimal_i() for reverse conversion

to_csdnnz()

auto csd::to_csdnnz ( double  decimal_value, unsigned int  nnz  ) -> std::string

extern

Convert a floating-point number to CSD with limited non-zero digits.

Converts a double precision floating point number to a CSD (Canonical Signed Digit) string representation with a fixed number of non-zero digits. This is useful for applications where hardware resources are limited and you want to control the complexity of the resulting representation.

The function will stop adding non-zero digits once the specified limit is reached, potentially resulting in an approximation of the original value.

Example:

to_csdnnz(28.5, 3) returns "+00-00.+"
// Uses only 3 non-zero digits: + at position 5, - at position 2, + at position 0

\[ x \approx \sum_{i} s_i 2^i, \quad |\{i : s_i \ne 0\}| \le \mathrm{nnz} \]

Parameters

[in]	decimal_value	The number to convert to CSD format. Can be positive, negative, or zero.
[in]	nnz	The maximum number of non-zero digits allowed in the CSD representation. Must be at least 1. Larger values produce more accurate representations.

Returns

String representation of the input number in CSD format with at most nnz non-zero digits.

Exceptions

std::invalid_argument

If nnz is 0 or if the conversion fails.

See also

to_csdnnz_i() for integer version

to_csd() for unlimited non-zero digits

to_csdnnz_i()

auto csd::to_csdnnz_i ( int  decimal_value, unsigned int  nnz  ) -> std::string

extern

Convert an integer to CSD with limited non-zero digits.

Converts an integer to a CSD (Canonical Signed Digit) string representation with a fixed number of non-zero digits. This is particularly useful for hardware design where you want to limit the number of adders/subtracters required.

The function will stop adding non-zero digits once the specified limit is reached, potentially resulting in an approximation of the original value.

Example:

to_csdnnz_i(28, 2) returns "+00-00"
// Uses only 2 non-zero digits: + at position 5, - at position 2

\[ n \approx \sum_{i} s_i 2^i, \quad |\{i : s_i \ne 0\}| \le \mathrm{nnz} \]

Parameters

[in]	decimal_value	The integer to convert to CSD format. Can be positive, negative, or zero.
[in]	nnz	The maximum number of non-zero digits allowed in the CSD representation. Must be at least 1.

Returns

String representation of the input number in CSD format with at most nnz non-zero digits.

Exceptions

std::invalid_argument

If nnz is 0 or if the conversion fails.

See also

to_csdnnz() for floating-point version

to_csd_i() for unlimited non-zero digits

to_decimal()

CONSTEXPR14 auto csd::to_decimal

(

const char *

csd

)

-> double

Convert the CSD string to a decimal.

This function takes a CSD (Canonical Signed Digit) string as input and converts it to a decimal number. It iterates through the characters of the string and performs operations based on each character to build up the decimal value.

The integral part is processed first, multiplying the value by 2 for each '0' and adding/subtracting 1 for '+'/'-'.

Then the fractional part is processed, starting with a scale of 0.5 and adding/ subtracting fractions of that scale based on the '+/-' digits.

The function throws an exception if any invalid characters are encountered.

\[ v = \sum_{i} s_i 2^i + \sum_{j} s_j 2^{-(j+1)}, \quad s_i, s_j \in \{-1, 0, 1\} \]

Parameters

[in]

csd

- Pointer to the null-terminated CSD string to convert

Returns

The decimal value of the CSD string

to_decimal_fractional()

CONSTEXPR14 auto csd::to_decimal_fractional

(

const char *

csd

)

-> double

Convert the fractional part of a CSD string to a decimal.

This function takes a pointer to a CSD string that contains a fractional part, starting after the '.' character. It iterates through the fractional digits, keeping track of a scaling factor. For each '+' it adds, and for each '-' it subtracts, a fraction of the current scale. This builds up the fractional part of the final decimal number.

\[ v = \sum_{i} s_i 2^{-(i+1)}, \quad s_i \in \{-1, 0, 1\} \]

to_decimal_i()

CONSTEXPR14 auto csd::to_decimal_i

(

const char *

csd

)

-> int

Convert CSD string to integer.

The function to_decimal_i takes a CSD (Canonical Signed Digit) string as input and converts it to an integer. This function only processes the integral part of the CSD string and ignores any fractional part.

This is essentially a wrapper around to_decimal_integral() for convenience and API consistency.

Example:

to_decimal_i("+00-00") returns 28
to_decimal_i("+00-00.+") returns 28  // Fractional part ignored
to_decimal_i("0") returns 0

\[ n = \sum_{i} s_i 2^i, \quad s_i \in \{-1, 0, 1\} \]

Parameters

[in]

csd

Pointer to null-terminated CSD string containing only '0', '+', '-', and optional '.' characters.

Returns

Integer value of the CSD string (fractional part ignored).

Exceptions

invalid_csd_format

If the string contains invalid characters.

See also

to_csd_i() for reverse conversion

to_decimal() for floating-point conversion

to_decimal_integral()

CONSTEXPR14 auto csd::to_decimal_integral

(

const char *&

csd

)

-> int

Convert the integral part of a CSD string to a decimal.

This function takes a pointer to a null-terminated CSD string, which represents a number in canonical signed digit format. It iterates through the string, processing each character and accumulating a decimal value for just the integral part of the number.

For each '0' digit, it multiplies the current value by 2. For each '+' digit, it multiplies the current value by 2 and adds 1. For each '-' digit, it multiplies the current value by 2 and subtracts 1.

It stops when it reaches either a '.' or '\0' character, as those mark the end of the integral part.

It throws an exception if any invalid character is encountered.

\[ v = \sum_{i} s_i 2^i, \quad s_i \in \{-1, 0, 1\} \]

Parameters

[in]

csd

- Pointer to the null-terminated CSD string

Returns

The decimal value of the integral part

to_decimal_using_switch()

CONSTEXPR14 auto csd::to_decimal_using_switch

(

const char *

csd

)

-> double

Converts a CSD string to a double precision decimal number using a switch statement.

This is an internal implementation detail, not part of the public API.

\[ v = \sum_{i} s_i 2^i, \quad s_i \in \{-1, 0, 1\} \]

Parameters

[in]

csd

The parameter csd is a pointer to a character array, which represents the input string. It is assumed that the string is null-terminated.

Returns

double decimal value of the CSD format

Variable Documentation

MAX_DECIMAL_PLACES

constexpr int csd::MAX_DECIMAL_PLACES = 20

constexpr

Maximum number of decimal places supported by CSD conversion.

MIN_NONZERO_DIGITS

constexpr unsigned int csd::MIN_NONZERO_DIGITS = 1

constexpr

Minimum value for non-zero digit count in CSDNNZ functions.