IO namespace

The IO namespace contains classes used to work with file input/output. The IStream interfaces defines the methods needed to read/write a file (not all IStreams support reading/writing). Then there are specific implementations, the most notable of which are:

The IO namespace itself also contains several methods for reading/writing specific types of data, for example IO::ReadInt32(), IO::WriteUInt(),...

There's also a class called XmlWriter which can be used to easily write simple files in the XML format.

Classes

class EAIOZoneObject
A class derived from EAIOZoneObject is able to be allocated from different heaps without the owner of the object needing to know or care which heap the object came from or even what kind of allocator the object is using.
class FileStream
class FixedMemoryStream
Implements an memory-based stream that supports the IStream interface.
class IStream
class MemoryStream
Implements an memory-based stream that supports the IStream interface.
class SharedPointer
Implements a basic ref-counted pointer.
class StreamBuffer
Implements a smart buffer around a random-access stream.
class StreamChild
Implements a fixed-size read-only stream which is a 'child' of a parent stream.
class StreamNull
Implements a 'bit bucket' stream, whereby all writes to the stream succeed but do nothing and all reads from the stream succeed but write nothing to the user-supplied buffer.
class XmlWriter
A simple class that can be used to easily write XML files.

Enums

enum class FileError: uint32_t { Success = 0, InvalidHandle = 0xFFFFFFFE, OutOfMemory = 0xCFDE0002, FileNotFound = 0xCFDE0004, PathNotFound = 0xCFDE0005, AccessDenied = 0xCFDE0006, CurrentDirectory = 0xCFDE0008, WriteProtect = 0xCFDE0007, NotReady = 0xCFDE000B, CRC = 0xCFDE000C, Other = 0xCFDE000D }
enum AccessFlags { kAccessFlagNone = 0x00, kAccessFlagRead = 0x01, kAccessFlagWrite = 0x02, kAccessFlagReadWrite = 0x03 }
Defines stream access flags, much like file access flags.
enum CD { kCDCreateNew = 1, kCDCreateAlways = 2, kCDOpenExisting = 3, kCDOpenAlways = 4, kCDTruncateExisting = 5, kCDDefault = 6 }
Creation disposition. Specifies aspects of how to create or not create a file during opening of it.
enum PositionType { kPositionTypeBegin = 0, kPositionTypeCurrent = 1, kPositionTypeEnd = 2 }
Defines the positional basis for a user GetPosition or SetPosition action.
enum LineEnd { kLineEndNone = 0, kLineEndAuto = 1, kLineEndNewline = 2, kLineEndUnix = 2, kLineEndWindows = 3 }
Defines textual line ending property types.
enum Share { kShareNone = 0x00, kShareRead = 0x01, kShareWrite = 0x02, kShareDelete = 0x04 }
enum UsageHints { kUsageHintNone = 0x00, kUsageHintSequential = 0x01, kUsageHintRandom = 0x02 }
enum State { kStateSuccess = 0, kStateError = -1, kStateNotOpen = -2 }
Defines state values or function return values.
enum Endian { kEndianBig = 0, kEndianLittle = 1, kEndianLocal = kEndianLittle }
Defines endian-ness. This is appropriate for working with binary numerical data.

Typedefs

using size_type = size_t

Functions

