C strtold() Function – stdlib.h

strtold() Function

The strtold() function is declared in the header file <stdlib.h>.

The strtold() function converts a string representing a floating-point number into a long double value. It parses the input string according to the current locale settings and returns the numerical value. Additionally, if provided, it can update a pointer to indicate where the numerical conversion stopped.

---

Syntax of strtold()

long double strtold(const char *str, char **endptr);

Parameters

Parameter	Description
str	C string beginning with the representation of a floating-point number.
endptr	A pointer to an object of type char* which is set to point to the character after the numerical value. It can be NULL if not needed.

Note that strtold() operates similarly to strtod() but returns a value of type long double. In cases where no valid conversion is performed, it returns 0.0L. Furthermore, if the converted value is out of range or causes underflow, the function returns HUGE_VALL (or its negative) and sets errno to ERANGE.

---

Return Value

On success, the function returns the converted floating point number as a value of type long double. If no valid conversion can be performed, it returns 0.0L. In the event of overflow, it returns a positive or negative HUGE_VALL and sets errno to ERANGE; in the case of underflow, it returns a value whose magnitude is no greater than the smallest normalized positive number (and may also set errno to ERANGE).

---

Examples for strtold()

Example 1: Basic Conversion of a Floating-Point String

This example demonstrates the conversion of a valid floating-point string to a long double value.

Program

#include <stdio.h>
#include <stdlib.h>

int main() {
    const char *str = "12345.6789";
    char *endptr;
    long double num;

    num = strtold(str, &endptr);
    printf("Converted number: %Lf\n", num);
    return 0;
}

Explanation:

1. The string "12345.6789" is parsed by strtold() to obtain its floating-point value.
2. The pointer endptr is updated to point to the character immediately after the number.
3. The converted value is printed using printf() with the format specifier %Lf.

Program Output:

Converted number: 12345.678900

Example 2: Demonstrating Endptr Functionality

This example shows how the endptr parameter can be used to determine where the numerical conversion stops.

Program

#include <stdio.h>
#include <stdlib.h>

int main() {
    const char *str = "3.14159pi";
    char *endptr;
    long double num;

    num = strtold(str, &endptr);
    printf("Converted number: %Lf\n", num);
    printf("Remaining string: %s\n", endptr);
    return 0;
}

Explanation:

1. The string "3.14159pi" contains a valid floating-point number followed by non-numeric characters.
2. strtold() converts the number 3.14159 and sets endptr to point to the substring "pi".
3. The program prints both the converted number and the remaining string.

Program Output:

Converted number: 3.141590
Remaining string: pi

Example 3: Handling Invalid Conversion

This example demonstrates how strtold() behaves when the string does not start with a valid floating-point number.

Program

#include <stdio.h>
#include <stdlib.h>

int main() {
    const char *str = "NotANumber";
    char *endptr;
    long double num;

    num = strtold(str, &endptr);
    if (str == endptr) {
        printf("No valid conversion could be performed.\n");
    } else {
        printf("Converted number: %Lf\n", num);
    }
    return 0;
}

Explanation:

1. The string "NotANumber" does not begin with a valid floating-point representation.
2. strtold() fails to convert any number and returns 0.0L, with endptr remaining equal to the original string pointer.
3. The program detects this by comparing the original string pointer with endptr and prints an error message.

Program Output:

No valid conversion could be performed.

Example 4: Detecting Overflow and Underflow

This example illustrates how to handle situations where the converted value is out of range, resulting in overflow or underflow.

Program

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <math.h>

int main() {
    const char *str = "1e8000"; // An exponent that causes overflow
    char *endptr;
    long double num;

    errno = 0; // Reset errno before conversion
    num = strtold(str, &endptr);

    if (errno == ERANGE) {
        printf("Overflow or underflow occurred.\n");
    } else {
        printf("Converted number: %Lf\n", num);
    }
    return 0;
}

Explanation:

1. The string "1e500" represents a number that exceeds the range of representable values.
2. strtold() returns a value (typically HUGE_VALL) and sets errno to ERANGE.
3. The program checks errno to detect the overflow condition and prints an appropriate message.

Program Output:

Overflow or underflow occurred.