Various Functions — mpdecimal 2.5.1 documentation
Description: libmpdec documentation

# Various Functions

## Applying the Context

### finalize

    void mpd_qfinalize(mpd_t *result, const mpd_context_t *ctx,
                       uint32_t *status);
    void mpd_finalize(mpd_t *result, mpd_context_t *ctx);

Apply ctx to result. This function performs checks the exponent limits and performs rounding. The following conditions can occur:

`MPD_Clamped`, `MPD_Inexact`, `MPD_Overflow`, `MPD_Rounded`, `MPD_Subnormal`, `MPD_Underflow`

## NaN Handling

These functions are convenience functions that take care of the elaborate NaN handling rules. They are meant to be used at the beginning of composite functions.

### check-nan

    int mpd_qcheck_nan(mpd_t *result, const mpd_t *a, const mpd_context_t *ctx,
                       uint32_t *status);
    int mpd_check_nan(mpd_t *result, const mpd_t *a, mpd_context_t *ctx);

If a is NaN or sNaN, set result to qNaN, copy any payload, apply ctx to the payload and return 1. If a is sNaN, additionally set `MPD_Invalid_operation`.

Otherwise, result is undefined and the return value is 0.

### check-nans

    int mpd_qcheck_nans(mpd_t *result, const mpd_t *a, const mpd_t *b,
                        const mpd_context_t *ctx, uint32_t *status);
    int mpd_check_nans(mpd_t *result, const mpd_t *a, const mpd_t *b,
                       mpd_context_t *ctx);

If either operand is NaN or sNaN, apply the precedence rules, set result to qNaN, copy any payload, apply ctx to the payload and return 1. If one of the operands is sNaN, additionally set `MPD_Invalid_operation`.

Otherwise, result is undefined and the return value is 0.

## Shifting and Rotating

### shift

    void mpd_qshift(mpd_t *result, const mpd_t *a, const mpd_t *b,
                    const mpd_context_t *ctx, uint32_t *status);
    void mpd_shift(mpd_t *result, const mpd_t *a, const mpd_t *b,
                   mpd_context_t *ctx);

Set result to a shifted by b places. b must be in the range [-prec, prec]. A negative b indicates a right shift, a positive b a left shift. Digits that do not fit are discarded.

### shiftn

    void mpd_qshiftn(mpd_t *result, const mpd_t *a, mpd_ssize_t n,
                     const mpd_context_t *ctx, uint32_t *status);
    void mpd_shiftn(mpd_t *result, const mpd_t *a, mpd_ssize_t n,
                    mpd_context_t *ctx);

Like `mpd_qshift`, only that the number of places is specified by a C integer type rather than a decimal. This function is not part of the specification.

### shiftl

    int mpd_qshiftl(mpd_t *result, const mpd_t *a, mpd_ssize_t n,
                    uint32_t *status);
    void mpd_shiftl(mpd_t *result, const mpd_t *a, mpd_ssize_t n,
                    mpd_context_t *ctx);

Set result to a, shifted by n places to the left. a must not be a special number. Digits are never discarded, so the coefficient of result might exceed prec. Return 1 on success. On failure, return 0 and add `MPD_Malloc_error` to status.

This function is not part of the specification.

### shiftr

    mpd_uint_t mpd_qshiftr(mpd_t *result, const mpd_t *a, mpd_ssize_t n,
                           uint32_t *status);
    mpd_uint_t mpd_shiftr(mpd_t *result, const mpd_t *a, mpd_ssize_t n,
                          mpd_context_t *ctx);

Set result to a, shifted by n places to the right. a must not be a special number. On success, return the digit relevant for rounding. On failure, return `MPD_UINT_MAX` and add `MPD_Malloc_error` to status.

This function is not part of the specification.

### shiftr-inplace

    mpd_uint_t mpd_qshiftr_inplace(mpd_t *result, mpd_ssize_t n)

Like `mpd_qshiftr`, but shifts result in place. result must not be a special number. This function cannot fail.

### rotate

    void mpd_qrotate(mpd_t *result, const mpd_t *a, const mpd_t *b,
                     const mpd_context_t *ctx, uint32_t *status);
    void mpd_rotate(mpd_t *result, const mpd_t *a, const mpd_t *b,
                    mpd_context_t *ctx);

Set result to a rotated by b places. b must be in the range [-prec, prec]. A negative b indicates a right rotation, a positive b a left rotation.

## Logical Operations

Logical operands are finite numbers with a sign of 0, an exponent of 0 and a coefficient consisting only of ones and zeros.

### and

    void mpd_qand(mpd_t *result, const mpd_t *a, const mpd_t *b,
                  const mpd_context_t *ctx, uint32_t *status);
    void mpd_and(mpd_t *result, const mpd_t *a, const mpd_t *b,
                 mpd_context_t *ctx);

Set result to the digit-wise logical and of a and b.

### or

    void mpd_qor(mpd_t *result, const mpd_t *a, const mpd_t *b,
                 const mpd_context_t *ctx, uint32_t *status);
    void mpd_or(mpd_t *result, const mpd_t *a, const mpd_t *b,
                mpd_context_t *ctx);

Set result to the digit-wise logical or of a and b.

