IO namespace

Classes to work with file input/output, that is, reading and writing data into files.

The IO namespace contains classes used to work with file input/output.

The main concept of this namespace is that of "streams", which are objects where data can be read form/written into. It's abstract representation is IO::IStream, which defines all the operations you can do to a stream. There are several subclasses to it, depending on the type of stream: use IO::FileStream if you want to write a disk file. Before you can use a stream, you have to call IO::IStream::Open() with the appropriate parameters (it depends on whether you want to create a new file, read or write, etc). AFter you are finished writing, call IO::IStream::Close() so the system releases the stream resources.

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.

Namespaces

namespace Directory
namespace File

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 class AccessFlags: int { None = 0x00, Read = 0x01, Write = 0x02, ReadWrite = 0x03 }
Defines stream access flags, much like file access flags.
enum class CD: int { CreateNew = 1, CreateAlways = 2, OpenExisting = 3, OpenAlways = 4, TruncateExisting = 5, Default = 6 }
Creation disposition. Specifies aspects of how to create or not create a file during opening of it.
enum class PositionType: int { Begin = 0, Current = 1, End = 2 }
Defines the positional basis for a user GetPosition or SetPosition action.
enum class LineEnd: int { None = 0, Auto = 1, Newline = 2, Unix = 2, Windows = 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 class Endian: int { Big = 0, Little = 1, Local = Little }
Defines endian-ness. This is appropriate for working with binary numerical data.

Typedefs

using size_type = size_t

Functions

auto GetAllocator() -> ICoreAllocator*
auto EnsureTrailingPathSeparator(eastl::string16& path) -> bool
Ensures the given path finishes with a path separator ('/' or '\' depending on the OS), modifying it if necessary.
auto ConcatenatePathComponents(char16_t* dstPath, const char16_t* component1, const char16_t* component2) -> int
auto Addresses(File) -> namespace
auto Addresses(Directory) -> namespace
auto Addresses(EAIOZoneObject) -> namespace
ASSERT_SIZE(FileStream, 0x22C)
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 = Endian::Big) -> 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 = Endian::Big) -> 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 = Endian::Big) -> 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 = Endian::Big) -> 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 = Endian::Big) -> 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 = Endian::Big) -> 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 eastl::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 = Endian::Big) -> 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 = Endian::Big) -> 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 = Endian::Big) -> bool
WriteInt32.
auto WriteUInt32(IStream* pOS, const uint32_t* value, size_type count = 1, Endian endianDestination = Endian::Big) -> 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 = Endian::Big) -> 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 = Endian::Big) -> bool
Writes a single ResourceID value or an array of ResourceID values to the output stream with the given destination endian-ness.
auto WriteCString(IStream* pOS, eastl::string8& str) -> void
Reads a null-terminated eastl::string from the source IStream This will read bytes until a \x00 byte is found.
auto WriteLine(IStream* pOS, const char* pLineSource, size_type nLineLength, LineEnd lineEndToUse = LineEnd::Auto) -> bool
Writes a line of text to a destination IStream.
ASSERT_SIZE(StreamBuffer, 0x34)
auto Addresses(StreamBuffer) -> namespace
ASSERT_SIZE(StreamChild, 0x1C)
auto Addresses(StreamChild) -> namespace
ASSERT_SIZE(FixedMemoryStream, 0x18)
auto Addresses(FixedMemoryStream) -> namespace
ASSERT_SIZE(SharedPointer, 0x18)
ASSERT_SIZE(MemoryStream, 0x24)
auto Addresses(MemoryStream) -> namespace
ASSERT_SIZE(StreamNull, 0x8)
auto Addresses(StreamNull) -> namespace
ASSERT_SIZE(XmlWriter, 0x20)
auto Addresses(XmlWriter) -> namespace

Variables

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 eastl::string conversion functions which means that the eastl::string length is specified by a wherever the terminating null character is.
const int kMaxPathLength

