23. Format conversion of integer types <inttypes.h>

The header <inttypes.h> includes the header <stdint.h> and extends it with additional facilities provided by hosted implementations.

It declares functions for manipulating greatest-width integers and converting numeric character strings to greatest-width integers, and it declares the type imaxdiv_t which is a structure type that is the type of the value returned by the imaxdiv function.

For each type declared in <stdint.h>, it defines corresponding macros for conversion specifiers for use with the formatted input/output functions.

Forward references: integer types <stdint.h> (Integer types <stdint.h>), formatted input/output functions (Formatted input/output functions), formatted wide character input/output functions (Formatted wide character input/output functions).

23.1. Macros for format specifiers

Each of the following object-like macros [1] expands to a character string literal containing a conversion specifier, possibly modified by a length modifier, suitable for use within the format argument of a formatted input/output function when converting the corresponding integer type. These macro names have the general form of PRI (character string literals for the fprintf and fwprintf family) or SCN (character string literals for the fscanf and fwscanf family), [2] followed by the conversion specifier, followed by a name corresponding to a similar type name in Integer types. In these names, N represents the width of the type as described in Integer types. For example, PRIdFAST32 can be used in a format string to print the value of an integer of type int_fast32_t.

The fprintf macros for signed integers are:

`` PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR``

`` PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR``

The fprintf macros for unsigned integers are:

`` PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR``

`` PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR``

`` PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR``

`` PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR``

The fscanf macros for signed integers are:

`` SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR``

`` SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR``

The fscanf macros for unsigned integers are:

`` SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR``

`` SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR``

`` SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR``

For each type that the implementation provides in <stdint.h>, the corresponding fprintf macros shall be defined and the corresponding fscanf macros shall be defined unless the implementation does not have a suitable fscanf length modifier for the type.

EXAMPLE

#include <inttypes.h>
#include <wchar.h>

int main(void)
{
  uintmax_t i = UINTMAX_MAX; // this type always exists

  wprintf(L"The largest integer value is %020" PRIxMAX "\n", i);

  return 0;
}

[1]

C++ implementations should define these macros only when __STDC_FORMAT_MACROS is defined before <inttypes.h> is included.

[2]

Separate macros are given for use with fprintf and fscanf functions because, in the general case, different format specifiers may be required for fprintf and fscanf, even when the type is the same.

23.2. Functions for greatest-width integer types

23.2.1. The imaxabs function

Synopsis

#include <inttypes.h>
intmax_t imaxabs(intmax_t j);

Description

The imaxabs function computes the absolute value of an integer j. If the result cannot be represented, the behavior is undefined. [3]

Returns

The imaxabs function returns the absolute value.

[3]

The absolute value of the most negative number cannot be represented in two’s complement.

23.2.2. The imaxdiv function

Synopsis

#include <inttypes.h>
imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);

Description

The imaxdiv function computes numer / denom and numer % denom in a single operation.

Returns

The imaxdiv function returns a structure of type imaxdiv_t comprising both the quotient and the remainder. The structure shall contain (in either order) the members quot (the quotient) and rem (the remainder), each of which has type intmax_t. If either part of the result cannot be represented, the behavior is undefined.

23.2.3. The strtoimax and strtoumax functions

Synopsis

#include <inttypes.h>
intmax_t strtoimax(const char * restrict nptr,
char ** restrict endptr, int base);
uintmax_t strtoumax(const char * restrict nptr,
char ** restrict endptr, int base);

Description

The strtoimax and strtoumax functions are equivalent to the strtol, strtoll, strtoul and strtoull functions, except that the initial portion of the string is converted to intmax_t and uintmax_t representation, respectively.

Returns

The strtoimax and strtoumax functions return the converted value, if any. If no conversion could be performed, zero is returned. If the correct value is outside the range of representable values, INTMAX_MAX, INTMAX_MIN or UINTMAX_MAX is returned (according to the return type and sign of the value, if any), and the value of the macro ERANGE is stored in errno.

Forward references: the strtol, strtoll, strtoul and strtoull functions (The strtol, strtoll, strtoul and strtoull functions).

23.2.4. The wcstoimax and wcstoumax functions

Synopsis

#include <stddef.h> // for wchar_t
#include <inttypes.h>
intmax_t wcstoimax(const wchar_t * restrict nptr,
wchar_t ** restrict endptr, int base);
uintmax_t wcstoumax(const wchar_t * restrict nptr,
wchar_t ** restrict endptr, int base);

Description

The wcstoimax and wcstoumax functions are equivalent to the wcstol, wcstoll, wcstoul and wcstoull functions except that the initial portion of the wide string is converted to intmax_t and uintmax_t representation, respectively.

Returns

The wcstoimax function returns the converted value, if any. If no conversion could be performed, zero is returned. If the correct value is outside the range of representable values, INTMAX_MAX, INTMAX_MIN or UINTMAX_MAX is returned (according to the return type and sign of the value, if any), and the value of the macro ERANGE is stored in errno.

Forward references: the wcstol, wcstoll, wcstoul and wcstoull functions (The wcstol, wcstoll, wcstoul and wcstoull functions).