C library function -newlocale()

C Standard Library - <locale.h>

Description

newlocale()is a function in the C standard library used to create a new locale object. This function allows the program to create a specific locale setting, and can be modified or extended based on an existing locale.

Declaration

Below is the declaration of the newlocale() function.

#include <locale.h>

locale_t newlocale(int category_mask, const char *locale, locale_t base);

Parameter

  • category_mask: A mask of one or more locale categories to set. It can be a combination of the following macros (via the bitwise OR operator|Combination):

    • LC_COLLATE_MASK: Localization information related to string comparison.
    • LC_CTYPE_MASKLocalization information related to character classification and conversion.
    • LC_MONETARY_MASK: Localization information related to currency format.
    • LC_NUMERIC_MASK: Localization information related to numeric format.
    • LC_TIME_MASK: Localization information related to time format.
    • LC_MESSAGES_MASK: Localization information related to message display.
    • LC_ALL_MASKAll localization categories.

  • locale: A string specifying the locale name to set (e.g., "en_US.UTF-8"). If it isNULLThen the default locale is used.

  • base: an existinglocale_tobject, used as the basis for creating a new locale object. If it isNULLThen a new object is created from scratch.

Return Value

  • On success, returns the newly created locale object (typelocale_t）。
  • On failure, returnsNULL。

Example

The following is sample code for creating and using a new locale object with newlocale():

Example

#include <stdio.h>
#include <locale.h>
#include <xlocale.h> // Required when using GNU extensions

int main() {
    // Create a new locale object, using the "en_US.UTF-8" locale setting
    locale_t newloc = newlocale(LC_ALL_MASK, "en_US.UTF-8", (locale_t)0);
    if (newloc == (locale_t)0) {
        perror("newlocale");
        return 1;
    }

    // Set the current thread's locale object to the new locale object
    locale_t oldloc = uselocale(newloc);

    // Get and print current locale information
    struct lconv *lc = localeconv();
    printf("Decimal point character in new locale: %s\n", lc->decimal_point);
    printf("Thousands separator in new locale: %s\n", lc->thousands_sep);

    // Restore the previous locale object
    uselocale(oldloc);

    // Release the new locale object
    freelocale(newloc);

    return 0;
}

Let us compile and run the above program, which will produce the following result:

Decimal point character in new locale: .
Thousands separator in new locale: ,

Code explanation

Create a new locale object

  • newlocale(LC_ALL_MASK, "en_US.UTF-8", NULL): Create a new locale object, using the "en_US.UTF-8" locale, based on the default locale object.
  • newlocale(LC_NUMERIC_MASK | LC_TIME_MASK, "fr_FR.UTF-8", NULL): Create a new locale object, setting numeric and time formats to "fr_FR.UTF-8" (French - France), with other categories using default settings.

Set the thread locale object

  • Usageuselocale(newloc)Set the current thread's locale object to the newly created locale object.
  • Usageuselocale(oldloc)Restore the previous locale object.

Releases the localization object

  • Usagefreelocale(newloc)Release the newly created locale object to avoid memory leaks.

Notes

  • newlocale()is part of the POSIX.1-2008 standard and is not supported on all platforms. If using the GNU C library, be sure to include<xlocale.h>Header file.
  • newlocale()returnedlocale_tThe object can be passed touselocale()function, so as to temporarily use a different locale in a thread.

Summary

newlocale()function allows creating and using new locale objects, so that programs can handle different locale settings and localization needs. By combiningnewlocale()、uselocale()andfreelocale()With this function, programmers can manage and switch the program's localization information more flexibly, thereby supporting the development of internationalized applications.

C Standard Library - <locale.h>

other extensions