string.Format Compatibility

The main point about string.Format compatibility is, how curly braces and colons are processed in the format string.

In most cases string.Format compatibility does not bring any advantages.

1. SmartSettings.StringFormatCompatibility = true

TLDR; Custom formatter extensions cannot be parsed and used with this setting.

a) Curly Braces and Brace Escaping

SmartFormat acts as a drop-in replacement for string.Format. Thus curly braces are escaped the string.Format way:

If the desired output shall be "{literal}", it means escaping (i.e. doubling) the open and closing curly braces:

string.Format("{{literal}}") == Smart.Format("{{literal}}")

Smart.Format("{{0}} {{{0}}} {{}}", "Zero");
// Outputs: "{0} {Zero} {}"

b) Item Formats

Determines how to format items, such as numbers and dates:

Smart.Format("{0:N3} | {1:MMMM, yyyy}", 5.5, new DateTime(2010,3,4));
// Outputs: "5.500 | March, 2010"

c) Alignment

Inserts spaces before or after the item, aligning it with other items:

Smart.Format("|{0,-10}|{1,10}|", "Left", "Right");
// Outputs: "|Left      |     Right|"

d) Localization

Same as string.Format, Smart.Format uses the current UI culture info for formatting, or you can supply your own IFormatProvider:

Smart.Format(CultureInfo.GetCultureInfo("en-US"), "{0:C}", 1234) 
// Outputs: "$1,234.00"
Smart.Format(CultureInfo.GetCultureInfo("ja-JP"), "{0:C}", 1234) 
// Outputs: "¥1234"

e) Colons in Format Literals

// Works only with StringFormatCompatibility = true
Smart.Format("{0:yyyy-MM-dd HH:mm:ss}", new DateTime())`
// same as with
string.Format("{0:yyyy-MM-dd HH:mm:ss}", new DateTime())`

f) Indexed (numbered) Placeholders

Numbers correspond to the argument index:

Smart.Format("{0} {1}", "Hello", "World"); 
// Outputs: "Hello World"

g) Named Placeholders

While string.Format is limited to indexed placeholders like in the examples above, SmartFormat will also resolve named placeholders with dot notation:

var date = new { Today = DateTime.Now };
// formats the Date property of a DateTime structure
Smart.Format("It is now {Today.Date:yyyy/MM/dd HH:mm:ss}", date);

2. SmartSettings.StringFormatCompatibility = false

TLDR; All features of SmartFormat can be used

a) Differences to string.Format

• Curly braces are escaped with a backslash instead using double curly braces.
• Colons must always be escaped when used in the option or format part of a placeholder.

b) Commonalities with string.Format

• Alignment

  Smart.Format("|{0,-10}|{1,10}|", "Left", "Right");
  // Outputs: "|Left      |     Right|"

• Localization

  Smart.Format(CultureInfo.GetCultureInfo("en-US"), "{0:C}", 1234) 
  // Outputs: "$1,234.00"
  Smart.Format(CultureInfo.GetCultureInfo("ja-JP"), "{0:C}", 1234) 
  // Outputs: "¥1234"

• null Values

  null will be output as string.Empty

c) Colons in Format Literals

Colons must always be escaped when used in the option or format part of a placeholder.

// string.Format allows for colons in the format part...
string.Format("{0:yyyy-MM-dd HH:mm:ss}", new DateTime())`

// ... but it's also allowed to escape colons
string.Format("{0:yyyy-MM-dd HH\:mm\:ss}", new DateTime())

// Does not work with StringFormatCompatibility = false
Smart.Format("{0:yyyy-MM-dd HH:mm:ss}", new DateTime())`

Note: In the last example the Parser would use the literal substring "yyyy-MM-dd HH" as a custom formatter name.

// Works with StringFormatCompatibility = true | false
Smart.Format(@"{0:yyyy-MM-dd HH\:mm\:ss}", new DateTime())

d) SmartFormat Extensions

All SmartFormat extensions can be used, e.g. the ListFormatter:

var data = new [] {1, 2, 3};
_ = Smart.Format(@"{0:list:*{:N2}*|  \:  }", data);
// Result: "*1,00*  :  *2,00*  :  *3,00*"

3. Summary

Take SmartSettings.StringFormatCompatibility = false (the default setting) to use all features of SmartFormat, or true if you're heading for full compatibility with string.Format.