nlib
nn::nlib::TextWriter Class Referencefinal

The class for writing text to streams. More...

#include "nn/nlib/TextWriter.h"

Public Member Functions

errno_t Init () noexcept
 Initializes the text writer. More...
 
errno_t Open (OutputStream *stream) noexcept
 Opens a text writer with a stream specified. More...
 
bool Write (wchar_t c) noexcept
 Writes one character to a stream. More...
 
bool Write (const wchar_t *str) noexcept
 Writes a text string to a stream. More...
 
bool Write (char c) noexcept
 Writes one character to a stream. More...
 
bool Write (const char *str) noexcept
 Writes a text string to a stream. More...
 
bool Write (nlib_utf16_t c) noexcept
 Writes one character to a stream. More...
 
bool Write (const nlib_utf16_t *str) noexcept
 Writes a text string to a stream. More...
 
bool Write (nlib_utf32_t c) noexcept
 Writes one character to a stream. More...
 
bool Write (const nlib_utf32_t *str) noexcept
 Writes a text string to a stream. More...
 
bool Flush () noexcept
 Flushes the text writer and the base stream. More...
 
bool Close () noexcept
 Closes the text writer. More...
 
errno_t GetErrorValue () const noexcept
 This function can get the cause of the error when writing has failed. More...
 
OutputStreamGetStream () noexcept
 Gets the stream for the text writer to write to. More...
 
bool WriteFormat (const wchar_t *fmt,...) noexcept
 Writes a formatted text string to a stream. More...
 
bool WriteFormat (const char *fmt,...) noexcept
 Writes a formatted text string to a stream. More...
 
void SetError (errno_t e) const noexcept
 Sets an error value. More...
 
 operator bool () const
 Returns true if no internal error has occurred.
 
Basic Member Functions
 TextWriter () noexcept
 Instantiates the object with default parameters (default constructor).
 
 ~TextWriter () noexcept
 Destructor. The stream is not closed.
 
TextWriterassign (TextWriter &rhs, move_tag)
 Assigns the object by using swap for a move.
 
 TextWriter (TextWriter &rhs, move_tag)
 Instantiates the object by using swap for a move.
 
 TextWriter (TextWriter &&rhs)
 Instantiates the object (move constructor). This function is useful when using C++11.
 
TextWriteroperator= (TextWriter &&rhs)
 Move assignment operator. This function is useful when using C++11.
 
void swap (TextWriter &rhs) noexcept
 Swaps the contents of an object.
 

Detailed Description

The class for writing text to streams.

Description
Outputs UTF-8 text strings to streams. A BOM is not attached.
Newline characters are processed as follows.
  • LF is output unmodified.
  • CR is output as LF.
  • CRLF is output as LF.
With surrogate pairs, if a high surrogate and a low surrogate are not paired, an EILSEQ error is generated,
// Converts a UTF-16/UTF-32 string to UTF-8 and writes it to the OutputStream object.
// Note that the actual encoding of the literal string differs depending on the environment.
const wchar_t str[] = L"wide \r\nstring";
MemoryOutputStream ostr(....);
if (nlib_is_error(w.Init(&ostr))) { ERROR; }
if (nlib_is_error(w.Write(str))) { ERROR; }
if (nlib_is_error(w.Close())) { ERROR; }
// the result is "wide \nstring"
// Writes the BOM.
w.Write(L'\xFEFF'); // Becomes a UTF-8 BOM.
Examples:
exi/serializer/serializer.cpp, exi/simple1/simple1.cpp, exi/simple2/simple2.cpp, exi/textparser/textparser.cpp, misc/writefile/writefile.cpp, msgpack/jsonrpc/jsonrpc.cpp, and msgpack/jsonrpc/server.cpp.

Definition at line 20 of file TextWriter.h.

Member Function Documentation

§ Close()

nn::nlib::TextWriter::Close ( )
noexcept

Closes the text writer.

Returns
Returns true when successful.
Description
Clears the reference to the base stream, closes the text writer, and detaches the base stream. The base stream is not closed by this operation.

§ Flush()

nn::nlib::TextWriter::Flush ( )
noexcept

Flushes the text writer and the base stream.

Returns
Returns true when successful.
Description
If this function has been called in the state where data has been written only for a high surrogate, writing of that high surrogate is put on hold.

§ GetErrorValue()

nn::nlib::TextWriter::GetErrorValue ( ) const
inlinenoexcept

