std::midpoint(3)

NAME
std::midpoint - std::midpoint

Synopsis
   Defined in header <numeric>
   template< class T > (1) (since C++20)
   constexpr T midpoint( T a, T b ) noexcept;
   template< class T > (2) (since C++20)
   constexpr T* midpoint( T* a, T* b );
   Computes the midpoint of the integers, floating-points, or pointers a and b.
   1) This overload participates in overload resolution only if T is an arithmetic type
   other than bool.
   2) This overload participates in overload resolution only if T is an object type.
   Use of this overload is ill-formed if T is an incomplete type.

Parameters
   a, b - integers, floating-points, or pointer values

Return value
   1) Half the sum of a and b. No overflow occurs. If a and b have integer type and the
   sum is odd, the result is rounded towards a. If a and b have floating-point type, at
   most one inexact operation occurs.
   2) If a and b point to, respectively, x[i] and x[j] of the same array object x (for
   the purpose of pointer arithmetic), returns a pointer to x[i+(j-i)/2] (or,
   equivalently x[std::midpoint(i, j)]) where the division rounds towards zero. If a
   and b do not point to elements of the same array object, the behavior is undefined.

Exceptions
   Throws no exceptions.

Notes
   Overload (2) can be simply implemented as return a + (b - a) / 2; on common
   platforms. However, such implementation is not guaranteed to be portable, because
   there may be some platforms where creating an array with number of elements greater
   than PTRDIFF_MAX is possible, and b - a may result in undefined behavior even if
   both b and a point to elements in the same array.
   Feature-test macro: __cpp_lib_interpolate

Example
// Run this code
 #include <cstdint>
 #include <limits>
 #include <numeric>
 #include <iostream>
 int main()
 {
     std::uint32_t a = std::numeric_limits<std::uint32_t>::max();
     std::uint32_t b = std::numeric_limits<std::uint32_t>::max() - 2;
     std::cout << "a: " << a << '\n'
               << "b: " << b << '\n'
               << "Incorrect (overflow and wrapping): " << (a + b) / 2 << '\n'
               << "Correct: " << std::midpoint(a, b) << "\n\n";
     auto on_pointers = [](int i, int j) {
         char const* text = "0123456789";
         char const* p = text + i;
         char const* q = text + j;
         std::cout << "std::midpoint('" << *p << "', '" << *q << "'): '"
                   << *std::midpoint(p, q) << "'\n";
     };
     on_pointers(2, 4);
     on_pointers(2, 5);
     on_pointers(5, 2);
     on_pointers(2, 6);
 }

Output:
 a: 4294967295
 b: 4294967293
 Incorrect (overflow and wrapping): 2147483646
 Correct: 4294967294
 std::midpoint('2', '4'): '3'
 std::midpoint('2', '5'): '3'
 std::midpoint('5', '2'): '4'
 std::midpoint('2', '6'): '4'

References
     * C++20 standard (ISO/IEC 14882:2020):
              * 25.10.15 Midpoint [numeric.ops.midpoint]

See also
   lerp linear interpolation function
   (C++20) (function)