### xor

    void mpd_qxor(mpd_t *result, const mpd_t *a, const mpd_t *b,
                  const mpd_context_t *ctx, uint32_t *status);
    void mpd_xor(mpd_t *result, const mpd_t *a, const mpd_t *b,
                 mpd_context_t *ctx);

Set result to the digit-wise logical xor of a and b.

### invert

    void mpd_qinvert(mpd_t *result, const mpd_t *a, const mpd_context_t *ctx,
                     uint32_t *status);
    void mpd_invert(mpd_t *result, const mpd_t *a, mpd_context_t *ctx);

Set result to the digit-wise logical inversion of a.

## Base Conversions

Functions for converting decimals to multi-precision integers and vice versa. Decimals that are exported must be integers.

### Importing

    void mpd_qimport_u16(mpd_t *result, const uint16_t *srcdata,
                         size_t srclen, uint8_t srcsign, uint32_t srcbase,
                         const mpd_context_t *ctx, uint32_t *status);
    void mpd_import_u16(mpd_t *result, const uint16_t *srcdata,
                        size_t srclen, uint8_t srcsign, uint32_t srcbase,
                        mpd_context_t *ctx);

Convert a multi-precision integer at srcdata with base srcbase to a decimal. The least significant word is srcdata[0].

srcsign is `MPD_POS` for positive and `MPD_NEG` for negative, srclen the length of srcdata.

Valid bases are in the range 2 <= srcbase <= `UINT16_MAX` + 1.

    void mpd_qimport_u32(mpd_t *result, const uint32_t *srcdata,
                         size_t srclen, uint8_t srcsign, uint32_t srcbase,
                         const mpd_context_t *ctx, uint32_t *status);
    void mpd_import_u32(mpd_t *result, const uint32_t *srcdata,
                        size_t srclen, uint8_t srcsign, uint32_t base,
                        mpd_context_t *ctx);

Convert a multi-precision integer at srcdata with base srcbase to a decimal. The least significant word is srcdata[0].

srcsign is `MPD_POS` for positive and `MPD_NEG` for negative, srclen the length of srcdata.

Valid bases are in the range 2 <= srcbase <= `UINT32_MAX`.

### Exporting

    mpd_sizeinbase(const mpd_t *a, uint32_t base);

Return the number of words needed to represent a decimal when converted to base. The decimal must be an integer, results are undefined for non-integers.

    size_t mpd_qexport_u16(uint16_t **rdata, size_t rlen, uint32_t rbase,
                           const mpd_t *src, uint32_t *status);
    size_t mpd_export_u16(uint16_t **rdata, size_t rlen, uint32_t rbase,
                          const mpd_t *src, mpd_context_t *ctx);

Set *rdata to src, converted to a representation in base rbase. The least significant word of the result is rdata[0]. src must be an integer.

If rdata is NULL, space is allocated by the function and rlen is irrelevant. In case of an error the allocated storage is freed and rdata is set back to NULL.

If rdata is non-NULL, it MUST be allocated by one of libmpdec’s allocation functions and rlen MUST be correct. If necessary, the function will resize rdata. Resizing is slow and should not occur if rlen has been obtained by a call to `mpd_sizeinbase`. In case of an error the caller must free rdata.

Return value: In case of success, the length of the multi-precision integer in the new base, `SIZE_MAX` otherwise.

Valid bases are in the range 2 <= rbase <= `UINT16_MAX` + 1.

Changed in version 2.4.0: rdata is now resized if necessary.

    size_t mpd_qexport_u32(uint32_t *rdata, size_t rlen, uint32_t rbase,
                           const mpd_t *src, uint32_t *status);
    size_t mpd_export_u32(uint32_t *rdata, size_t rlen, uint32_t rbase,
                          const mpd_t *src, mpd_context_t *ctx);

Set *rdata to src, converted to a representation in base rbase. The least significant word of the result is rdata[0]. src must be an integer.

If rdata is NULL, space is allocated by the function and rlen is irrelevant. In case of an error the allocated storage is freed and rdata is set back to NULL.

If rdata is non-NULL, it MUST be allocated by one of libmpdec’s allocation functions and rlen MUST be correct. If necessary, the function will resize rdata. Resizing is slow and should not occur if rlen has been obtained by a call to `mpd_sizeinbase`. In case of an error the caller must free rdata.

Return value: In case of success, the length of the multi-precision integer in the new base, `SIZE_MAX` otherwise.

Valid bases are in the range 2 <= rbase <= `UINT32_MAX`.

Changed in version 2.4.0: rdata is now resized if necessary.

## Required Functions

The functions in this section are not needed for this implementation. They are provided for full compliance with the specification.

    void mpd_canonical(mpd_t *result, const mpd_t *a, mpd_context_t *ctx);

Same as `mpd_copy`.

    int mpd_iscanonical(const mpd_t *dec);

Return 1, for compatibility with the standard.

    long mpd_radix(void);

Return 10.

## Library version

    /* Macros defining the components of the version as integers. */
    MPD_MAJOR_VERSION
    MPD_MINOR_VERSION
    MPD_MICRO_VERSION

    /* Macro defining the complete version as a string. */
    MPD_VERSION

    const char *mpd_version(void);

Library version information. `mpd_version` returns the MPD_VERSION macro from the header that the library was compiled with.

New in version 2.4.0.