tango.io.Print

License:
BSD style: see license.txt

Version:
Feb 2007: Separated from Stdout

author:
Kris

class Print (T): OutputStream;

A bridge between a Layout instance and a Buffer. This is used for the Stdout & Stderr globals, but can be used for general purpose buffer-formatting as desired. The Template type 'T' dictates the text arrangement within the target buffer ~ one of char, wchar or dchar (utf8, utf16, or utf32).

Print exposes this style of usage:

        auto print = new Print!(char) (...);

        print ("hello");                        => hello
        print (1);                              => 1
        print (3.14);                           => 3.14
        print ('b');                            => b
        print (1, 2, 3);                        => 1, 2, 3
        print ("abc", 1, 2, 3);                 => abc, 1, 2, 3
        print ("abc", 1, 2) ("foo");            => abc, 1, 2foo
        print ("abc") ("def") (3.14);           => abcdef3.14

        print.format ("abc {}", 1);             => abc 1
        print.format ("abc {}:{}", 1, 2);       => abc 1:2
        print.format ("abc {1}:{0}", 1, 2);     => abc 2:1
        print.format ("abc ", 1);               => abc

Note that the last example does not throw an exception. There are several use-cases where dropping an argument is legitimate, so we're currently not enforcing any particular trap mechanism.

Flushing the output is achieved through the flush() method, or via an empty pair of parens:

        print ("hello world") ();
        print ("hello world").flush;

        print.format ("hello {}", "world") ();
        print.format ("hello {}", "world").flush;

Special character sequences, such as "\n", are written directly to the output without any translation (though an output-filter could be inserted to perform translation as required). Platform-specific newlines are generated instead via the newline() method, which also flushes the output when configured to do so:

        print ("hello ") ("world").newline;
        print.format ("hello {}", "world").newline;
        print.formatln ("hello {}", "world");

The format() method supports the range of formatting options exposed by tango.text.convert.Layout and extensions thereof; including the full I18N extensions where configured in that manner. To create a French instance of Print :

        import tango.text.locale.Locale;

        auto locale = new Locale (Culture.getCulture ("fr-FR"));
        auto print = new Print!(char) (locale, ...);

Note that Print is *not* intended to be thread-safe. Use either tango.util.log.Trace or the standard logging facilities in order to enable atomic console I/O

this(Layout!(T) convert, OutputStream output, T[] eol = Eol);: Construct a Print instance, tying the provided stream to a layout formatter
Print format (T[] fmt,...);: Layout using the provided formatting specification
Print formatln (T[] fmt,...);: Layout using the provided formatting specification
Print print (...);: Unformatted layout, with commas inserted between args. Currently supports a maximum of 24 arguments
Print newline ();: Output a newline and optionally flush
Print flush (bool yes);: Control implicit flushing of newline(), where true enables flushing. An explicit flush () will always flush the output.
OutputStream stream ();: Return the associated output stream
Print stream (OutputStream output);: Set the associated output stream
Layout!(T) layout ();: Return the associated Layout
Print layout (Layout!(T) layout );: Set the associated Layout
uint sink (T[] s);: Sink for passing to the formatter
IConduit conduit ();: OutputStream Interface

Return the host conduit
uint write (void[] src);: Write to conduit from a source array. The provided src content will be written to the conduit.

Returns the number of bytes written from src, which may be less than the quantity provided
OutputStream flush ();: Flush the output stream
OutputStream copy (InputStream src);: Transfer the content of another conduit to this one. Returns a reference to this class, and throws IOException on failure.
void close ();: Close the output

anchorFromTitle('tango.io.Print', 'source/', 'html');