Miscellaneous Functions

Locale-related functions and macros

This macro should be used as a statement. It declares a private variable (whose name begins with an underscore) that is needed by the other macros in this section. Failing to include this correctly should lead to a syntax error. For compatibility with C89 C compilers it should be placed in a block before any executable statements.

This is used by XS code that that is LC_NUMERIC locale-aware to force the locale for category LC_NUMERIC to be what perl thinks is the current underlying locale. (The perl interpreter could be wrong about what the underlying locale actually is if some C or XS code has called the C library function setlocale(3) behind its back; calling "sync_locale" before calling this macro will update perl's records.)

A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to declare at compile time a private variable used by this macro. This macro should be called as a single statement, not an expression, but with an empty argument list, like this:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

The private variable is used to save the current locale state, so that the requisite matching call to "RESTORE_LC_NUMERIC" can restore it.

This is used to help wrap XS or C code that that is LC_NUMERIC locale-aware. This locale category is generally kept set to the C locale by Perl for backwards compatibility, and because most XS code that reads floating point values can cope only with the decimal radix character being a dot.

This macro makes sure the current LC_NUMERIC state is set properly, to be aware of locale if the call to the XS or C code from the Perl program is from within the scope of a use locale; or to ignore locale if the call is instead from outside such scope.

This macro is the start of wrapping the C or XS code; the wrap ending is done by calling the "RESTORE_LC_NUMERIC" macro after the operation. Otherwise the state can be changed that will adversely affect other XS code.

A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to declare at compile time a private variable used by this macro. This macro should be called as a single statement, not an expression, but with an empty argument list, like this:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_SET_TO_NEEDED();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

This is used in conjunction with one of the macros "STORE_LC_NUMERIC_SET_TO_NEEDED" and "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"

to properly restore the LC_NUMERIC state.

A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to declare at compile time a private variable used by this macro and the two STORE ones. This macro should be called as a single statement, not an expression, but with an empty argument list, like this:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   RESTORE_LC_NUMERIC();
    ...
}