auto GetAllocator() -> ICoreAllocator*
auto Addresses(EAIOZoneObject) -> namespace
auto Addresses(FileStream) -> namespace
auto ReadBool8(IStream* pIS, bool& value) -> bool
Reads a single boolean value from the stream.
auto ReadInt8(IStream* pIS, int8_t* value, size_type count = 1) -> bool
Reads a single int8_t value or an array of int8_t from the stream.
auto ReadUInt8(IStream* pIS, uint8_t* value, size_type count = 1) -> bool
Reads a single uint8_t value or an array of uint8_t from the stream.
auto ReadInt16(IStream* pIS, int16_t* value, size_type count = 1, Endian endianSource = kEndianBig) -> bool
Reads a single int16_t value or an array of int16_t from the stream.
auto ReadUInt16(IStream* pIS, uint16_t* value, size_type count = 1, Endian endianSource = kEndianBig) -> bool
Reads a single uint16_t value or an array of uint16_t from the stream.
auto ReadInt32(IStream* pIS, int32_t* value, size_type count = 1, Endian endianSource = kEndianBig) -> bool
Reads a single int32_t value or an array of int32_t from the stream.
auto ReadUInt32(IStream* pIS, uint32_t* value, size_type count = 1, Endian endianSource = kEndianBig) -> bool
Reads a single uint32_t value or an array of uint32_t from the stream.
auto ReadFloat(IStream* pIS, float* value, size_type count = 1, Endian endianSource = kEndianBig) -> bool
Reads a single float value or an array of float from the stream.
auto ReadResourceID(IStream* pIS, ResourceID* value, size_type count = 1, Endian endianSource = kEndianBig) -> bool
Reads a single ResourceID value or an array of ResourceID from the stream.
auto ReadCString(IStream* pIS, eastl::string8& str) -> IStream*
Reads a null-terminated string from the source IStream This will read bytes until a \x00 byte is found.
auto ReadLine(IStream* pIS, char* pLine, size_type nLineCapacity) -> size_type
Reads a line of text from the source IStream.
auto WriteBool8(IStream* pOS, const bool* value) -> bool
Writes a boolean value to the output stream.
auto WriteInt8(IStream* pOS, const int8_t* value, size_type count = 1) -> bool
Writes a single int8_t value or an array of int8_t numerical values to the output stream.
auto WriteUInt8(IStream* pOS, const uint8_t* value, size_type count = 1) -> bool
Writes a single uint8_t value or an array of uint8_t numerical values to the output stream.
auto WriteInt16(IStream* pOS, const int16_t* value, size_type count = 1, Endian endianDestination = kEndianBig) -> bool
Writes a single int16_t value or an array of int16_t numerical values to the output stream with the given destination endian-ness.
auto WriteUInt16(IStream* pOS, const uint16_t* value, size_type count = 1, Endian endianDestination = kEndianBig) -> bool
Writes a single uint16_t value or an array of uint16_t numerical values to the output stream with the given destination endian-ness.
auto WriteInt32(IStream* pOS, const int32_t* src, size_type count = 1, Endian endianDestination = kEndianBig) -> bool
WriteInt32.
auto WriteUInt32(IStream* pOS, const uint32_t* value, size_type count = 1, Endian endianDestination = kEndianBig) -> bool
Writes a single uint32_t value or an array of uint32_t numerical values to the output stream with the given destination endian-ness.
auto WriteFloat(IStream* pOS, const float* value, size_type count = 1, Endian endianDestination = kEndianBig) -> bool
Writes a single float value or an array of float numerical values to the output stream with the given destination endian-ness.
auto WriteResourceID(IStream* pOS, const ResourceID* value, size_type count = 1, Endian endianDestination = kEndianBig) -> bool
Writes a single ResourceID value or an array of ResourceID values to the output stream with the given destination endian-ness.
void WriteCString(IStream* pOS, eastl::string8& str)
Reads a null-terminated string from the source IStream This will read bytes until a \x00 byte is found.
auto WriteLine(IStream* pOS, const char8_t* pLineSource, size_type nLineLength, LineEnd lineEndToUse = kLineEndAuto) -> bool
Writes a line of text to a destination IStream.
auto Addresses(StreamBuffer) -> namespace
auto Addresses(StreamChild) -> namespace
auto Addresses(FixedMemoryStream) -> namespace
auto Addresses(MemoryStream) -> namespace
auto Addresses(StreamNull) -> namespace
auto Addresses(XmlWriter) -> namespace

Variables

const int kMaxPathLength
const size_type kSizeTypeError
Used to designate an error condition for many functions that return size_type.
const size_type kSizeTypeDone
Used to designate the condition whereby a requested operation is complete and no more processing can be done.
const size_t kLengthNull
Defines a value to be used for string conversion functions which means that the string length is specified by a wherever the terminating null character is.

Enum documentation

enum class IO::FileError: uint32_t

enum IO::AccessFlags

Defines stream access flags, much like file access flags.

Enumerators
kAccessFlagNone

kAccessFlagRead

No specified flags. Also used to indicate that a given IO stream is closed.

kAccessFlagWrite

Used for identifying read access to an entity.

kAccessFlagReadWrite

Used for identifying write access to an entity.

enum IO::CD

Creation disposition. Specifies aspects of how to create or not create a file during opening of it.

