Vault  4.1
Public Types | Public Member Functions
VTextIOStream Class Reference

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

#include <vtextiostream.h>

Inheritance diagram for VTextIOStream:
VIOStream

List of all members.

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:
rawStreamthe raw stream on which I/O will be performed
lineEndingsWriteKindthe 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:
sa VString to format
includeLineEndingtrue 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:
sa VString to append to
includeLineEndingstrue 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:
linesa 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:
sthe 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:
sthe 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:
kindone 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:

Copyright ©1997-2014 Trygve Isaacson. All rights reserved. This documentation was generated with Doxygen.