SysUtils.FormatFloat Function

Formats a floating point value.

Pascal

function FormatFloat(const Format: string; Value: Extended): string; overload;
function FormatFloat(const Format: string; Value: Extended; const FormatSettings: TFormatSettings): string; overload;

C++

AnsiString FormatFloat(const AnsiString Format, Extended Value);
AnsiString FormatFloat(const AnsiString Format, Extended Value, const TFormatSettings FormatSettings);

File

SysUtils

Description

FormatFloat formats the floating-point value given by Value using the format string given by Format. The following format specifiers are supported in the format string:

Specifier	Represents
0	Digit place holder. If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the output string. Otherwise, a '0' is stored in that position in the output string.
#	Digit placeholder. If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
.	Decimal point. The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored. The actual character used as a the decimal separator in the output string is determined by the DecimalSeparator global variable or its TFormatSettings equivalent.
,	Thousand separator. If the format string contains one or more ',' characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of ',' characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is determined by the ThousandSeparator global variable or its TFormatSettings equivalent.
E+	Scientific notation. If any of the strings 'E+', 'E-', 'e+', or 'e-' are contained in the format string, the number is formatted using scientific notation. A group of up to four '0' characters can immediately follow the 'E+', 'E-', 'e+', or 'e-' to determine the minimum number of digits in the exponent. The 'E+' and 'e+' formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The 'E-' and 'e-' formats output a sign character only for negative exponents.
'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting.
;	Separates sections for positive, negative, and zero numbers in the format string.

The locations of the leftmost '0' before the decimal point in the format string and the rightmost '0' after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ('0' or '#') to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the '.' character in the format string, the extra digits are output before the first digit placeholder.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

One section: The format string applies to all values.

Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

If the section for positive values is empty, or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits, corresponding to a call to FloatToStrF with the ffGeneral format. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.

The first form of FormatFloat is not thread-safe, because it uses localization information contained in global variables. The second form of FormatFloat, which is thread-safe, refers to localization information contained in the FormatSettings parameter. Before calling the thread-safe form of FormatFloat, you must populate FormatSettings with localization information. To populate FormatSettings with a set of default locale values, call GetLocaleFormatSettings.

C++ Examples:

Copy Code

/*
The following example uses two buttons, a string grid, and
text edit on a form. When the conversion button is clicked,
the values across the top of the string grid are converted
using the formats along the left side.  Select a cell and
use the Alter Cell button and text edit to change the
values converted and the conversion formats.
*/
void __fastcall TForm1::Button1Click(TObject *Sender)
{
  for (int x = 1; x < StringGrid1->ColCount; x++)
  {
    for (int y = 1; y < StringGrid1->RowCount; y++)
    {
      StringGrid1->Cells[x][y] = FormatFloat(
      StringGrid1->Cells[0][y], StrToFloat(StringGrid1->Cells[x][0]));
    }
  }
}

int currCellCol, currCellRow;

void __fastcall TForm1::StringGrid1MouseUp(TObject *Sender, TMouseButton Button,
      TShiftState Shift, int X, int Y)
{
  StringGrid1->MouseToCell(X, Y, currCellCol, currCellRow);
}

// Alter Cell
void __fastcall TForm1::Button2Click(TObject *Sender)
{
  StringGrid1->Cells[currCellCol][currCellRow] = Edit1->Text;
}

void __fastcall TForm1::FormCreate(TObject *Sender)
{
  StringGrid1->Cells[1][0] = "1234";
  StringGrid1->Cells[2][0] = "-1234";
  StringGrid1->Cells[3][0] = "0.5";
  StringGrid1->Cells[4][0] = "0";
  StringGrid1->Cells[0][1] = "";
  StringGrid1->Cells[0][2] = "0";
  StringGrid1->Cells[0][3] = "0.00";
  StringGrid1->Cells[0][4] = "#.##";
  StringGrid1->Cells[0][5] = "#,##0.00";
  StringGrid1->Cells[0][6] = "#,##0.00;(#,##0.00)";
  StringGrid1->Cells[0][7] = "#,##0.00;;Zero";
  StringGrid1->Cells[0][8] = "0.000E+00";
  StringGrid1->Cells[0][9] = "#.###E-0";
}

Delphi Examples:

Copy Code

{
The following example uses two buttons, a string grid, and
text edit on a form. When the conversion button is clicked,
the values across the top of the string grid are converted
using the formats along the left side.  Select a cell and
use the Alter Cell button and text edit to change the
values converted and the conversion formats.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  X, Y, I: Integer;
begin
  for X := 1 to StringGrid1.ColCount - 1 do
  begin
    for Y := 0 to StringGrid1.RowCount - 1 do
    begin
      StringGrid1.Cells[X,Y] := SysUtils.FormatFloat(
        StringGrid1.Cells[0,Y], StrToFloat(StringGrid1.Cells[X,0]));
    end;
  end;

end;

var currCellCol, currCellRow: Integer;

// Alter Cell
procedure TForm1.Button2Click(Sender: TObject);
begin
  StringGrid1.Cells[currCellCol,currCellRow] := Edit1.Text;
end;

procedure TForm1.StringGrid1MouseUp(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Integer);
begin
  StringGrid1.MouseToCell(X, Y, &currCellCol, &currCellRow);
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  StringGrid1.Cells[1,0] := '1234';
  StringGrid1.Cells[2,0] := '-1234';
  StringGrid1.Cells[3,0] := '0.5';
  StringGrid1.Cells[4,0] := '0';
  StringGrid1.Cells[0,1] := '';
  StringGrid1.Cells[0,2] := '0';
  StringGrid1.Cells[0,3] := '0.00';
  StringGrid1.Cells[0,4] := '#.##';
  StringGrid1.Cells[0,5] := '#,##0.00';
  StringGrid1.Cells[0,6] := '#,##0.00;(#,##0.00)';
  StringGrid1.Cells[0,7] := '#,##0.00;;Zero';
  StringGrid1.Cells[0,8] := '0.000E+00';
  StringGrid1.Cells[0,9] := '#.###E-0';
end;

Copy Code

{
The following example displays in a dialog the disk free 
space of the current drive with commas as thousand separators.
}
procedure TForm1.Button1Click(Sender: TObject);
begin
  ShowMessage(FormatFloat('#,##0 bytes', DiskFree(0)));
end;