# 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* and macOS platforms.On Windows* platforms, you must link libistrconv as a static library only.

## Using 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 drivers.

Linux and macOS

    icpc conv.c –libistrconv

Windows

    icl 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 run-time 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 run-time 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.

Parent topic: Intel's Numeric String Conversion Library