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

ID 767253
Date 3/22/2024
Public

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

Document Table of Contents

Use Intel's Numeric String Conversion Library

Intel's Numeric String Conversion Library, libistrconv, provides a collection of routines for converting between ASCII strings and C data types, which are optimized for performance. The istrconv.h header file declares prototypes for the library functions.

You can link the libistrconv library as a static or shared library on Linux* platforms.On Windows* platforms, you must link libistrconv as a static library only.

Use Intel's Numeric String Conversion Library

To use the libistrconv library, include the header file, istrconv.h, in your program.

Consider the following example conv.c file that illustrates how to use the library to convert between string and floating-point data type.

// conv.c 
#include <stdio.h> 
#include <istrconv.h> 
#define LENGTH 20 

int main() {
 const char pi[] = "3.14159265358979323";
 char s[LENGTH];
 int prec;
 float fx;
 double dx;
 printf("PI: %s\n", pi);
 printf("single-precision\n");
 fx = __IML_string_to_float(pi, NULL);
 prec = 6;
 __IML_float_to_string(s, LENGTH, prec, fx);
 printf("prec: %2d, val: %s\n", prec, s);
 printf("double-precision\n");
 dx = __IML_string_to_double(pi, NULL);
 prec = 15;
 __IML_double_to_string(s, LENGTH, prec, dx);
 printf("prec: %2d, val: %s\n", prec, s);	
 return 0; 
}

To compile the conv.c file with Intel's Numeric String Conversion Library (libistrconv) use one of the following commands. See Invoke the Compiler for information about all available compilers and drivers.

Linux

icpx conv.c –libistrconv

Windows

icx conv.c libistrconv.lib

After you compile this example and run the program, you should get the following results:

PI: 3.14159265358979323 

single-precision		
prec: 6, val: 3.14159 

double-precision		
prec: 15, val: 3.14159265358979

Integer Conversion Functions Optimized with SSE4.2 Instructions

The following integer conversion functions are optimized for better performance with SSE4.2 string processing instructions:

  • __IML_int_to_string
  • __IML_uint_to_string
  • __IML_int64_to_string
  • __IML_uint64_to_string
  • __IML_i_to_str
  • __IML_u_to_str
  • __IML_ll_to_str
  • __IML_ull_to_str
  • __IML_string_to_int
  • __IML_string_to_uint
  • __IML_string_to_int64
  • __IML_string_to_uint64
  • __IML_str_to_i
  • __IML_str_to_u
  • __IML_str_to_ll
  • __IML_str_to_ull

The SSE4.2 optimized versions of these functions can be deployed in the following situations:

  • Used automatically on post-SSE4.2 processors through Intel runtime processor dispatching
  • Called directly by defining the "__SSE4_2__" macro to the C preprocessor where <istrconv.h> is included.

The generic versions of these functions can be deployed in the following situations:

  • Used automatically on pre-SSE4.2 processors through Intel runtime processor dispatching
  • Called directly by adding _generic suffix to the function names

The SSE4.2 optimized versions of these functions moves strings from memory to XMM registers and vice versa directly to maximize performance. The functions would not overwrite the memory beyond the boundary; however, this may introduce memory access violation when the memory location immediately trailing the strings is not allocated or accessible. Users with concerns about potential memory access violation should use the generic versions instead.