/MEng/System/Runtime/TextOutStream

ClassPath:	MEng.System.Runtime.TextOutStream
Parent ClassPath:	MEng.Object
Copyable:	No
Final:	No

MEng.System.Runtime.TextOutStream is a base class from which a set of output text streams are derived. An output text stream is a class that provide methods to which you can pass all of the intrinsic (fundamental) classes and it will format them to text in some appropriate way. Since, in the end, all classes are made up of from instances of the intrinsic classes, this provides the means to format out out any class in some attractive way. This is how most classes allow programs, which can display things in various ways (console, GUI windows, log messages, remote call to another program, etc...), to format them in some readable way. 

There are multiple types of derived text output streams. This allows you to dump the formatted information to various targets, such as the console, or to a window, or to a file, for instance. As long as your class can format itself to a TextOutStream, it will work (via polymorphism) with the various derived text streams. Generally, you would do this by deriving from MEng.Formattable, but that is not strictly required.

NOTE: Text output strreams are buffered for performance reasons. I.e. they will buffer up a certain amount of bytes and then write a whole block of bytes at a time to the actual target. So you must flush them in order to get all the data out to the target. If you just write a string to, say, an console output stream, it won't show up until you flush it. And be particularly careful to flush them before closing. They don't automatically flush upon closing them, since you might be exiting out of some error situation and trying to flush would cause a nested error that you couldn't recover from.

 

Nested Classes:

Enum=StreamJustify
        Left   : "Left";
        Right  : "Right";
        Center : "Center";
EndEnum;

This enumerated type is used to set the field justification on the stream. It interacts with the field width. If the field width is, for instance, set to 8 and you output a string of 4 characters, it will be justified in an 8 character field, justified as indicated by the SetJustify() method.

 

Constructors:

No constructors are exposed at the macro level. You cannot create a class of this type directly.

 

Final, Non-Const Methods:

DNewLn();

Outputs two new lines to the stream. This is just a convenience and performance tweak, since it could also be done by writing out two separate new lines. But doing two new lines, on the end of some line plus an empty line) is so common that it's worth having this method to do it.

Flush();

The output streams doing caching, meaning that, in order to vastly improve efficiency, they don't immediately send everything you write to them to whatever actual target they manage (console, file, etc...) Instead, they will store up data in a cache until that cache gets full, or you flush the stream. This is somewhat of a pain, but it is necessary for good performance, since a single line of output might be made up by many calls to format small amounts of information. Doing a full flush of each of those calls all the way to the target would be very piggy.

FmtBool([In] MEng.Boolean ToFmt);
FmtCard1([In] MEng.Card1 ToFmt);
FmtCard1R([In] MEng.Card1 ToFmt, [In] Radices Radix);
FmtCard2([In] MEng.Card2 ToFmt);
FmtCard2R([In] MEng.Card2 ToFmt, [In] Radices Radix);
FmtCard4([In] MEng.Card4 ToFmt);
FmtCard4R([In] MEng.Card4 ToFmt, [In] Radices Radix);
FmtChar([In] MEng.Char ToFmt);
FmtFloat4([In] MEng.Float4 ToFmt);
FmtFloat8([In] MEng.Float8 ToFmt);
FmtInt1([In] MEng.Int1 ToFmt);
FmtInt1R([In] MEng.Int1 ToFmt, [In] Radices Radix);
FmtInt2([In] MEng.Int2 ToFmt);
FmtInt2R([In] MEng.Int2 ToFmt, [In] Radices Radix);
FmtInt4([In] MEng.Int4 ToFmt);
FmtInt4R([In] MEng.Int4 ToFmt, [In] Radices Radix);
FmtStr([In] MEng.String ToFmt);

These methods will format out a value of each of the intrinsic classes. These are the workhorse methods of this class which do most of the work. Note that these are more efficient than the generic (polymorphic) Format() method below, though the two will achieve the same effect. So use these when you know the type of the value you are formatting.

There are 'R' versions of the cardinal and integral versions, which allow you to indicate a radix to use for display. The other versions assume a decimal radix.

FmtCurLine();

Formats out the current line within the current class. This is mostly used for debugging and in tests, where you want to report in the formatted output what line within a class that the output came from. Another way to do this would be FmtCard4($CurLine) which uses the magic $CurLine value that represents the current line with the current class as an MEng.Card4 value.

Format([In] MEng.Formattable ToFmt);

This method allows any object that is derived from the formattable class to be formatted to a stream. Since all of the intrinsic types derive from the formattable classes, you can use this in place of the FmtXXX() methods above. However, those are more efficient because they are dedicated to their particular data types, whereas this call depends on polymorphism. But for other classes, you would use this method to format them out to a text stream.

NewLn();

Outputs a single new line to the stream. It is commonly used at the end of a line out of output to start a new line. You can also put a "\n" at the end of a text string, but often the last thing formatted on a line isn't a text string, so you need some way to generate a new line.

SetJustify([In] StreamJustify ToSet);

Sets the justification for the stream. The justification enumeration is a nested type of this class, documented above on this page. When the value formatted is smaller than the set field width, see SetWidth() below, then it will be justified within the field according to the justification set. It is left justified by default.

SeekToEnd();

Moves the output position to the end of the current content. For some types of output streams, this will have no real meaning since they are always 'at the end', so to speak. For those that it does have meaning, this will move the output position such that subsequent output will go at the end.

SetWidth([In] MEng.Card4 ToSet);

Sets the field width for the stream. When a non-zero field width is set, if any value formatted to the stream is less than width characters wide, it will be justified within a field of this width.