ITemplateFormatPrintable

ITemplateFormatPrintable prints template texts using a format provider.

/// <summary>Printable template text. Printing assigns arguments to placeholders.</summary>
public interface ITemplateFormatPrintable : ITemplatePrintableBase
{
    /// <summary>Print <paramref name="arguments"/> in placeholders using <paramref name="formatProvider"/>.</summary>
    string Print(IFormatProvider? formatProvider, object?[]? arguments = null);
    /// <summary>Append to <paramref name="sb"/>.</summary>
    void AppendTo(StringBuilder sb, IFormatProvider? formatProvider, object?[]? arguments = null);
    /// <summary>Write to <paramref name="textWriter"/>.</summary>
    void WriteTo(TextWriter textWriter, IFormatProvider? formatProvider, object?[]? arguments = null);
    /// <summary>Try print <paramref name="arguments"/> using <paramref name="formatProvider"/> into <paramref name="dst"/>.</summary>
    /// <param name="length">Number of characters written to <paramref name="dst"/>. If failed, the 0 is returned.</param>
    /// <returns>True if text was written, false if write failed.</returns>
    bool TryPrintTo(Span<char> dst, out int length, IFormatProvider? formatProvider, object?[]? arguments = null);
    /// <summary>Try estimate print length</summary>
    bool TryEstimatePrintLength(out int length, IFormatProvider? formatProvider, object?[]? arguments = null);
}

/// <summary>Root interface printable template.</summary>
public interface ITemplatePrintableBase
{
    /// <summary>Parameters in order of arguments and correspondence to <see cref="ITemplateParameterPart.ParameterIndex"/>.</summary>
    string?[] ParameterNames { get; set; }
}

Printing

.Print(culture, arguments) prints template string by placing arguments into placeholders.

// Create text without template format
ITemplateFormatPrintable printable = new TemplateText("Time is {0}.", TemplateFormat.Brace);
// Create arguments
object?[] arguments = { DateTime.Now };
// Print ok
string print = printable.Print(CultureInfo.CurrentCulture, arguments);
// ""
WriteLine(print);

.Print(culture, argumentMap) prints from a dictionary of arguments.

// Create text without template format
ITemplateFormatPrintable printable = new TemplateText("Time is {0}.", TemplateFormat.Brace);
// Create arguments
IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", DateTime.Now } };
// Print ok
string print = printable.Print(CultureInfo.CurrentCulture, argumentMap);
// ""
WriteLine(print);

Printable doesn't expose its inner template string. The implemenation may actually use different template strings, such as a localized or pluralized versions, depending on provided culture and argument values.

// "You have no apples."
printable.Print(CultureInfo.GetCultureInfo("en"), new object?[] { 0 });
// "You have an apple."
printable.Print(CultureInfo.GetCultureInfo("en"), new object?[] { 1 });
// "You have 3 apples."
printable.Print(CultureInfo.GetCultureInfo("en"), new object?[] { 3 });
// "Sinulla ei ole omenoita."
printable.Print(CultureInfo.GetCultureInfo("fi"), new object?[] { 0 });
// "Sinulla on yksi omena."
printable.Print(CultureInfo.GetCultureInfo("fi"), new object?[] { 1 });
// "Sinulla on 3 omenaa."
printable.Print(CultureInfo.GetCultureInfo("fi"), new object?[] { 3 });

.EstimatePrintLength(culture, arguments) counts the number of characters and .PrintTo(span, culture, arg) writes to span. This is zero heap printing.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
object[] arguments = { 3 };
// Estimate length
int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, arguments);
// Allocate span
Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
// Print to span
length = printable.PrintTo(span, CultureInfo.InvariantCulture, arguments);
// Print to stdout, zero heap.
Console.Out.Write(span[..length]);

.EstimatePrintLength(culture, argumentMap) estimates length from a dictionary of arguments.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
// Estimate length
int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, argumentMap);
// Allocate span
Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
// Print to span
length = printable.PrintTo(span, CultureInfo.InvariantCulture, argumentMap);
// Print to stdout, zero heap.
Console.Out.Write(span[..length]);