Enumerators
kCDCreateNew

kCDCreateAlways

Fails if file already exists.

kCDOpenExisting

Never fails, always opens or creates and truncates to 0.

kCDOpenAlways

Fails if file doesn't exist, keeps contents.

kCDTruncateExisting

Never fails, creates if doesn't exist, keeps contents.

kCDDefault

Fails if file doesn't exist, but truncates to 0 if it does.

enum IO::PositionType

Defines the positional basis for a user GetPosition or SetPosition action.

Enumerators
kPositionTypeBegin

kPositionTypeCurrent

For GetPosition refers to absolute index of next byte to read; always positive. For SetPosition, refers to absolute index of next byte to be written; always positive.

kPositionTypeEnd

For GetPosition always returns zero. For SetPosition, refers to position relative to current position; can be positive or negative.

enum IO::LineEnd

Defines textual line ending property types.

Enumerators
kLineEndNone

kLineEndAuto

Refers to no line termination. When writing, it means to append nothing.

kLineEndNewline

Refers to automatic line termination. When writing, it means to append kLineTerminationNewline if there isn't one already.

kLineEndUnix

Refers to "\n" line termination. When writing, it means to append a newline always.

kLineEndWindows

Same as kLineEndNewline.

enum IO::Share

Enumerators
kShareNone

kShareRead

No sharing.

kShareWrite

Allow sharing for reading.

kShareDelete

Allow sharing for writing.

enum IO::UsageHints

enum IO::State

Defines state values or function return values.

Zero means success and non-zero means failure in general. Note that various stream types may define their own errors in addition to these generic errors.

enum IO::Endian

Defines endian-ness. This is appropriate for working with binary numerical data.

Enumerators
kEndianBig

kEndianLittle

Big endian.

kEndianLocal

Little endian.

Typedef documentation

typedef size_t IO::size_type

Function documentation

namespace IO::Addresses(FileStream)

bool IO::ReadBool8(IStream* pIS, bool& value)

Reads a single boolean value from the stream.

Note that the to be portable, the stream implments booleans as int8_t and not bool. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error.

bool IO::ReadInt8(IStream* pIS, int8_t* value, size_type count = 1)

Reads a single int8_t value or an array of int8_t from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1.

bool IO::ReadUInt8(IStream* pIS, uint8_t* value, size_type count = 1)

Reads a single uint8_t value or an array of uint8_t from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1.

bool IO::ReadInt16(IStream* pIS, int16_t* value, size_type count = 1, Endian endianSource = kEndianBig)

Reads a single int16_t value or an array of int16_t from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::ReadUInt16(IStream* pIS, uint16_t* value, size_type count = 1, Endian endianSource = kEndianBig)

Reads a single uint16_t value or an array of uint16_t from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::ReadInt32(IStream* pIS, int32_t* value, size_type count = 1, Endian endianSource = kEndianBig)

Reads a single int32_t value or an array of int32_t from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::ReadUInt32(IStream* pIS, uint32_t* value, size_type count = 1, Endian endianSource = kEndianBig)

Reads a single uint32_t value or an array of uint32_t from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::ReadFloat(IStream* pIS, float* value, size_type count = 1, Endian endianSource = kEndianBig)

Reads a single float value or an array of float from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::ReadResourceID(IStream* pIS, ResourceID* value, size_type count = 1, Endian endianSource = kEndianBig)

Reads a single ResourceID value or an array of ResourceID from the stream.

Input 'endianSource' refers to the endian-ness of the values in the stream. Upon return the output value will be in local (a.k.a. native) endian-ness. The return value is true if the value could be entirely read. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

IStream* IO::ReadCString(IStream* pIS, eastl::string8& str)

Reads a null-terminated string from the source IStream This will read bytes until a \x00 byte is found.

size_type IO::ReadLine(IStream* pIS, char* pLine, size_type nLineCapacity)

Reads a line of text from the source IStream.

A line is defined as a sequence ending with "\n" or "\r\n". A line may be empty, as would be the case with a "\n\n" sequence. The returned line does not end with line terminator characters. The returned line -does- end with a terminating zero.

The return value is the strlen (string length) of the expected line or kSizeTypeError upon error. A return value of kSizeTypeDone means there were no more lines to read. This is different from the return value of the IStream::Read function because of the possibility of empty lines. Note that the return value is the expected strlen, which may be >= the nLineCapacity. In any case, the returned line will always be nul-terminated if it has any capacity.

