Overloocked Format( ) options

[Rollo62 498]

Hi there,

 

I was just reading @jeroenp 's blog, from here.

Thats so much true, and I love Format() since the old C days

 

What I wanted to add here is another "overlooked" option, adding leading zeroes, which is described here.

Maybe there are even more "overlooked" features, I'm not aware of ?   I'm curious.

 

 

[Uwe Raabe 1877]

The documentation found in System.SysUtils.pas is pretty comprehensive. A thorough read is recommended.

{ The Format routine formats the argument list given by the Args parameter
  using the format string given by the Format parameter.

  Format strings contain two types of objects--plain characters and format
  specifiers. Plain characters are copied verbatim to the resulting string.
  Format specifiers fetch arguments from the argument list and apply
  formatting to them.

  Format specifiers have the following form:

    "%" [index ":"] ["-"] [width] ["." prec] type

  A format specifier begins with a % character. After the % come the
  following, in this order:

  -  an optional argument index specifier, [index ":"]
  -  an optional left-justification indicator, ["-"]
  -  an optional width specifier, [width]
  -  an optional precision specifier, ["." prec]
  -  the conversion type character, type

  The following conversion characters are supported:

  d  Decimal. The argument must be an integer value. The value is converted
     to a string of decimal digits. If the format string contains a precision
     specifier, it indicates that the resulting string must contain at least
     the specified number of digits; if the value has less digits, the
     resulting string is left-padded with zeros.

  u  Unsigned decimal.  Similar to 'd' but no sign is output.

  e  Scientific. The argument must be a floating-point value. The value is
     converted to a string of the form "-d.ddd...E+ddd". The resulting
     string starts with a minus sign if the number is negative, and one digit
     always precedes the decimal point. The total number of digits in the
     resulting string (including the one before the decimal point) is given
     by the precision specifer in the format string--a default precision of
     15 is assumed if no precision specifer is present. The "E" exponent
     character in the resulting string is always followed by a plus or minus
     sign and at least three digits.

  f  Fixed. The argument must be a floating-point value. The value is
     converted to a string of the form "-ddd.ddd...". The resulting string
     starts with a minus sign if the number is negative. The number of digits
     after the decimal point is given by the precision specifier in the
     format string--a default of 2 decimal digits is assumed if no precision
     specifier is present.

  g  General. The argument must be a floating-point value. The value is
     converted to the shortest possible decimal string using fixed or
     scientific format. The number of significant digits in the resulting
     string is given by the precision specifier in the format string--a
     default precision of 15 is assumed if no precision specifier is present.
     Trailing zeros are removed from the resulting string, and a decimal
     point appears only if necessary. The resulting string uses fixed point
     format if the number of digits to the left of the decimal point in the
     value is less than or equal to the specified precision, and if the
     value is greater than or equal to 0.00001. Otherwise the resulting
     string uses scientific format.

  n  Number. The argument must be a floating-point value. The value is
     converted to a string of the form "-d,ddd,ddd.ddd...". The "n" format
     corresponds to the "f" format, except that the resulting string
     contains thousand separators.

  m  Money. The argument must be a floating-point value. The value is
     converted to a string that represents a currency amount. The conversion
     is controlled by the CurrencyString, CurrencyFormat, NegCurrFormat,
     ThousandSeparator, DecimalSeparator, and CurrencyDecimals global
     variables, all of which are initialized from locale settings provided
     by the operating system.  For example, Currency Format preferences can be
     set in the International section of the Windows Control Panel. If the format
     string contains a precision specifier, it overrides the value given
     by the CurrencyDecimals global variable.

  p  Pointer. The argument must be a pointer value. The value is converted
     to a string of the form "XXXX:YYYY" where XXXX and YYYY are the
     segment and offset parts of the pointer expressed as four hexadecimal
     digits.

  s  String. The argument must be a character, a string, or a PChar value.
     The string or character is inserted in place of the format specifier.
     The precision specifier, if present in the format string, specifies the
     maximum length of the resulting string. If the argument is a string
     that is longer than this maximum, the string is truncated.

  x  Hexadecimal. The argument must be an integer value. The value is
     converted to a string of hexadecimal digits. If the format string
     contains a precision specifier, it indicates that the resulting string
     must contain at least the specified number of digits; if the value has
     less digits, the resulting string is left-padded with zeros.

  Conversion characters may be specified in upper case as well as in lower
  case--both produce the same results.

  For all floating-point formats, the actual characters used as decimal and
  thousand separators are obtained from the DecimalSeparator and
  ThousandSeparator global variables.

  Index, width, and precision specifiers can be specified directly using
  decimal digit string (for example "%10d"), or indirectly using an asterisk
  charcater (for example "%*.*f"). When using an asterisk, the next argument
  in the argument list (which must be an integer value) becomes the value
  that is actually used. For example "Format('%*.*f', [8, 2, 123.456])" is
  the same as "Format('%8.2f', [123.456])".

  A width specifier sets the minimum field width for a conversion. If the
  resulting string is shorter than the minimum field width, it is padded
  with blanks to increase the field width. The default is to right-justify
  the result by adding blanks in front of the value, but if the format
  specifier contains a left-justification indicator (a "-" character
  preceding the width specifier), the result is left-justified by adding
  blanks after the value.

  An index specifier sets the current argument list index to the specified
  value. The index of the first argument in the argument list is 0. Using
  index specifiers, it is possible to format the same argument multiple
  times. For example "Format('%d %d %0:d %d', [10, 20])" produces the string
  '10 20 10 20'.

  The Format function can be combined with other formatting functions. For
  example

    S := Format('Your total was %s on %s', [
      FormatFloat('$#,##0.00;;zero', Total),
      FormatDateTime('mm/dd/yy', Date)]);

  which uses the FormatFloat and FormatDateTime functions to customize the
  format beyond what is possible with Format.

  Each of the string formatting routines that uses global variables for
  formatting (separators, decimals, date/time formats etc.), has an
  overloaded equivalent requiring a parameter of type TFormatSettings. This
  additional parameter provides the formatting information rather than the
  global variables. For more information see the notes at TFormatSettings.  }

 