Enum documentation

enum class IO::AccessFlags: int
#include <Spore ModAPI/Spore/IO/Constants.h>

Defines stream access flags, much like file access flags.

Enumerators
None

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

Used for identifying read access to an entity.
Write

Used for identifying write access to an entity.
ReadWrite

Used for identifying both read and write access to an entity.

enum class IO::CD: int
#include <Spore ModAPI/Spore/IO/Constants.h>

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

Enumerators
CreateNew

Fails if file already exists.
CreateAlways

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

Fails if file doesn't exist, keeps contents.
OpenAlways

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

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

Default (implementation-specific) disposition.

enum class IO::PositionType: int
#include <Spore ModAPI/Spore/IO/Constants.h>

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

Enumerators
Begin

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.
Current

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

For GetPosition returns to position relative to end (i.e. the negative of bytes left to read); always negative. For SetPosition, refers to position relative to end; can be positive or negative.

enum class IO::LineEnd: int
#include <Spore ModAPI/Spore/IO/Constants.h>

Defines textual line ending property types.

Enumerators
None

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

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

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

Same as Newline.
Windows

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

enum IO::Share
#include <Spore ModAPI/Spore/IO/Constants.h>

Enumerators
kShareNone

No sharing.
kShareRead

Allow sharing for reading.
kShareWrite

Allow sharing for writing.
kShareDelete

Allow sharing for deletion.

enum IO::State
#include <Spore ModAPI/Spore/IO/Constants.h>

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 class IO::Endian: int
#include <Spore ModAPI/Spore/IO/Constants.h>

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

Enumerators
Big

Big endian.
Little

Little endian.
Local

Whatever endian is native to the machine.

Typedef documentation

Function documentation

bool IO::EnsureTrailingPathSeparator(eastl::string16& path)
#include <Spore ModAPI/Spore/IO/Constants.h>

Ensures the given path finishes with a path separator ('/' or '\' depending on the OS), modifying it if necessary.

Parameters
path

bool IO::ReadBool8(IStream* pIS, bool& value)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::ReadUInt16(IStream* pIS, uint16_t* value, size_type count = 1, Endian endianSource = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::ReadInt32(IStream* pIS, int32_t* value, size_type count = 1, Endian endianSource = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::ReadUInt32(IStream* pIS, uint32_t* value, size_type count = 1, Endian endianSource = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::ReadFloat(IStream* pIS, float* value, size_type count = 1, Endian endianSource = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::ReadResourceID(IStream* pIS, ResourceID* value, size_type count = 1, Endian endianSource = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

IStream* IO::ReadCString(IStream* pIS, eastl::string8& str)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

Reads a null-terminated eastl::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)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 (eastl::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)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::WriteUInt16(IStream* pOS, const uint16_t* value, size_type count = 1, Endian endianDestination = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::WriteInt32(IStream* pOS, const int32_t* src, size_type count = 1, Endian endianDestination = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::WriteUInt32(IStream* pOS, const uint32_t* value, size_type count = 1, Endian endianDestination = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::WriteFloat(IStream* pOS, const float* value, size_type count = 1, Endian endianDestination = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

bool IO::WriteResourceID(IStream* pOS, const ResourceID* value, size_type count = 1, Endian endianDestination = Endian::Big)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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 Endian::Big.

void IO::WriteCString(IStream* pOS, eastl::string8& str)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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

bool IO::WriteLine(IStream* pOS, const char* pLineSource, size_type nLineLength, LineEnd lineEndToUse = LineEnd::Auto)
#include <Spore ModAPI/Spore/IO/StreamAdapter.h>

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.

Variable documentation

const size_type IO::kSizeTypeError
#include <Spore ModAPI/Spore/IO/Constants.h>

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

const size_type IO::kSizeTypeDone
#include <Spore ModAPI/Spore/IO/Constants.h>

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
#include <Spore ModAPI/Spore/IO/Constants.h>

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

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