Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

ID 767253
Date 9/08/2022
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Function List

Intel's Numeric String Conversion library (libistrconv) functions are listed in this topic.

Routines to Convert Floating-point Numbers to ASCII Strings

Intel's Numeric String Conversion Library supports the following functions to convert floating-point number x to string s in various formats, where l represents the length of the formatted string allowing for full conversion (not including the null terminator).

__IML_float_to_string, __IML_double_to_string

Description: These functions are similar to snprintf(s, n, "%.*g", p, x) in stdio.h, where p specifies the maximum number of significant digits in either fixed-point or exponential notation format. If n is zero, nothing is written and s may be a null pointer. Output characters beyond the (n-1)th character are discarded and a null character is appended at the end. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_float_to_string(char * s, size_t n, int p, float x);

int __IML_double_to_string(char * s, size_t n, int p, double x);

__IML_float_to_string_f, __IML_double_to_string_f

Description: These functions are similar to snprintf(s, n, "%.*f", p, x) in stdio.h, where p specifies the number of digits after the decimal point in the fixed-point notation format. If n is zero, nothing is written and s may be a null pointer. Output characters beyond the (n-1)th character are discarded and a null character is appended at the end. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_float_to_string_f(char * s, size_t n, int p, float x);

int __IML_double_to_string_f(char * s, size_t n, int p, double x);

__IML_float_to_string_e, __IML_double_to_string_e

Description: These functions are similar to snprintf(s, n, "%.*e", p, x) in stdio.h, where p specifies the number of digits after the decimal point in the exponential notation format. If n is zero, nothing is written and s may be a null pointer. Output characters beyond the (n-1)th character are discarded and a null character is appended at the end. l is returned on success; otherwise, the result is undefined.

Calling interface:

int __IML_float_to_string_e(char * s, size_t n, int p, float x);

int __IML_double_to_string_e(char * s, size_t n, int p, double x);

__IML_f_to_str, __IML_d_to_str

Description: These functions are similar to snprintf(s, n, “%.*g”, p, x) in stdio.h, where p specifies the maximum number of significant digits in either fixed-point or exponential notation format. If l < n, all output characters are stored in s with a null terminator at the end. Otherwise, output characters beyond the nth character are discarded and no null character is appended at the end. If n is zero, nothing is written and s may be a null pointer. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_f_to_str(char * s, size_t n, int p, float x);

int __IML_d_to_str(char * s, size_t n, int p, double x);

__IML_f_to_str_f, __IML_d_to_str_f

Description: These functions are similar to snprintf(s, n, “%.*f”, p, x) in stdio.h, where p specifies the number of digits after the decimal point in the fixed-point notation format. If l < n, all output characters are stored in s with a null terminator at the end. Otherwise, output characters beyond the nth character are discarded and no null character is appended at the end. If n is zero, nothing is written and s may be a null pointer. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_f_to_str_f(char * s, size_t n, int p, float x);

int __IML_d_to_str_f(char * s, size_t n, int p, double x);

__IML_f_to_str_e, __IML_d_to_str_e

Description: These functions are similar to snprintf(s, n, “%.*e”, p, x) in stdio.h, where pspecifies the number of digits after the decimal point in the exponential notation format. If l < n, all output characters are stored in s with a null terminator at the end. Otherwise, output characters beyond the nth character are discarded and no null character is appended at the end. If n is zero, nothing is written and s may be a null pointer. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_f_to_str_e(char * s, size_t n, int p, float x);

int __IML_d_to_str_e(char * s, size_t n, int p, double x);

Routines to Convert Integers to ASCII Strings

Intel's Numeric String Conversion Library supports the following functions to convert integer x to string s, where l represents the length of the formatted string allowing for full conversion (not including the null terminator).

__IML_int_to_string, __IML_uint_to_string, __IML_int64_to_string, __IML_uint64_to_string

Description: These functions are similar to snprintf(s, n, "%[d|u|lld|llu]", x) in stdio.h. If n is zero, nothing is written and s may be a null pointer. Output characters beyond the (n-1)th character are discarded and a null character is appended at the end. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_int_to_string(char * s, size_t n, int x);

int __IML_uint_to_string(char * s, size_t n, unsigned int x);

int __IML_int64_to_string(char * s, size_t n, long long x);

int __IML_uint64_to_string(char * s, size_t n, unsigned long long x);

__IML_int_to_oct_string, __IML_uint_to_oct_string, __IML_int64_to_oct_string, __IML_uint64_to_oct_string

Description: These functions are similar to snprintf(s, n, "%[o|llo]", x) in stdio.h. If n is zero, nothing is written and s may be a null pointer. Output characters beyond the (n-1)th character are discarded and a null character is appended at the end. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_int_to_oct_string(char * s, size_t n, int x);