[Der schöne Günther 306]

I didn't even know, altough it's properly documented:

System.SysUtils.Format - RAD Studio API Documentation (embarcadero.com)

 

I still find

('The result is %8.2f', [myFloat])

more readable than

('The result is *.*f', [8, 2, myFloat])

[dummzeuch 1387]

32 minutes ago, Der schöne Günther said:

I didn't even know, altough it's properly documented:

System.SysUtils.Format - RAD Studio API Documentation (embarcadero.com)

 

I still find

('The result is %8.2f', [myFloat])

more readable than

('The result is *.*f', [8, 2, myFloat])

The second syntax is meant to be used with variables rather than constants.

[dummzeuch 1387]

Format is very flexible but unfortunately there is no compile time checking for the  (or has it been added in newer Delphi versions?).

Unfortunately it's also difficult to debug (from user error reports) since you don't see the format string in the error message. That's why I always hook this function and add the format string to the error message. If anybody is interested, I can post that unit here.

[Tommi Prami 123]

24 minutes ago, dummzeuch said:

Format is very flexible but unfortunately there is no compile time checking for the  (or has it been added in newer Delphi versions?).

Unfortunately it's also difficult to debug (from user error reports) since you don't see the format string in the error message. That's why I always hook this function and add the format string to the error message. If anybody is interested, I can post that unit here.

FixInsight tries to check Format strings and parameter count, which is nice. Not checking types I think. Have found couple of bugs with it.

 

-Tee-

[Rollo62 498]

3 hours ago, dummzeuch said:

Format is very flexible but unfortunately there is no compile time checking

Thats true, this is why I work with my predefined constants for some most usual settings, to avoid typos.

[Fr0sT.Brutal 897]

I find useful indexed placeholders:

Format('One more %0:s found nearby. Interesting how much %0:ss there are?', ['zombie']);

Edited May 13, 2021 by Fr0sT.Brutal
fix to %0:s

[Attila Kovacs 617]

you mean %0:s?

[dummzeuch 1387]

23 hours ago, Uwe Raabe said:

p Pointer. The argument must be a pointer value. The value is converted to a string of the form "XXXX:YYYY" where XXXX and YYYY are the segment and offset parts of the pointer expressed as four hexadecimal digits.

That doesn't sound like up to date documentation.

[Fr0sT.Brutal 897]

4 hours ago, Attila Kovacs said:

you mean %0:s?

Sure. Fixed, thx