Namespaces
Variants
Views
Actions

std::modf, std::modff, std::modfl

From cppreference.com
< cpp‎ | numeric‎ | math
 
C++
 
Numerics library
Common mathematical functions
Mathematical special functions (C++17)
Mathematical constants (C++20)
Basic linear algebra algorithms (C++26)
Floating-point environment (C++11)
Complex numbers
Numeric array (valarray)
Pseudo-random number generation
Factor operations
(C++17)
(C++17)
Interpolations
(C++20)
(C++20)
Saturation arithmetic
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)

Generic numeric operations
Bit operations
(C++20)    
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++23)
(C++20)
 
Common mathematical functions
Functions
Basic operations
(C++11)  
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
Exponential functions
(C++11)
(C++11)

(C++11)
(C++11)
Power functions
(C++11)
(C++11)
Trigonometric and
hyperbolic functions
(C++11)
(C++11)
(C++11)

Error and gamma functions
(C++11)
(C++11)
(C++11)
(C++11)
Nearest integer floating point operations
(C++11)(C++11)(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
Floating point manipulation functions
(C++11)(C++11)
(C++11)
(C++11)
modf
(C++11)(C++11)
(C++11)
Classification and comparison
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Types
(C++11)
(C++11)
(C++11)
Macro constants
 
Defined in header <cmath>
(1)
float       modf ( float num, float* iptr );

double      modf ( double num, double* iptr );

long double modf ( long double num, long double* iptr );
 (until C++23)
constexpr /* floating-point-type */

            modf ( /* floating-point-type */ num,

                   /* floating-point-type */* iptr );
 (since C++23)
float       modff( float num, float* iptr );
 (2) (since C++11)
(constexpr since C++23)
long double modfl( long double num, long double* iptr );
 (3) (since C++11)
(constexpr since C++23)
Additional overloads (since C++11)
Defined in header <cmath>
template< class Integer >
double      modf ( Integer num, double* iptr );
 (A) (constexpr since C++23)
1-3) Decomposes given floating point value num into integral and fractional parts, each having the same type and sign as num. The integral part (in floating-point format) is stored in the object pointed to by iptr. The library provides overloads of std::modf for all cv-unqualified floating-point types as the type of the parameter num and the pointed-to type of iptr.(since C++23)
A) Additional overloads are provided for all integer types, which are treated as double.
 (since C++11)

Contents

Parameters

num - floating-point or integer value
iptr - pointer to floating-point value to store the integral part to

Return value

If no errors occur, returns the fractional part of num with the same sign as num. The integral part is put into the value pointed to by iptr.

The sum of the returned value and the value stored in *iptr gives num (allowing for rounding).

Error handling

This function is not subject to any errors specified in math_errhandling.

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

  • If num is ±0, ±0 is returned, and ±0 is stored in *iptr.
  • If num is ±∞, ±0 is returned, and ±∞ is stored in *iptr.
  • If num is NaN, NaN is returned, and NaN is stored in *iptr.
  • The returned value is exact, the current rounding mode is ignored.

Notes

This function behaves as if implemented as follows: 

double modf(double num, double* iptr)
{
#pragma STDC FENV_ACCESS ON
    int save_round = std::fegetround();
    std::fesetround(FE_TOWARDZERO);
    *iptr = std::nearbyint(num);
    std::fesetround(save_round);
    return std::copysign(std::isinf(num) ? 0.0 : num - (*iptr), num);
}

The additional overloads are not required to be provided exactly as (A). They only need to be sufficient to ensure that for their argument num of integer type, std::modf(num, iptr) has the same effect as std::modf(static_cast<double>(num), iptr).

Example

Compares different floating-point decomposition functions:

Run this code
#include <cmath>
#include <iostream>
#include <limits>
 
int main()
{
    double f = 123.45;
    std::cout << "Given the number " << f << " or " << std::hexfloat
              << f << std::defaultfloat << " in hex,\n";
 
    double f3;
    double f2 = std::modf(f, &f3);
    std::cout << "modf() makes " << f3 << " + " << f2 << '\n';
 
    int i;
    f2 = std::frexp(f, &i);
    std::cout << "frexp() makes " << f2 << " * 2^" << i << '\n';
 
    i = std::ilogb(f);
    std::cout << "logb()/ilogb() make " << f / std::scalbn(1.0, i) << " * "
              << std::numeric_limits<double>::radix
              << "^" << std::ilogb(f) << '\n';
 
    // special values
    f2 = std::modf(-0.0, &f3);
    std::cout << "modf(-0) makes " << f3 << " + " << f2 << '\n';
    f2 = std::modf(-INFINITY, &f3);
    std::cout << "modf(-Inf) makes " << f3 << " + " << f2 << '\n';
}

Possible output: 

Given the number 123.45 or 0x1.edccccccccccdp+6 in hex,
modf() makes 123 + 0.45
frexp() makes 0.964453 * 2^7
logb()/ilogb() make 1.92891 * 2^6
modf(-0) makes -0 + -0
modf(-Inf) makes -INF + -0

See also

(C++11)(C++11)(C++11)
 nearest integer not greater in magnitude than the given value
(function) [edit]
C documentation for modf
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/math/modf&oldid=149276"