int __IML_uint_to_oct_string(char * s, size_t n, unsigned int x);

int __IML_int64_to_oct_string(char * s, size_t n, long long x);

int __IML_uint64_to_oct_string(char * s, size_t n, unsigned long long x);

__IML_int_to_hex_string, __IML_uint_to_hex_string, __IML_int64_to_hex_string, __IML_uint64_to_hex_string

Description: These functions are similar to snprintf(s, n, "%[x|llx]", x) in stdio.h. If n is zero, nothing is written and s may be a null pointer. Output characters beyond the (n-1)th character are discarded and a null character is appended at the end. l is returned on success; otherwise the result is undefined.

Calling interface:

int __IML_int_to_hex_string(char * s, size_t n, int x);

int __IML_uint_to_hex_string(char * s, size_t n, unsigned int x);

int __IML_int64_to_hex_string(char * s, size_t n, long long x);

int __IML_uint64_to_hex_string(char * s, size_t n, unsigned long long x);

__IML_i_to_str, __IML_u_to_str, __IML_ll_to_str, __IML_ull_to_str

Description: These functions are similar to snprintf(s, n, "%[d|u|lld|llu]", x) in stdio.h. If l < n, all output characters are stored in s with a null terminator at the end. Otherwise, output characters beyond the nth character are discarded and no null character is appended at the end. If n is zero, nothing is written, and s may be a null pointer. l is returned on success, otherwise the result is undefined.

Calling interface:

int __IML_i_to_str(char * s, size_t n, int x);

int __IML_u_to_str(char * s, size_t n, unsigned int x);

int __IML_ll_to_str(char * s, size_t n, long long x);

int __IML_ull_to_str(char * s, size_t n, unsigned long long x);

__IML_i_to_oct_str, __IML_u_to_oct_str, __IML_ll_to_oct_str, __IML_ull_to_oct_str

Description: These functions are similar to snprintf(s, n, "%[o|llo]", x) in stdio.h. If l < n, all output characters are stored in s with a null terminator at the end. Otherwise, output characters beyond the nth character are discarded and no null character is appended at the end. If n is zero, nothing is written, and s may be a null pointer. l is returned on success, otherwise the result is undefined.

Calling interface:

int __IML_i_to_oct_str(char * s, size_t n, int x);

int __IML_u_to_oct_str(char * s, size_t n, unsigned int x);

int __IML_ll_to_oct_str(char * s, size_t n, long long x);

int __IML_ull_to_oct_str(char * s, size_t n, unsigned long long x);

__IML_i_to_hex_str, __IML_u_to_hex_str, __IML_ll_to_hex_str, __IML_ull_to_hex_str

Description: These functions are similar to snprintf(s, n, "%[x|llx]", x) in stdio.h. If l < n, all output characters are stored in s with a null terminator at the end. Otherwise, output characters beyond the nth character are discarded and no null character is appended at the end. If n is zero, nothing is written, and s may be a null pointer. l is returned on success, otherwise the result is undefined.

Calling interface:

int __IML_i_to_hex_str(char * s, size_t n, int x);

int __IML_u_to_hex_str(char * s, size_t n, unsigned int x);

int __IML_ll_to_hex_str(char * s, size_t n, long long x);

int __IML_ull_to_hex_str(char * s, size_t n, unsigned long long x);

Routines to Convert ASCII Strings to Floating-point Numbers

Intel's Numeric String Conversion Library supports the following functions to convert the initial portion of decimal string s to floating-point number x. If no conversion could be performed, zero is returned. If the correct value is outside the range of the return type, plus (+) or minus (-) HUGE_VALF, HUGE_VAL, or HUGE_VALL is returned, and the value of macro ERANGE is stored in errno.

__IML_string_to_float, __IML_string_to_double, __IML_string_to_long_double

Description: These functions are similar to strtof(nptr, endptr), strtod(nptr, endptr), and strtold(nptr, endptr) in stdlib.h, where endptr points to the object that stores the final part of nptr when endptr is not a null pointer.

Calling interface:

float __IML_string_to_float(const char * nptr, char ** endptr);

double __IML_string_to_double(const char * nptr, char ** endptr);

long double __IML_string_to_long_double(const char * nptr, char ** endptr);

__IML_str_to_f, __IML_str_to_d, __IML_str_to_ld

Description: These functions convert the initial n decimal digits of the significand string multiplied by 10 raised to power of exponent to floating-point number as return. endptr points to the object that stores the final part of significand, provided that endptr is not a null pointer.

Calling interface:

float __IML_str_to_f(const char * significand, size_t n, int exponent, char ** endptr);

double __IML_str_to_d(const char * significand, size_t n, int exponent, char ** endptr);

long double __IML_str_to_ld(const char * significand, size_t n, int exponent, char ** endptr);