This function can get the cause of the error when writing has failed.

Return values
0No error occurred.
EINVALInvalid argument.
EEXISTInitialized redundantly.
EBADFNo stream to write to.
EIOWriting to the stream has failed for some reason.
EILSEQTried to write an invalid character.
ENOMEMFailed to dynamically allocate memory.

Definition at line 37 of file TextWriter.h.

§ GetStream()

nn::nlib::TextWriter::GetStream ( )
inlinenoexcept

Gets the stream for the text writer to write to.

Returns
The pointer to the stream.

Definition at line 38 of file TextWriter.h.

§ Init()

nn::nlib::TextWriter::Init ( )
noexcept

Initializes the text writer.

Returns
Returns 0 if successful. Returns EALREADY if already initialized.
Examples:
msgpack/jsonrpc/jsonrpc.cpp, and msgpack/jsonrpc/server.cpp.

§ Open()

nn::nlib::TextWriter::Open ( OutputStream stream)
noexcept

Opens a text writer with a stream specified.

Parameters
[in]streamA stream.
Return values
0if successful.
EINVALif the stream is NULL.
EEXISTif already opened.
Examples:
msgpack/jsonrpc/jsonrpc.cpp, and msgpack/jsonrpc/server.cpp.

§ SetError()

nn::nlib::TextWriter::SetError ( errno_t  e) const
inlinenoexcept

Sets an error value.

Parameters
[in]eAn error value.
Description
If an error value has not been set, the one specified by e is set.

Definition at line 41 of file TextWriter.h.

§ Write() [1/8]

nn::nlib::TextWriter::Write ( wchar_t  c)
noexcept

Writes one character to a stream.

Parameters
[in]cA wide character (UTF-16 or UTF-32).
Returns
Returns true when successful.

§ Write() [2/8]

nn::nlib::TextWriter::Write ( const wchar_t *  str)
noexcept

Writes a text string to a stream.

Parameters
[in]strA wide text string.
Returns
Returns true when successful.

§ Write() [3/8]

nn::nlib::TextWriter::Write ( char  c)
noexcept

Writes one character to a stream.

Parameters
[in]cAn ASCII character.
Returns
Returns true when successful.
Description
To write a multibyte string, write the data as a string and not one character at a time. An error is generated (EILSEQ).

§ Write() [4/8]

nn::nlib::TextWriter::Write ( const char *  str)
noexcept

Writes a text string to a stream.

Parameters
[in]strA UTF-8 text string.
Returns
Returns true when successful.

§ Write() [5/8]

nn::nlib::TextWriter::Write ( nlib_utf16_t  c)
noexcept

Writes one character to a stream.

Parameters
[in]cA UTF-16 character.
Returns
Returns true when successful.
Description
If a high surrogate has been written, an error occurs if this is not followed by writing a low surrogate.

§ Write() [6/8]

nn::nlib::TextWriter::Write ( const nlib_utf16_t str)
noexcept

Writes a text string to a stream.

Parameters
[in]strUTF-16 string.
Returns
Returns true when successful.

§ Write() [7/8]

nn::nlib::TextWriter::Write ( nlib_utf32_t  c)
noexcept

Writes one character to a stream.

Parameters
[in]cA UTF-32 character.
Returns
Returns true when successful.

§ Write() [8/8]

nn::nlib::TextWriter::Write ( const nlib_utf32_t str)
noexcept

Writes a text string to a stream.

Parameters
[in]strUTF-32 string.
Returns
Returns true when successful.

§ WriteFormat() [1/2]

nn::nlib::TextWriter::WriteFormat ( const wchar_t *  fmt,
  ... 
)
noexcept

Writes a formatted text string to a stream.

Parameters
[in]fmtA formatted text string.
Returns
Returns true if it succeeds, and false if it fails.
Description
If the function returns false, you can use the GetErrorValue member function to get the cause of the error.
Examples:
msgpack/jsonrpc/jsonrpc.cpp, and msgpack/jsonrpc/server.cpp.

§ WriteFormat() [2/2]

nn::nlib::TextWriter::WriteFormat ( const char *  fmt,
  ... 
)
noexcept

Writes a formatted text string to a stream.

Parameters
[in]fmtA formatted text string.
Returns
Returns true if it succeeds, and false if it fails.
Description
If the function returns false, you can use the GetErrorValue member function to get the cause of the error.

The documentation for this class was generated from the following files: