VTextIOStream is a concrete VIOStream subclass that provides text line-oriented stream i/o. More...

#include <vtextiostream.h>

Inheritance diagram for VTextIOStream:

Public Types
enum	{ kLineEndingsUnknown, kLineEndingsUnix, kLineEndingsDOS, kLineEndingsMac, kLineEndingsMixed, kNumLineEndingsReadKinds }
	Values for mLineEndingsReadKind, set as we read the stream and figure out what its format is. More...
enum	{ kUseUnixLineEndings, kUseDOSLineEndings, kUseMacLineEndings, kUseSuppliedLineEndings, kUseNativeLineEndings, kNumLineEndingsWriteKinds }
	Values for mLineEndingsWriteKind, which the caller tells us to use as we write to the stream. More...
Public Member Functions
	VTextIOStream (VStream &rawStream, int lineEndingsWriteKind=kUseNativeLineEndings)
	Constructs the object with an underlying raw stream and the kind of line endings to use during write.
virtual	~VTextIOStream ()
	Destructor.
void	readLine (VString &s, bool includeLineEnding=false)
	Reads the next line of text from the stream.
VCodePoint	readUTF8CodePoint ()
	Reads the next code point (1 to 4 bytes) from the stream, even if it is part of a line ending.
VChar	readCharacterByte ()
	Reads the next byte from the stream and returns a VChar to wrap it.
void	readAll (VString &s, bool includeLineEndings=true)
	Primarily useful for reading from an underlying file stream, reads until eof is encountered, and returns the entire stream as a single string, by reading every line and appending it to the supplied string.
void	readAll (VStringVector &lines)
	This convenience function is like the other readAll, but it returns the stream's contents as a vector of strings rather than a single giant string.
void	writeLine (const VString &s)
	This method is equivalent to writeString(s) + writeLineEnd().
void	writeString (const VString &s)
	Writes a string of text to the stream, WITHOUT line ending character(s).
void	writeLineEnd ()
	Writes just the line ending character(s).
int	getLineEndingsReadKind () const
	Returns the mLineEndingsReadKind property, describing the kind of line endings that the file has encountered while reading from the stream.
int	getLineEndingsReadKindForWrite () const
	Returns the mLineEndingsReadKind property, converted to a value suitable for supplying as the mLineEndingsWriteKind value for an output stream.
int	getLineEndingsWriteKind () const
	Returns the mLineEndingsWriteKind property, describing the kind of line endings that this object has been set up to write to the stream.
void	setLineEndingsKind (int kind)
	Sets the mLineEndingsWriteKind property, which determines what the writeLine method behavior is with regard to writing the line ending character(s) at the end of each line written to the stream.

Detailed Description

VTextIOStream is a concrete VIOStream subclass that provides text line-oriented stream i/o.

You can specify a line ending mode when writing, or request to use the native mode for the platform the code is running on.

You can find out what the line ending mode is when reading, in case you need to tell the user (imagine implementing a line ending selection the way the CodeWarrior IDE does).

Definition at line 31 of file vtextiostream.h.

Member Enumeration Documentation

anonymous enum

Values for mLineEndingsReadKind, set as we read the stream and figure out what its format is.

Enumerator:

kLineEndingsUnknown	Indicates that we have not yet read a line ending.
kLineEndingsUnix	Indicates that we have only seen Unix line endings (0x0A).
kLineEndingsDOS	Indicates that we have only seen DOS line endings (0x0D0A).
kLineEndingsMac	Indicates that we have only seen Mac line endings (0x0D).
kLineEndingsMixed	Indicates that we have seen a mixture of line ending types.

Definition at line 35 of file vtextiostream.h.

anonymous enum

Values for mLineEndingsWriteKind, which the caller tells us to use as we write to the stream.

Enumerator:

kUseUnixLineEndings	Indicates that we are writing Unix line endings (0x0A).
kUseDOSLineEndings	Indicates that we are writing DOS line endings (0x0D0A).
kUseMacLineEndings	Indicates that we are writing Mac line endings (0x0D).
kUseSuppliedLineEndings	Indicates that the caller is giving us the line endings, so we don't actually write them.
kUseNativeLineEndings	Indicates that we are writing line endings native to the OS we are compiled for.

Definition at line 46 of file vtextiostream.h.

Constructor & Destructor Documentation

VTextIOStream::VTextIOStream	(	VStream &	rawStream,
		int	lineEndingsWriteKind = `kUseNativeLineEndings`
	)

Constructs the object with an underlying raw stream and the kind of line endings to use during write.

Parameters:

rawStream	the raw stream on which I/O will be performed
lineEndingsWriteKind	the kind of line endings to write

Definition at line 16 of file vtextiostream.cpp.

References VString::preflight(), and setLineEndingsKind().

Member Function Documentation

void VTextIOStream::readLine	(	VString &	s,
		bool	includeLineEnding = `false`
	)

Reads the next line of text from the stream.

Throws a VException if EOF is encountered. Sets the mLineEndingsReadKind property depending on the line ending characters encountered.

Parameters:

