Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function GetNumberFormat Lib "kernel32.dll" Alias "GetNumberFormatA" (ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, lpFormat As Any, ByVal lpNumberStr As String, ByVal cchNumber As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.5 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

GetNumberFormat formats a number for display. By default, the function formats the number according to the specified locale's settings. However, custom formatting preferences can instead be used. The end result of GetNumberFormat is a number displayed according to the user's preferences.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the number of characters copied into the string passed as lpNumberStr, not including the terminating null character.

Visual Basic-Specific Issues

When passing 0 for the lpFormat parameter, the expression ByVal CLng(0) must be used. See the example code for a demonstration of this.

Parameters

Locale

The locale identifier of the locale to format the number according to. This identifier could be generated by the MAKELCID macro. Alternatively, this could be one of the following flags specifying a locale:

LOCALE_SYSTEM_DEFAULT: The system's default locale.
LOCALE_USER_DEFAULT: The user's default locale.

dwFlags

If no structure is passed as lpFormat, this parameter determines the settings used to format the number. If this is 0, the current locale settings are used. Or, this could be the following flag:

LOCALE_NOUSEROVERRIDE: Use the system's default settings for the locale, regardless of any modifications the user may have made to it.

lpValue

A string containing the number to format. The only allowable characters in this string are the digits 0-9 and at most a single decimal point character (.). If the number is negative, the first character in the string must be a minus sign character (-). Any other characters are invalid.

lpFormat

To override the locale's formatting settings, pass a NUMBERFMT structure that contains the appropriate formatting information. To use the locale's settings instead, pass 0 for this parameter.

lpNumberStr

String that receives the null-terminated formatted number string. This string must have enough room to receive the string.

cchNumber

The number of characters in the string passed as lpNumberStr.

Constant Definitions

Const LOCALE_SYSTEM_DEFAULT = &H400 Const LOCALE_USER_DEFAULT = &H800 Const LOCALE_NOUSEROVERRIDE = &H80000000

Example

' This code is licensed according to the terms and conditions listed here. ' Declarations and such needed for the example: ' (Copy them to the (declarations) section of a module.) Public Type NUMBERFMT NumDigits As Long LeadingZero As Long Grouping As Long lpDecimalSep As String lpThousandSep As String NegativeOrder As Long End Type Public Declare Function GetNumberFormat Lib "kernel32.dll" Alias "GetNumberFormatA" _ (ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, lpFormat _ As Any, ByVal lpNumberStr As String, ByVal cchNumber As Long) As Long Const LOCALE_USER_DEFAULT = &H800 ' Display the number -1,234,567.89 according to two formatting rules. ' 1. Use the format specified by the current user locale. ' 2. Use a custom format specified by a structure passed to the function. Dim nft As NUMBERFMT ' custom formatting settings Dim formatted As String ' receives the formatted number strings Dim strlen As Long ' the length of the formatted string ' Display the number formatted according to the current locale. formatted = Space(256) strlen = GetNumberFormat(LOCALE_USER_DEFAULT, 0, "-1234567.89", ByVal CLng(0), _ formatted, Len(formatted)) formatted = Left(formatted, strlen) Debug.Print "User locale format: "; formatted ' Now display according the format we specify below. With nft ' Display three digits after the decimal point. .NumDigits = 3 ' Display zeros after the decimal point. .LeadingZero = 1 ' Group every three digits to the left of the decimal. .Grouping = 3 ' Use a comma to as the decimal point (like they do in France and Spain). .lpDecimalSep = "," ' Likewise, use a period as the grouping separator. .lpThousandSep = "." ' Put the negative sign immediately after the number. .NegativeOrder = 3 End With formatted = Space(256) strlen = GetNumberFormat(LOCALE_USER_DEFAULT, 0, "-1234567.89", nft, formatted, Len(formatted)) formatted = Left(formatted, strlen) Debug.Print "Custom format: "; formatted