List formatter
Format the items of a collection and join them with spacers, or index into a list with a selector.
The List formatter is both a formatter and a source. As a formatter it repeats a format for each item of any IEnumerable, such as an array or a List<T>, joining the items with spacers. As a source it provides list-item selectors, so you can read an item by index or by the current iteration index. Apply the formatter explicitly with the name list, or omit the name to apply it implicitly to a collection.
flowchart TD
full["{value:list:template|spacer|final spacer}"]
full --> p1["value"]
full --> p2["list"]
full --> p3["template"]
full --> p4["spacer"]
full --> p5["final spacer"]
p1 --> d1["Any IEnumerable"]
p2 --> d2["Formatter name: list<br/>(or implicit)"]
p3 --> d3["Template: how each<br/>item is formatted"]
p4 --> d4["Spacer: added after each<br/>item except the last"]
p5 --> d5["Final spacer: replaces the<br/>last spacer (optional)"]
classDef code fill:#F5F5F5,stroke:#BDBDBD,color:#111;
classDef orange fill:none,stroke:none,color:#F37021;
classDef green fill:none,stroke:none,color:#67BC6B;
classDef purple fill:none,stroke:none,color:#765BA7;
class full code;
class p1,d1 orange;
class p2,d2 green;
class p3,d3 purple;
class p4,d4 purple;
class p5,d5 purple;
linkStyle default stroke:#2196F3,stroke-width:1.5px;
The format takes up to four parts, separated by the split character:
| Part | Description |
|---|---|
| Item format | The format applied to each item. An empty placeholder {} outputs the item itself. |
| Spacer | Written between items. |
| Last spacer | Optional. Replaces the spacer before the final item. |
| Two spacer | Optional. Used as the only spacer when the list has exactly two items. |
The item format can contain nested placeholders, so each item can be formatted in detail, for example {Sizes:list:{Width}x{Height}|, }. |
Spacers can include character literals, for example \n to put each item on its own line.
A spacer that contains nested placeholders is formatted against the collection’s parent value, not the individual item.
Format a list
| Smart String | Argument | Result |
|---|---|---|
{0:list:{}\|, \|, and } |
["one", "two", "three"] |
one, two, and three |
{0:list:{}\| and } |
["one", "two"] |
one and two |
{0:list:{:0.00}\|, } |
[1, 2, 3] |
1.00, 2.00, 3.00 |
List-item selectors
As a source, the List formatter lets a selector index into an IList. Use a numeric selector to read a specific item, and the index selector to read the current item’s position while iterating.
A string is an IEnumerable, but the formatter does not treat strings or IFormattable values as lists.
| Smart String | Argument | Result |
|---|---|---|
The value at index 1 is {0.1} |
[1, 2, 3] |
The value at index 1 is 2 |
{0.0} {0.1} {0.2} |
[1, "Hello", "World"] |
1 Hello World |
Use the index selector to synchronize two lists by iterating one and indexing the other at the same position:
| Smart String | Argument | Result |
|---|---|---|
{0:{} = {1.index}\|, } |
[1, 2, 3, 4] and ["one", "two", "three", "four"]
|
1 = one, 2 = two, 3 = three, 4 = four |