Formats a number string as a number string customized for a locale specified by identifier.

Note: This function retrieves information only about a locale specified by identifier. Additional locales, features, and RFC 4646 names are supported by the GetNumberFormatEx function.

int GetNumberFormat(
  LCID Locale,                
  DWORD dwFlags,              
  LPCTSTR lpValue,            
  CONST NUMBERFMT* lpFormat,  
  LPTSTR lpNumberStr,         
  int cchNumber        
);

Parameters

Locale

[in] Locale identifier that specifies the locale. You can use the MAKELCID macro to create a locale identifier or use one of the following predefined values. For more information, see Locale Identifier Constants and Strings.

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

Windows Vista and later: The following custom locale identifiers are also supported.

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

dwFlags

[in] Flags controlling the operation of the function. The application must set this parameter to 0 if lpFormat does not indicate a null pointer. In this case, the function formats the string using user overrides to the default number format for the locale. If lpFormat is set to a null pointer, the application can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default number format for the specified locale. Note: Since LOCALE_NOUSEROVERRIDE disables user preferences, its use is discouraged.

lpValue

[in] Pointer to a null-terminated string containing the number string to format. This string can only contain the following characters. All other characters are invalid. The function returns an error if the string indicated by lpValue deviates from these rules.

• Characters '0' through '9'.
• One decimal point (dot) if the number is a floating-point value.
• A minus sign in the first character position if the number is a negative value.

lpFormat

[in] Pointer to a NUMBERFMT structure that contains number formatting information, with all members set to appropriate values. If this parameter does not indicate a null pointer, the function uses the locale only for formatting information not specified in the structure, for example, the locale-specific string value for the negative sign.

lpNumberStr

[out] Pointer to a buffer in which this function retrieves the formatted number string.

cchNumber

[in] Size, in TCHAR values, for the number string buffer indicated by lpNumberStr.

Alternatively, the application can set this parameter to 0. In this case, the function returns the required size for the number string buffer, and does not use the lpNumberStr parameter.

Return Values

Returns the number of TCHAR values retrieved in the buffer indicated by lpNumberStr if successful. If the cchNumber parameter is set to 0, the function returns the number of characters required to hold the formatted number string, including a terminating null character.

The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError. GetLastError can return one of the following error codes:

• ERROR_INSUFFICIENT_BUFFER
• ERROR_INVALID_FLAGS
• ERROR_INVALID_PARAMETER
• ERROR_OUTOFMEMORY

Remarks

When the ANSI version of this function is used with a Unicode-only locale identifier, the function can succeed because the operating system uses the system code page. However, characters that are undefined in the system code page appear in the string as a question mark (?). To determine the identifiers that are Unicode-only, see Locale Identifier Constants and Strings.

Windows 95/98/Me: The Unicode version of this function is supported by the Microsoft Layer for Unicode. To use this version, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.

This function can return data from custom locales. Locales are not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.

Applications that are intended to run only on Windows Vista and later should use GetNumberFormatEx in preference to this function. GetNumberFormatEx provides good support for supplemental locales. However, GetNumberFormatEx is not supported for versions of Windows prior to Windows Vista.

Requirements

  Windows NT/2000/XP/Vista: Included in Windows NT 3.5 and later.
  Windows 95/98/Me: Included in Windows 95 and later.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP. Also supported by Microsoft Layer for Unicode.
  Header: Declared in Winnls.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

National Language Support, National Language Support Functions, GetCurrencyFormat, GetNumberFormatEx, NUMBERFMT