.TryPrintTo(span, culture, arguments) attempts to print without possibility of throwing InvalidOperationException.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
object[] arguments = { 3 };
// Estimate length
int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, arguments);
// Allocate span
Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
// Print to span
if (printable.TryPrintTo(span, out length, CultureInfo.InvariantCulture, arguments))
    Console.Out.Write(span[..length]);

.TryPrintTo(span, culture, argumentMap) attempts to print from a dictionary of arguments.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
// Estimate length
int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, argumentMap);
// Allocate span
Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
// Print to span
if (printable.TryPrintTo(span, out length, CultureInfo.InvariantCulture, argumentMap))
    Console.Out.Write(span[..length]);

.AppendTo(stringbuilder, culture, arguments) appends to string builder.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
object?[] arguments = { 3 };
// Create string builder
StringBuilder sb = new(1024);
// Append to string builder
printable.AppendTo(sb, CultureInfo.InvariantCulture, arguments);
// Print
WriteLine(sb); // "You have 3 apple(s)."

.AppendTo(stringbuilder, culture, argumentMap) appends from a dictionary of arguments.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
object?[] arguments = { 3 };
// Create string builder
StringBuilder sb = new(1024);
// Append to string builder
printable.AppendTo(sb, CultureInfo.InvariantCulture, arguments);
// Print
WriteLine(sb); // "You have 3 apple(s)."

.WriteTo(textwriter, culture, arguments) writes to text writer.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
object?[] arguments = { 3 };
// Assign text writer
TextWriter textWriter = Console.Out;
// Write to writer
printable.WriteTo(textWriter, CultureInfo.InvariantCulture, arguments); // "You have 3 apple(s)."

.WriteTo(textwriter, culture, argumentMap) writes from a dictionary of arguments.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Create arguments
IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
// Assign text writer
TextWriter textWriter = Console.Out;
// Write to writer
printable.WriteTo(textWriter, CultureInfo.InvariantCulture, argumentMap); // "You have 3 apple(s)."

Note

Thanks to C# 10 for Span, stackalloc, ISpanFormattable and MemoryPool which allow zero heap or near zero implementations.

// Create template
ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
// Rent arguments
object[] arguments = ArrayPool<object>.Shared.Rent(1);
// Assign argument
arguments[0] = "3";
// Estimate length
int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, arguments);
// Rent chars
char[] buffer = ArrayPool<char>.Shared.Rent(length);
// Print to buffer
length = printable.PrintTo(buffer.AsSpan(), CultureInfo.InvariantCulture, arguments);
// Print to stdout, zero heap.
Console.Out.Write(buffer.AsSpan()[..length]);
// Return rentals
ArrayPool<object>.Shared.Return(arguments);
ArrayPool<char>.Shared.Return(buffer);            

Full Example

Full example

using System.Buffers;
using System.Globalization;
using System.Text;
using Avalanche.Template;
using static System.Console;