Upon return, the stream will be positioned at the beginning of the next line, even if input nLineCapacity was not enough to hold the entire line. The input nLineCapacity is max number of characters to write, including the terminating zero. The input pLine can be NULL, in which case it will not be written to and the return value will merely indicate its required size.

Example usage: char buffer[256]; size_type size; while((size = EA::IO::ReadLine(&fileStream, buffer, 256)) < kSizeTypeDone) // While there there were more lines... ; // do something

bool IO::WriteBool8(IStream* pOS, const bool* value)

Writes a boolean value to the output stream.

Since type 'bool' is not portable, this function converts the input to an int8_t and write that as 0 or 1. The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error.

bool IO::WriteInt8(IStream* pOS, const int8_t* value, size_type count = 1)

Writes a single int8_t value or an array of int8_t numerical values to the output stream.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1.

bool IO::WriteUInt8(IStream* pOS, const uint8_t* value, size_type count = 1)

Writes a single uint8_t value or an array of uint8_t numerical values to the output stream.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1.

bool IO::WriteInt16(IStream* pOS, const int16_t* value, size_type count = 1, Endian endianDestination = kEndianBig)

Writes a single int16_t value or an array of int16_t numerical values to the output stream with the given destination endian-ness.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::WriteUInt16(IStream* pOS, const uint16_t* value, size_type count = 1, Endian endianDestination = kEndianBig)

Writes a single uint16_t value or an array of uint16_t numerical values to the output stream with the given destination endian-ness.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::WriteInt32(IStream* pOS, const int32_t* src, size_type count = 1, Endian endianDestination = kEndianBig)

WriteInt32.

Writes a single int32_t value or an array of int32_t numerical values to the output stream with the given destination endian-ness. The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::WriteUInt32(IStream* pOS, const uint32_t* value, size_type count = 1, Endian endianDestination = kEndianBig)

Writes a single uint32_t value or an array of uint32_t numerical values to the output stream with the given destination endian-ness.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::WriteFloat(IStream* pOS, const float* value, size_type count = 1, Endian endianDestination = kEndianBig)

Writes a single float value or an array of float numerical values to the output stream with the given destination endian-ness.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

bool IO::WriteResourceID(IStream* pOS, const ResourceID* value, size_type count = 1, Endian endianDestination = kEndianBig)

Writes a single ResourceID value or an array of ResourceID values to the output stream with the given destination endian-ness.

The return value is true if the value could be successfully completely written. If false, you can use IStream::GetState to determine the error. The default number of values is 1, and the default endian-ness is kEndianBig.

void IO::WriteCString(IStream* pOS, eastl::string8& str)

Reads a null-terminated string from the source IStream This will read bytes until a \x00 byte is found.

bool IO::WriteLine(IStream* pOS, const char8_t* pLineSource, size_type nLineLength, LineEnd lineEndToUse = kLineEndAuto)

Writes a line of text to a destination IStream.

The source line is not expected to end in a line delimiter (e.g. '
'); a appropriate line delimiter (defined by the lineEndToUse parameter) will be written to the stream by this function. The source line is not expected to end with a nul-terminator; if it has such a terminator, the nSourceLineLength value should not include that terminator.

If input nLineLength is kLengthNull, then the line is expected to be nul-terminated and the length written is the strlen of pSourceLine. The pLineSource value must be non-NULL unless nLineLength is zero.

The return value is true if the line could be successfully completely written. If false, you can use IStream::GetState to determine the error, as this function generates no errors beyond those related to IStream errors.

namespace IO::Addresses(StreamNull)

namespace IO::Addresses(XmlWriter)

Variable documentation

const int IO::kMaxPathLength

const size_type IO::kSizeTypeError

Used to designate an error condition for many functions that return size_type.

const size_type IO::kSizeTypeDone

Used to designate the condition whereby a requested operation is complete and no more processing can be done.

Only applicable to functions that document the use of kSizeTypeDone.

const size_t IO::kLengthNull

Defines a value to be used for string conversion functions which means that the string length is specified by a wherever the terminating null character is.

For the copying or converting of strings, the terminating null character is also copied to the destination.