# Overview: 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 on Linux* platforms, use one of the following commands:

For C++:

    icc

For DPC++:

     conv.c –libistrconv

To compile the conv.c file on macOS* platforms, use the following command:

For C++:

    icc

For DPC++:

     conv.c –libistrconv

To compile the conv.c file on Windows* platforms, use the following command:

For C++:

    icl

For DPC++:

     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