public class templateformatprintable
{
    public static void Run()
    {
        {
            // <03>
            // Create text without template format
            ITemplateFormatPrintable printable = new TemplateText("Time is {0}.", TemplateFormat.Brace);
            // Create arguments
            object?[] arguments = { DateTime.Now };
            // Print ok
            string print = printable.Print(CultureInfo.CurrentCulture, arguments);
            // ""
            WriteLine(print);
            // </03>
        }
        {
            // <03B>
            // Create text without template format
            ITemplateFormatPrintable printable = new TemplateText("Time is {0}.", TemplateFormat.Brace);
            // Create arguments
            IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", DateTime.Now } };
            // Print ok
            string print = printable.Print(CultureInfo.CurrentCulture, argumentMap);
            // ""
            WriteLine(print);
            // </03B>
        }
        {
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // <04>
            // "You have no apples."
            printable.Print(CultureInfo.GetCultureInfo("en"), new object?[] { 0 });
            // "You have an apple."
            printable.Print(CultureInfo.GetCultureInfo("en"), new object?[] { 1 });
            // "You have 3 apples."
            printable.Print(CultureInfo.GetCultureInfo("en"), new object?[] { 3 });
            // "Sinulla ei ole omenoita."
            printable.Print(CultureInfo.GetCultureInfo("fi"), new object?[] { 0 });
            // "Sinulla on yksi omena."
            printable.Print(CultureInfo.GetCultureInfo("fi"), new object?[] { 1 });
            // "Sinulla on 3 omenaa."
            printable.Print(CultureInfo.GetCultureInfo("fi"), new object?[] { 3 });
            // </04>
        }

        {
            // <05>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            object[] arguments = { 3 };
            // Estimate length
            int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, arguments);
            // Allocate span
            Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
            // Print to span
            length = printable.PrintTo(span, CultureInfo.InvariantCulture, arguments);
            // Print to stdout, zero heap.
            Console.Out.Write(span[..length]);
            // </05>
            WriteLine();
        }
        {
            // <05B>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
            // Estimate length
            int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, argumentMap);
            // Allocate span
            Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
            // Print to span
            length = printable.PrintTo(span, CultureInfo.InvariantCulture, argumentMap);
            // Print to stdout, zero heap.
            Console.Out.Write(span[..length]);
            // </05B>
            WriteLine();
        }

        {
            // <06>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            object[] arguments = { 3 };
            // Estimate length
            int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, arguments);
            // Allocate span
            Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
            // Print to span
            if (printable.TryPrintTo(span, out length, CultureInfo.InvariantCulture, arguments))
                Console.Out.Write(span[..length]);
            // </06>
            WriteLine();
        }
        {
            // <06B>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
            // Estimate length
            int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, argumentMap);
            // Allocate span
            Span<char> span = length < 512 ? stackalloc char[length] : new char[length];
            // Print to span
            if (printable.TryPrintTo(span, out length, CultureInfo.InvariantCulture, argumentMap))
                Console.Out.Write(span[..length]);
            // </06B>
            WriteLine();
        }

        {
            // <11>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            object?[] arguments = { 3 };
            // Create string builder
            StringBuilder sb = new(1024);
            // Append to string builder
            printable.AppendTo(sb, CultureInfo.InvariantCulture, arguments);
            // Print
            WriteLine(sb); // "You have 3 apple(s)."
            // </11>
        }
        {
            // <11B>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
            // Create string builder
            StringBuilder sb = new(1024);
            // Append to string builder
            printable.AppendTo(sb, CultureInfo.InvariantCulture, argumentMap);
            // Print
            WriteLine(sb); // "You have 3 apple(s)."
            // </11B>
        }

        {
            // <13>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            object?[] arguments = { 3 };
            // Assign text writer
            TextWriter textWriter = Console.Out;
            // Write to writer
            printable.WriteTo(textWriter, CultureInfo.InvariantCulture, arguments); // "You have 3 apple(s)."
            // </13>
            WriteLine();
        }
        {
            // <13B>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Create arguments
            IDictionary<string, object?> argumentMap = new Dictionary<string, object?> { { "0", 3 } };
            // Assign text writer
            TextWriter textWriter = Console.Out;
            // Write to writer
            printable.WriteTo(textWriter, CultureInfo.InvariantCulture, argumentMap); // "You have 3 apple(s)."
            // </13B>
            WriteLine();
        }

        {
            // <20>
            // Create template
            ITemplateFormatPrintable printable = new TemplateText("You have {0} apple(s).", TemplateFormat.Brace);
            // Rent arguments
            object[] arguments = ArrayPool<object>.Shared.Rent(1);
            // Assign argument
            arguments[0] = "3";
            // Estimate length
            int length = printable.EstimatePrintLength(CultureInfo.InvariantCulture, arguments);
            // Rent chars
            char[] buffer = ArrayPool<char>.Shared.Rent(length);
            // Print to buffer
            length = printable.PrintTo(buffer.AsSpan(), CultureInfo.InvariantCulture, arguments);
            // Print to stdout, zero heap.
            Console.Out.Write(buffer.AsSpan()[..length]);
            // Return rentals
            ArrayPool<object>.Shared.Return(arguments);
            ArrayPool<char>.Shared.Return(buffer);            
            // </20>
            WriteLine();
        }
    }
}