Routines to Convert ASCII Strings to Integers

Intel's Numeric String Conversion Library supports the following functions to convert the initial portion of string s to integer x. If no conversion could be performed, zero is returned. If the correct value is outside the range of the return type, INT_MIN, INT_MAX, UINT_MAX, LLONG_MIN, LLONG_MAX, ULLONG_MAX is returned, and the value of macro ERANGE is stored in errno.

__IML_string_to_int, __IML_string_to_uint, __IML_string_to_int64, __IML_string_to_uint64

Description: These functions are similar to ([unsigned] int)strto[u]l(nptr, endptr, 10) and strto[u]ll(nptr, endptr, 10) functions in stdlib.h, where endptr points to the object that stores the final part of nptr when endptr is not a null pointer.

Calling interface:

int __IML_string_to_int(const char * nptr, char ** endptr);

unsigned int __IML_string_to_uint(const char * nptr, char ** endptr);

long long __IML_string_to_int64(const char * nptr, char ** endptr);

unsigned long long __IML_string_to_uint64(const char * nptr, char ** endptr);

__IML_oct_string_to_int, __IML_oct_string_to_uint, __IML_oct_string_to_int64, __IML_oct_string_to_uint64

Description: These functions are similar to ([unsigned] int)strto[u]l(nptr, endptr, 8) and strto[u]ll(nptr, endptr, 8) functions in stdlib.h, where endptr points to the object that stores the final part of nptr when endptr is not a null pointer.

Calling interface:

int __IML_oct_string_to_int(const char * nptr,char ** endptr);

unsigned int __IML_oct_string_to_uint(const char * nptr,char ** endptr);

long long __IML_oct_string_to_int64(const char * nptr,char ** endptr);

unsigned long long __IML_oct_string_to_uint64(const char * nptr,char ** endptr);

__IML_hex_string_to_int, __IML_hex_string_to_uint, __IML_hex_string_to_int64, __IML_hex_string_to_uint64

Description: These functions are similar to ([unsigned] int)strto[u]l(nptr, endptr, 16) and strto[u]ll(nptr, endptr, 16) functions in stdlib.h, where endptr points to the object that stores the final part of nptr when endptr is not a null pointer.

Calling interface:

int __IML_hex_string_to_int(const char * nptr,char ** endptr);

unsigned int __IML_hex_string_to_uint(const char * nptr,char ** endptr);

long long __IML_hex_string_to_int64(const char * nptr,char ** endptr);

unsigned long long __IML_hex_string_to_uint64(const char * nptr,char ** endptr);

__IML_str_to_i, __IML_str_to_u, __IML_str_to_ll, __IML_str_to_ull

Description: These functions convert the initial n decimal digits (including an optional + or - sign) pointed to by nptr to integral values. When endptr is not a null pointer it points to the object that stores the final part of nptr. These functions treat any leading whitespace as invalid.

Calling interface:

int __IML_str_to_i(const char * nptr, size_t n, char ** endptr);

unsigned int __IML_str_to_u(const char * nptr, size_t n, char ** endptr);

long long __IML_str_to_ll(const char * nptr, size_t n, char ** endptr);

unsigned long long __IML_str_to_ull(const char * nptr, size_t n, char ** endptr);

__IML_oct_str_to_i, __IML_oct_str_to_u, __IML_oct_str_to_ll, __IML_oct_str_to_ull

Description: These functions convert the initial n octal digits (including an optional + or - sign) pointed to by nptr to integral values. When endptr is not a null pointer it points to the object that stores the final part of nptr. These functions treat any leading whitespace as invalid.

Calling interface:

int __IML_oct_str_to_i(const char * nptr,size_t n,char ** endptr);

unsigned int __IML_oct_str_to_u(const char * nptr,size_t n,char ** endptr);

long long __IML_oct_str_to_ll(const char * nptr,size_t n,char ** endptr);

unsigned long long __IML_oct_str_to_ull(const char * nptr,size_t n,char ** endptr);

__IML_hex_str_to_i, __IML_hex_str_to_u, __IML_hex_str_to_ll, __IML_hex_str_to_ull

Description: These functions convert the initial n hexadecimal digits (including an optional + or - sign) pointed to by nptr to integral values. When endptr is not a null pointer it points to the object that stores the final part of nptr. These functions treat any leading whitespace as invalid.

Calling interface:

int __IML_hex_str_to_i(const char * nptr,size_t n,char ** endptr);

unsigned int __IML_hex_str_to_u(const char * nptr,size_t n,char ** endptr);

long long __IML_hex_str_to_ll(const char * nptr,size_t n,char ** endptr);

unsigned long long __IML_hex_str_to_ull(const char * nptr,size_t n,char ** endptr);