s	a VString to format
includeLineEnding	true if you want the line ending character(s) to be included in the string that is returned

Definition at line 31 of file vtextiostream.cpp.

References VIOStream::available(), VString::EMPTY(), VCodePoint::getUTF8Length(), VCodePoint::isNotNull(), kLineEndingsDOS, kLineEndingsMac, and kLineEndingsUnix.

VCodePoint VTextIOStream::readUTF8CodePoint ( )

Reads the next code point (1 to 4 bytes) from the stream, even if it is part of a line ending.

Throws a VException if EOF is encountered. You probably don't want to mix use of readLine and readCharacter in the same input stream, unless you are prepared to deal with line ending characters being read by readUTF8CodePoint, and the result that calls to readLine will not see those characters and be able to set the mLineEndingsReadKind property except for the line endings that it does see.

Returns:: the next code point

Definition at line 121 of file vtextiostream.cpp.

VChar VTextIOStream::readCharacterByte ( )

Reads the next byte from the stream and returns a VChar to wrap it.

Note that this is not UTF-8 compatible and should only be used on single-byte streams where you interpret chars out of the 0-127 ASCII range correctly according to some code page that is implicit in the stream context. Generally you should avoid this approach to text streams and use UTF-8 instead, but you may have specific streams (e.g. a file in some particular format) where this is necessary.

Returns:: the next single byte char

Definition at line 126 of file vtextiostream.cpp.

References VIOStream::readGuaranteed().

void VTextIOStream::readAll	(	VString &	s,
		bool	includeLineEndings = `true`
	)

Primarily useful for reading from an underlying file stream, reads until eof is encountered, and returns the entire stream as a single string, by reading every line and appending it to the supplied string.

Note that the default value for includeLineEndings is the opposite of VTextIOStream::readLine(), because here you probably want the whole file with lines separated, whereas when you read one line you probably don't want the end of line characters.

Parameters:

s	a VString to append to
includeLineEndings	true if you want the line ending character(s) to be included in the string that is returned

Definition at line 134 of file vtextiostream.cpp.

References readLine().

void VTextIOStream::readAll ( VStringVector & lines )

This convenience function is like the other readAll, but it returns the stream's contents as a vector of strings rather than a single giant string.

The lines do not have line ending characters at the end.

Parameters:

lines a vector of strings; lines are appended to this vector

Definition at line 144 of file vtextiostream.cpp.

References readLine().

void VTextIOStream::writeLine ( const VString & s )

This method is equivalent to writeString(s) + writeLineEnd().

Writes a line of text to the stream, with line ending character(s). If the mLineEndingsWriteKind property is kUseSuppliedLineEndings, then it assumed that you are supplying a string that has the line ending character(s) in it, and the method will not write them itself; otherwise, it writes them.

Parameters:

s	the line of text to write

Definition at line 154 of file vtextiostream.cpp.

References writeLineEnd(), and writeString().

void VTextIOStream::writeString ( const VString & s )

Writes a string of text to the stream, WITHOUT line ending character(s).

Parameters:

s	the string of text to write

Definition at line 159 of file vtextiostream.cpp.

References VString::getDataBufferConst(), VString::length(), and VIOStream::write().

void VTextIOStream::writeLineEnd ( )

Writes just the line ending character(s).

Does nothing if the mLineEndingsWriteKind property is kUseSuppliedLineEndings, because that means you supply the line endings in the strings you write.

Definition at line 163 of file vtextiostream.cpp.

References VIOStream::write().

int VTextIOStream::getLineEndingsReadKind ( ) const [inline]

Returns the mLineEndingsReadKind property, describing the kind of line endings that the file has encountered while reading from the stream.

Returns:: one of the mLineEndingsReadKind enum values

Definition at line 154 of file vtextiostream.h.

int VTextIOStream::getLineEndingsReadKindForWrite ( ) const

Returns the mLineEndingsReadKind property, converted to a value suitable for supplying as the mLineEndingsWriteKind value for an output stream.

Returns:: one of the mLineEndingsReadKind enum values

Definition at line 250 of file vtextiostream.cpp.

References kLineEndingsDOS, kLineEndingsMac, kLineEndingsUnix, kUseDOSLineEndings, kUseMacLineEndings, kUseNativeLineEndings, and kUseUnixLineEndings.

int VTextIOStream::getLineEndingsWriteKind ( ) const [inline]

Returns the mLineEndingsWriteKind property, describing the kind of line endings that this object has been set up to write to the stream.

Returns:: one of the mLineEndingsReadKind enum values

Definition at line 167 of file vtextiostream.h.

void VTextIOStream::setLineEndingsKind ( int kind )

Sets the mLineEndingsWriteKind property, which determines what the writeLine method behavior is with regard to writing the line ending character(s) at the end of each line written to the stream.

Parameters:

kind	one of the mLineEndingsWriteKind enum values

Definition at line 271 of file vtextiostream.cpp.

References kUseDOSLineEndings, kUseMacLineEndings, kUseNativeLineEndings, kUseSuppliedLineEndings, and kUseUnixLineEndings.

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

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation