BufferedOutputRange is a performance enhancement over writing directly to an output stream. It holds a File open for write or an OutputRange. Ouput is accumulated in an internal buffer and written to the output stream as a block.
Writing to stdout is a key use case. BufferedOutputRange is often dramatically faster than writing to stdout directly. This is especially noticable for outputs with short lines, as it blocks many writes together in a single write.
The internal buffer is written to the output stream after flushSize has been reached. This is checked at newline boundaries, when appendln is called or when put is called with a single newline character. Other writes check maxSize, which is used to avoid runaway buffers.
This scheme only flushes the internal buffer, it does not flush the output stream. Use flush() to flush both the internal buffer and the output stream. Specify flushSize as BufferedOutputRangeDefaults.lineBufferedFlushSize in the constructor to get line buffering with immediate flushes to the output stream.
The output stream type must be provided as a template argument during construction. E.g.
auto bufferedOutput = BufferedOutputRange!(typeof(stdout))(stdout)
BufferedOutputRange has a put method allowing it to be used an output range. It has a number of other methods providing additional control.
The internal buffer is automatically flushed when the BufferedOutputRange goes out of scope.
Constructor. Takes the output stream, e.g. stdout. Optional arguments control buffering behavior, defaults normally suffice. The defaults are available from the BufferedOutputRangeDefault enum.
Alternate constuctor used to turn line-buffered mode on. Use Yes.lineBuffered to enable. Lines are flushed at newline boundaries when in line-buffered mode.
Appends data to the output buffer. The output buffer is flushed if the appended data ends in a newline and the output buffer has reached flushSize.
Appends data plus a newline to the output buffer. The output buffer is flushed if it has reached flushSize.
Writes the internal buffer to the output stream and flush the output stream.
joinAppend is an optimization of append(inputRange.joiner(delimiter). This form is quite a bit faster, 40%+ on some benchmarks.
The put method makes BufferOutputRange an OutputRange. It operates similarly to append.