#include <evo/file.h>

Inheritance diagram for File:

[legend]

Detailed Description

File I/O stream.

Use to read and write files
This is a Stream (read/write) using I/O device IoFile
This throws an ExceptionStream on error if exceptions are enabled, otherwise use error() to check for error
See also: Directory, FilePath

Methods

File:
- open()
  - isopen()
- close()
- seek()
- pos()
Data:
- readline(), readtext(), readbin()
  - bufread()
- writeline(), writetext(), writebin()
Error handling:

Example

#include <evo/io.h>
#include <evo/file.h>
using namespace evo;
static Console& c = con();
int main() {
    const char* filename = "tmpfile.txt";
    // Write new file
    {
        File file(filename, oWRITE_NEW);
        file << "line one" << NL;
        file << "line " << 2 << NL;
        file << "line three" << NL;
    }
    // Read and print file
    {
        File file(filename);
        for (String line; file.readline(line); )
            c.out << "> " << line << NL;
    }
    return 0;
}

Public Types
typedef Stream< IoFile >	Base
	Base class alias. More...

typedef IoFile ::ExceptionInT	ExceptionInT
	Stream input exception type More...

typedef IoFile ::ExceptionOutT	ExceptionOutT
	Stream output exception type More...

typedef StreamFormatter< This >	Format
	Stream output formatter with state. More...

typedef IoFile ::Handle	Handle
	Low-level handle type (OS dependent) More...

typedef This	Out
	Type returned by write_out() More...

typedef ulong	Size
	Data size type (ulong) More...

typedef Stream< IoFile >	This
	This stream type. More...

Public Member Functions
	File (Newline nl=NL_SYS, bool exceptions=1)
	Constructor. More...

	File (const char *path, Open mode=oREAD, bool flushlines=false, Newline nl=NL_SYS, bool exceptions=1)
	Constructor to open file. More...

	File (const char *path, Open mode, Newline nl, bool exceptions=1)
	Constructor to open file and set default newline. More...

void	attach (Open mode, Handle handle, bool owned=true, bool flushlines=false)
	Attach existing stream. More...

RawBuffer &	bufread ()
	Advanced: Access primary read buffer. More...

IoWriter &	bufwrite ()
	Advanced: Access primary write buffer. More...

bool	close ()
	Close stream. More...

Handle	detach ()
	Detach current stream. More...

Error	error () const
	Get error code from last operation. More...

bool	excep () const
	Get whether exceptions are enabled. More...

void	excep (bool val)
	Set whether exceptions are enabled. More...

bool	flush ()
	Flush any pending output in stream write buffer, if buffered. More...

Handle	handle () const
	Get stream handle for low-level calls. More...

bool	isopen () const
	Get whether stream is open. More...

bool	open (const char *path, Open mode=oREAD, bool flushlines=false)
	Open file for read and/or writing. More...

	operator SafeBoolType () const
	Safe (explicit) evaluation as bool type. More...

bool	operator! () const
	Negation operator checks whether an error was set by a previous operation. More...

This &	operator<< (This &)
	No-op used by formatting helpers. More...

This &	operator<< (Newline nl)
	Write an explicit newline and flush stream. More...

This &	operator<< (NewlineDefault nl)
	Write default newline and flush stream. More...

This &	operator<< (const NewlineValue &nl)
	Write newline value and flush stream. More...

This &	operator<< (Flush)
	Flush buffer by writing to stream. More...

This &	operator<< (bool val)
	Append a bool value to stream. More...

This &	operator<< (char ch)
	Write character to stream. More...

This &	operator<< (const char *str)
	Write terminated string to stream. More...

This &	operator<< (const SubString &str)
	Write substring to stream. More...

This &	operator<< (const ListBase< char, TSize > &str)
	Write substring to stream. More...

This &	operator<< (int num)
	Write formatted number to stream. More...

This &	operator<< (long num)
	Write formatted number to stream. More...

This &	operator<< (longl num)
	Write formatted number to stream. More...

This &	operator<< (uint num)
	Write formatted number to stream. More...

This &	operator<< (ulong num)
	Write formatted number to stream. More...

This &	operator<< (ulongl num)
	Write formatted number to stream. More...

This &	operator<< (const IntegerT< U > &num)
	Write formatted class number to stream. More...

This &	operator<< (float num)
	Write formatted floating-point number to stream. More...

This &	operator<< (double num)
	Write formatted floating-point number to stream. More...

This &	operator<< (ldouble num)
	Write formatted floating-point number to stream. More...

This &	operator<< (const FloatT< U > &num)
	Write formatted class floating-point number to stream. More...

This &	operator<< (const FmtChar &fmt)
	Write repeated character to stream. More...

This &	operator<< (const FmtString &fmt)
	Write formatted string field to stream. More...

This &	operator<< (const FmtShort &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtInt &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtLong &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtLongL &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtUShort &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtUInt &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtULong &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtULongL &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtFloat &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtFloatD &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtFloatL &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtFieldNum< U > &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtFieldFloat< U > &fmt)
	Write formatted number field to stream. More...

This &	operator<< (const FmtPtr &fmtptr)
	Writer formatted pointer field to stream. More...

This &	operator<< (const FmtDump &fmt)
	Write formatted data dump to stream. More...

ulongl	pos ()
	Get current file position. More...

ulong	readbin (void *buf, ulong size)
	Read binary input from stream. More...

bool	readline (String &str, ulong maxlen=0)
	Read text line input from stream. More...

ulong	readtext (char *buf, ulong size)
	Read text input from stream. More...

ulongl	seek (ulongl offset, Seek start=sBegin)
	Seek to file position. More...

char *	write_direct (Size size)
	Get pointer for writing directly to buffer to append data. More...

bool	write_direct_finish (Size size)
	Finish writing directly to buffer. More...

char *	write_direct_flush (Size &available, Size written_size, Size reserve_size)

char *	write_direct_multi (Size &available, Size reserve_size)

Out &	write_out ()

ulong	writebin (const void *buf, ulong size)
	Write binary output to stream. More...

ulong	writechar (char ch, ulong count=1)
	Write repeat character as text output to stream. More...

bool	writefmtchar (char ch, ulong count, const FmtSetField &field)
	Write formatted and/or repeated character. More...

bool	writefmtdump (const FmtDump &fmt)
	Write formatted data dump. More...

bool	writefmtdump (const FmtDump &fmt, Newline nl)
	Write formatted data dump with explicit newline type. More...

bool	writefmtnum (TNum num, const FmtSetInt &fmt, const FmtSetField *field=NULL)
	Write formatted signed number with field alignment. More...

bool	writefmtnumf (TNum num, const FmtSetFloat &fmt, const FmtSetField *field=NULL)
	Write formatted floating point number with field alignment. More...

bool	writefmtnumu (TNum num, const FmtSetInt &fmt, const FmtSetField *field=NULL)
	Write formatted unsigned number with field alignment. More...

bool	writefmtstr (const char *buf, ulong size, const FmtSetField &field)
	Write text with field alignment. More...

ulong	writeline (const char *buf, ulong size)
	Write text line output to stream. More...

bool	writenum (TNum num, int base=fDEC)
	Write formatted signed number. More...

bool	writenumf (TNum num, int precision=fPREC_AUTO)
	Write formatted floating-point number. More...

bool	writenumu (TNum num, int base=fDEC)
	Write formatted unsigned number. More...

Size	writequoted (const char *buf, Size size, char delim, bool optional=false)
	Write quoted text output to string. More...

ulong	writetext (const char *buf, ulong size)
	Write text output to stream. More...

Protected Types
enum	RwLast
	Current read/write mode. More...

Protected Member Functions
void	init (Open mode, bool flushlines=false)
	Initialize and reset buffers for a new stream. More...

Protected Attributes
IoReader	bufrd_
	Buffered reader. More...

IoWriter	bufwr_
	Buffered writer. More...

IoFile	device_
	I/O device. More...

Error	error_
	Last error code. More...

bool	excep_
	Whether to throw exceptions. More...

bool	owned_
	Whether handle is owned (to be closed here) More...

RwLast	rwlast_
	Read/Write: Used to track last operation when switching between read/write. More...

ulongl	savepos_
	Read/Write: Used to save buffered read position when switching between read/write. More...

Member Typedef Documentation

◆ Base

typedef Stream<IoFile> Base

Base class alias.

◆ ExceptionInT

typedef IoFile ::ExceptionInT ExceptionInT

inherited

Stream input exception type

◆ ExceptionOutT

typedef IoFile ::ExceptionOutT ExceptionOutT

inherited

Stream output exception type

◆ Format

typedef StreamFormatter<This> Format

inherited

Stream output formatter with state.

This is associated with a Stream object and supports stateful (i.e. sticky) output formatting with "<<" operator on this object
- Use Stream::Format (where Stream is the stream type used)
Formatting attributes include:
- Aligned fields for formatting text "columns"
- Integer base, prefix, and padding (in addition to field padding)
- Floating point precision and padding (in additon to field padding)
- String to use for "null" values (null char*, String, Int, etc)
Note: Single character (char) and Newline (NL) values are not formatted as fields (i.e. not padded) since they're usually delimiters
See: Stream Formatting

Examples

Example using File:

#include <evo/io.h>
using namespace evo;
int main() {
    File file("file.txt", oWRITE_NEW);
    // Use a temporary formatter to write line: 7B,1C8
    File::Format(file) << fHEX << 123 << ',' << 456 << NL;
    // Create a formatter and use to write line: 001,002
    File::Format out(file);
    out << FmtSetInt(fDEC, 3) << 1 << ',' << 2 << NL;
    return 0;
}

Example using Console (stdout):

#include <evo/io.h>
using namespace evo;
int main() {
    Console& c = con();
    // Use a temporary formatter to write line: 7B,1C8
    Console::Format(c.out) << fHEX << 123 << ',' << 456 << NL;
    // Create a formatter and use to write line: 001,002
    Console::Format out(c.out);
    out << FmtSetInt(fDEC, 3) << 1 << ',' << 2 << NL;
    return 0;
}

For more examples see: Stream Formatting

◆ Handle

typedef IoFile ::Handle Handle

inherited

Low-level handle type (OS dependent)

◆ Out

typedef This Out

inherited

Type returned by write_out()

◆ Size

typedef ulong Size

inherited

Data size type (ulong)

◆ This

typedef Stream<IoFile > This

inherited

This stream type.

Member Enumeration Documentation

◆ RwLast

enum RwLast

protectedinherited

Current read/write mode.

Constructor & Destructor Documentation

◆ File() [1/3]

File	(	Newline	nl = `NL_SYS`,
		bool	exceptions = `1`
	)

inline

Constructor.

This initializes without opening a file, use open() to open a file

Parameters

nl	Default newline value to use for text reads/writes
exceptions	Whether to enable exceptions on error, default set by Evo config: EVO_EXCEPTIONS

◆ File() [2/3]

File	(	const char *	path,
		Open	mode = `oREAD`,
		bool	flushlines = `false`,
		Newline	nl = `NL_SYS`,
		bool	exceptions = `1`
	)

inline

Constructor to open file.

Throws ExceptionStreamOpen on error, if exceptions enabled
If exceptions disabled: Call error() to check for error

Parameters

path	File path to use
mode	Access mode to use
flushlines	Whether to flush text output on newlines (line buffering)
nl	Default newline value to use for text reads/writes
exceptions	Whether to enable exceptions on error, default set by Evo config: EVO_EXCEPTIONS

◆ File() [3/3]

File	(	const char *	path,
		Open	mode,
		Newline	nl,
		bool	exceptions = `1`
	)

inline

Constructor to open file and set default newline.

Throws ExceptionStreamOpen on error, if exceptions enabled
If exceptions disabled: Call error() to check for error

Parameters

path	File path to use
mode	Access mode to use
nl	Default newline value to use for text reads/writes
exceptions	Whether to enable exceptions on error, default set by Evo config: EVO_EXCEPTIONS

Member Function Documentation

◆ attach()

void attach	(	Open	mode,
		Handle	handle,
		bool	owned = `true`,
		bool	flushlines = `false`
	)

inlineinherited

Attach existing stream.

Parameters

mode	Access mode to use (oREAD, oREAD_WRITE, or oWRITE), must be correct for handle
handle	Handle to attach, must be valid
owned	Whether to take ownership and close handle, false detaches on close()
flushlines	Whether to flush text output on newlines (line buffering)

◆ bufread()

RawBuffer& bufread ( )

inlineinherited

Advanced: Access primary read buffer.

Caution: This returns a low-level interface that must be used properly
Note: Other buffers may be involved if filters are used
This never throws any exception

Returns: Read buffer

◆ bufwrite()

IoWriter& bufwrite ( )

inlineinherited

Advanced: Access primary write buffer.

Caution: This returns a low-level interface that must be used properly
Note: Other buffers may be involved if filters are used
This never throws any exception

Returns: Write buffer

◆ close()

bool close ( )

inlineinherited

Close stream.

This will flush output before closing
Never throws an exception, even if flush or close fails

Returns: Whether successful, false on flush error (stream will still close)

◆ detach()

Handle detach ( )

inlineinherited

Detach current stream.

This will flush output before detaching
Never throws an exception, even if flush fails

Returns: Detached handle

◆ error()

Error error ( ) const

inlineinherited

Get error code from last operation.

Returns: Error code, ENone for success (no error)

◆ excep() [1/2]

bool excep ( ) const

inlineinherited

Get whether exceptions are enabled.

Returns: Whether exceptions enabled

◆ excep() [2/2]

void excep ( bool val )

inlineinherited

Set whether exceptions are enabled.

Parameters

val	Whether to enable exceptions

◆ flush()

bool flush ( )

inlinevirtualinherited

Flush any pending output in stream write buffer, if buffered.

This is a no-op if writes aren't buffered
Call error() to check error code

Returns: Whether successful, false on error

Reimplemented from IoBase.

◆ handle()

Handle handle ( ) const

inlineinherited

Get stream handle for low-level calls.

Returns: Stream handle

◆ init()

void init	(	Open	mode,
		bool	flushlines = `false`
	)

inlineprotectedinherited

Initialize and reset buffers for a new stream.

◆ isopen()

bool isopen ( ) const

inlinevirtualinherited

Get whether stream is open.

Returns: Whether open

Reimplemented from IoBase.

◆ open()

bool open	(	const char *	path,
		Open	mode = `oREAD`,
		bool	flushlines = `false`
	)

inline

Open file for read and/or writing.

Current file is closed first
Throws ExceptionStreamOpen on error, if exceptions enabled

Parameters

path	File path to use
mode	Access mode to use
flushlines	Whether to flush text output on newlines (line buffering)

Returns: Whether successful, false on error – call error() for error code

◆ operator SafeBoolType()

operator SafeBoolType ( ) const

inlineinherited

Safe (explicit) evaluation as bool type.

This is called when object is directly evaluated as a bool, and is equivalent to: !operator!()
See SafeBool

◆ operator!()

bool operator! ( ) const

inlineinherited

Negation operator checks whether an error was set by a previous operation.

Call error() to get last error code
Alternatively, use SafeBool evaluation to check whether previous operations were successful

Returns: Whether last operation set an error

◆ operator<<() [1/38]

This& operator<< ( This & )

inlineinherited

No-op used by formatting helpers.

Returns: This

◆ operator<<() [2/38]

This& operator<< ( Newline nl )

inlineinherited

Write an explicit newline and flush stream.

Use NL for default newline value, where default is set by the stream

Parameters

nl	Newline type to write, NL for current default or NL_SYS for system default

Returns: This

◆ operator<<() [3/38]

This& operator<< ( NewlineDefault nl )

inlineinherited

Write default newline and flush stream.

This overloads operator<<(Newline)

Parameters

nl	Default newline value (NL), where default is set by the stream

Returns: This

◆ operator<<() [4/38]

This& operator<< ( const NewlineValue & nl )

inlineinherited

Write newline value and flush stream.

Parameters

nl	Newline value to use, use current stream default if null

Returns: This

◆ operator<<() [5/38]

This& operator<< ( Flush )

inlineinherited

Flush buffer by writing to stream.

This calls flush()
This is useful when writing a console prompt, flush so the prompt is immediately visible

Returns: This

◆ operator<<() [6/38]

This& operator<< ( bool val )

inlineinherited

Append a bool value to stream.

Bool value is formatted as either "true" or "false" (without quotes)
This calls writetext()

Parameters

val	Bool value to append

Returns: This

◆ operator<<() [7/38]

This& operator<< ( char ch )

inlineinherited

Write character to stream.

This calls writetext()

Parameters

ch	Character to write

Returns: This

◆ operator<<() [8/38]

This& operator<< ( const char * str )

inlineinherited

Write terminated string to stream.

This calls writetext()

Parameters

str	String to write, must be terminated

Returns: This

◆ operator<<() [9/38]

This& operator<< ( const SubString & str )

inlineinherited

Write substring to stream.

This calls writetext()

Parameters

str	Substring to write

Returns: This

◆ operator<<() [10/38]

This& operator<< ( const ListBase< char, TSize > & str )

inlineinherited

Write substring to stream.

This effectively calls writetext()
This handles all Evo character list or string types

Template Parameters

TSize List size type (inferred from parameter)

Parameters

str	Substring to write

Returns: This

◆ operator<<() [11/38]

This& operator<< ( int num )

inlineinherited

Write formatted number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [12/38]

This& operator<< ( long num )

inlineinherited

Write formatted number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [13/38]

This& operator<< ( longl num )

inlineinherited

Write formatted number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [14/38]

This& operator<< ( uint num )

inlineinherited

Write formatted number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [15/38]

This& operator<< ( ulong num )

inlineinherited

Write formatted number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [16/38]

This& operator<< ( ulongl num )

inlineinherited

Write formatted number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [17/38]

This& operator<< ( const IntegerT< U > & num )

inlineinherited

Write formatted class number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Template Parameters

U	Number class type (Int, Uint, etc)

Parameters

num	Number to format and write, no-op if null

Returns: This

◆ operator<<() [18/38]

This& operator<< ( float num )

inlineinherited

Write formatted floating-point number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [19/38]

This& operator<< ( double num )

inlineinherited

Write formatted floating-point number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [20/38]

This& operator<< ( ldouble num )

inlineinherited

Write formatted floating-point number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

num	Number to format and write

Returns: This

◆ operator<<() [21/38]

This& operator<< ( const FloatT< U > & num )

inlineinherited

Write formatted class floating-point number to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Template Parameters

U	Number class type (Float, FloatD, etc)

Parameters

num	Number to format and write, no-op if null

Returns: This

◆ operator<<() [22/38]

This& operator<< ( const FmtChar & fmt )

inlineinherited

Write repeated character to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Character info

Returns: This

◆ operator<<() [23/38]

This& operator<< ( const FmtString & fmt )

inlineinherited

Write formatted string field to stream.

Parameters

fmt	String info

Returns: This

◆ operator<<() [24/38]

This& operator<< ( const FmtShort & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [25/38]

This& operator<< ( const FmtInt & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [26/38]

This& operator<< ( const FmtLong & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [27/38]

This& operator<< ( const FmtLongL & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [28/38]

This& operator<< ( const FmtUShort & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [29/38]

This& operator<< ( const FmtUInt & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [30/38]

This& operator<< ( const FmtULong & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [31/38]

This& operator<< ( const FmtULongL & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [32/38]

This& operator<< ( const FmtFloat & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [33/38]

This& operator<< ( const FmtFloatD & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [34/38]

This& operator<< ( const FmtFloatL & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [35/38]

This& operator<< ( const FmtFieldNum< U > & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [36/38]

This& operator<< ( const FmtFieldFloat< U > & fmt )

inlineinherited

Write formatted number field to stream.

This will flush current buffer if it's too full
This formats directly to write buffer so it must be large enough

Parameters

fmt	Number info

Returns: This

◆ operator<<() [37/38]

This& operator<< ( const FmtPtr & fmtptr )

inlineinherited

Writer formatted pointer field to stream.

Parameters

fmtptr Pointer info

Returns: This

◆ operator<<() [38/38]

This& operator<< ( const FmtDump & fmt )

inlineinherited

Write formatted data dump to stream.

Parameters

fmt Dump info

Returns: This

◆ pos()

ulongl pos ( )

inline

Get current file position.

Call error() to check error code

Returns: File position on success, 0 on error

◆ readbin()

ulong readbin	(	void *	buf,
		ulong	size
	)

inlinevirtualinherited

Read binary input from stream.

This does a binary read – no conversion on newlines
Depending on the stream type, this may:
- be a blocking call
- read at least 1 byte, but less than requested
- return a read error, some stream types may timeout
Call error() to check error code
This never throws any exception

Parameters

buf	Buffer to store data read
size	Size to read

Returns: Bytes read and stored in buf, 0 if end-of-stream or error

Reimplemented from IoBase.

◆ readline()

bool readline	(	String &	str,
		ulong	maxlen = `0`
	)

inlinevirtualinherited

Read text line input from stream.

This will read and return the next line as a string, not including the newline
Depending on the stream type, this may:
- be a blocking call
- read at least 1 byte, but less than requested
- return a read error
Call error() to check error code
Error codes:
- EEnd if no more lines (end-of-file)
- EOutOfBounds if line exceeds maxlen
- ELoss if previous readtext() call left a pending partial newline pair that must be read first – this prevents data loss on the newline pair
  - Only occurs when readtext() was used with size=1 while reading a newline pair (and newline conversion to 2-byte newline pairs is used), and next readline() is called in the middle of the newline pair, triggering this special case
  - Resolve by calling readtext() again with size=1 to read the pending newline char, then resume reading as desired
  - Calling readtext() with size=1 followed by readline() on same stream is best avoided so this special case never happens
- Other codes for read errors
This never throws any exception

Parameters

str	String to store line (cleared first) [out]
maxlen	Maximum line length, 0 for no limit

Returns: Whether successful, false if no more lines (end-of-file) or error

Reimplemented from StreamBase.

◆ readtext()

ulong readtext	(	char *	buf,
		ulong	size
	)

inlinevirtualinherited

Read text input from stream.

This does a text read, converting newlines as needed
Depending on the stream type, this may:
- be a blocking call
- read at least 1 byte, but less than requested
- return a read error
Call error() to check error code
After calling this with size=1 (not recommended), calling readline() next may trigger a special case error in certain conditions – see readline() error code ELoss

Parameters

buf	Buffer to store data read
size	Size in bytes to read from file (must be positive)

Returns: Bytes read, 0 if end-of-file or error

Reimplemented from StreamBase.

◆ seek()

ulongl seek	(	ulongl	offset,
		Seek	start = `sBegin`
	)

inline

Seek to file position.

Call error() to check error code

Parameters

offset	Offset from start to seek to
start	Start position to seek from

Returns: New file position after seek, 0 for beginning or error

◆ write_direct()

char* write_direct ( Size size )

inlinevirtualinherited

Get pointer for writing directly to buffer to append data.

Call write_direct_finish() to commit written data, or don't to cancel
This will flush buffer to make room, if needed
Newlines in data written aren't converted

Parameters

size	Requred size in bytes to reserve

Returns: Buffer to write to (at append position), NULL on error or if buffer not large enough or if not supported

Reimplemented from StreamBase.

◆ write_direct_finish()

bool write_direct_finish ( Size size )

inlinevirtualinherited

Finish writing directly to buffer.

This commits data written directly after calling write_direct() or write_direct_multi(), one of which must be called first
Newlines in data written aren't converted

Parameters

size	Size written in bytes, must not be greater than `size` passed to write_direct()

Returns: Whether successful, false if not supported

Reimplemented from StreamBase.

◆ write_direct_flush()

char* write_direct_flush	(	Size &	available,
		Size	written_size,
		Size	reserve_size
	)

inlineinherited

◆ write_direct_multi()

char* write_direct_multi	(	Size &	available,
		Size	reserve_size
	)

inlineinherited

◆ write_out()

Out& write_out ( )

inlineinherited

◆ writebin()

ulong writebin	(	const void *	buf,
		ulong	size
	)

inlinevirtualinherited

Write binary output to stream.

This does a binary write – no conversion on newlines
Depending on the stream type, this may:
- be a blocking call
- write at least 1 byte, but less than requested
  - StreamBase: always writes all data on success
- return a write error, some stream types may timeout
Call error() to check error code

Parameters

buf	Data to write
size	Size to write

Returns: Bytes written, 0 on error

Reimplemented from IoBase.

◆ writechar()

ulong writechar	(	char	ch,
		ulong	count = `1`
	)

inlinevirtualinherited

Write repeat character as text output to stream.

This does a text write, converting newlines as needed
- Note that writing newline text characters 1 char at a time or by string will give the same end result either way – the edge cases are covered
Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Parameters

ch	Character to write
count	Character count to write, must be positive

Returns: Size actually written (should be the same as count), 0 on error

Reimplemented from StreamBase.

◆ writefmtchar()

bool writefmtchar	(	char	ch,
		ulong	count,
		const FmtSetField &	field
	)

inlineinherited

Write formatted and/or repeated character.

Parameters

ch	Character to write
count	Character repeat count to use
field	Field attributes to use

Returns: Whether successful, false on error

◆ writefmtdump() [1/2]

bool writefmtdump ( const FmtDump & fmt )

inlineinherited

Write formatted data dump.

Output may span multiple lines, and always ends with a newline (unless dump data is empty)
Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Parameters

fmt	Format data, including buffer to dump

Returns: Whether successful, false on error

◆ writefmtdump() [2/2]

bool writefmtdump	(	const FmtDump &	fmt,
		Newline	nl
	)

inlineinherited

Write formatted data dump with explicit newline type.

Output may span multiple lines, and always ends with a newline (unless dump data is empty)
Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Parameters

fmt	Format data, including buffer to dump
nl	Newline type to use, NL for current default or NL_SYS for system default

Returns: Whether successful, false on error

◆ writefmtnum()

bool writefmtnum	(	TNum	num,
		const FmtSetInt &	fmt,
		const FmtSetField *	field = `NULL`
	)

inlineinherited

Write formatted signed number with field alignment.

Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
fmt	Integer formatting attributes to use
field	Field formatting attributes to use, NULL for none

Returns: Whether successful, false on error

◆ writefmtnumf()

bool writefmtnumf	(	TNum	num,
		const FmtSetFloat &	fmt,
		const FmtSetField *	field = `NULL`
	)

inlineinherited

Write formatted floating point number with field alignment.

Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
fmt	Floating point formatting attributes to use
field	Field formatting attributes to use, NULL for none

Returns: Whether successful, false on error

◆ writefmtnumu()

bool writefmtnumu	(	TNum	num,
		const FmtSetInt &	fmt,
		const FmtSetField *	field = `NULL`
	)

inlineinherited

Write formatted unsigned number with field alignment.

Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
fmt	Integer formatting attributes to use
field	Field formatting attributes to use, NULL for none

Returns: Whether successful, false on error

◆ writefmtstr()

bool writefmtstr	(	const char *	buf,
		ulong	size,
		const FmtSetField &	field
	)

inlineinherited

Write text with field alignment.

This does a text write, converting newlines as needed
Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Parameters

buf	Buffer to write from
size	Size to write in bytes
field	Field attributes to use

Returns: Whether successful, false on error

◆ writeline()

ulong writeline	(	const char *	buf,
		ulong	size
	)

inlinevirtualinherited

Write text line output to stream.

This always writes the whole line followed by a newline on success
This does a text write, converting newlines as needed, which could turn into multiple lines
Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Parameters

buf	Data buffer to write from
size	Data size to write in bytes, must be positive

Returns: Size actually written (including newline), 0 on error

Reimplemented from StreamBase.

◆ writenum()

bool writenum	(	TNum	num,
		int	base = `fDEC`
	)

inlineinherited

Write formatted signed number.

Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
base	Base to use for formatting

Returns: Whether successful, false on error

◆ writenumf()

bool writenumf	(	TNum	num,
		int	precision = `fPREC_AUTO`
	)

inlineinherited

Write formatted floating-point number.

Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
precision	Formatting precision (number of fractional digits), 0 for none, fPREC_AUTO for automatic

Returns: Whether successful, false on error

◆ writenumu()

bool writenumu	(	TNum	num,
		int	base = `fDEC`
	)

inlineinherited

Write formatted unsigned number.

Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Template Parameters

TNum	Number type, inferred by param

Parameters

num	Number to write
base	Base to use for formatting

Returns: Whether successful, false on error

◆ writequoted()

Size writequoted	(	const char *	buf,
		Size	size,
		char	delim,
		bool	optional = `false`
	)

inlinevirtualinherited

Write quoted text output to string.

Newlines and unprintable characters are written as-is
This uses Smart Quoting – see Smart Quoting

Parameters

buf	Data to quote and write
size	Data size to write
delim	Delimiter for next field to escape via quoting
optional	Whether quoting is optional, true to avoid quoting if possible

Returns: Size actually written, 0 on error (write error or unquotable text)

Reimplemented from StreamBase.

◆ writetext()

ulong writetext	(	const char *	buf,
		ulong	size
	)

inlinevirtualinherited

Write text output to stream.

This does a text write, converting newlines as needed
Depending on the stream type, this may be a blocking call
If exceptions are disabled, call error() to check error code

Parameters

buf	Data to write
size	Size to write

Returns: Size actually written, 0 on error

Reimplemented from StreamBase.

Member Data Documentation

◆ bufrd_

IoReader bufrd_

protectedinherited

Buffered reader.

◆ bufwr_

IoWriter bufwr_

protectedinherited

Buffered writer.

◆ device_

IoFile device_

protectedinherited

I/O device.

◆ error_

Error error_

protectedinherited

Last error code.

◆ excep_

bool excep_

protectedinherited

Whether to throw exceptions.

◆ owned_

bool owned_

protectedinherited

Whether handle is owned (to be closed here)

◆ rwlast_

RwLast rwlast_

protectedinherited

Read/Write: Used to track last operation when switching between read/write.

◆ savepos_

ulongl savepos_

protectedinherited

Read/Write: Used to save buffered read position when switching between read/write.

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

evo/file.h

Detailed Description

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ Base

◆ ExceptionInT

◆ ExceptionOutT

◆ Format

◆ Handle

◆ Out

◆ Size

◆ This

Member Enumeration Documentation

◆ RwLast

Constructor & Destructor Documentation

◆ File() [1/3]

◆ File() [2/3]

◆ File() [3/3]

Member Function Documentation

◆ attach()

◆ bufread()

◆ bufwrite()

◆ close()

◆ detach()

◆ error()

◆ excep() [1/2]

◆ excep() [2/2]

◆ flush()

◆ handle()

◆ init()

◆ isopen()

◆ open()

◆ operator SafeBoolType()

◆ operator!()

◆ operator<<() [1/38]

◆ operator<<() [2/38]

◆ operator<<() [3/38]

◆ operator<<() [4/38]

◆ operator<<() [5/38]

◆ operator<<() [6/38]

◆ operator<<() [7/38]

◆ operator<<() [8/38]

◆ operator<<() [9/38]

◆ operator<<() [10/38]

◆ operator<<() [11/38]

◆ operator<<() [12/38]

◆ operator<<() [13/38]

◆ operator<<() [14/38]

◆ operator<<() [15/38]

◆ operator<<() [16/38]

◆ operator<<() [17/38]

◆ operator<<() [18/38]

◆ operator<<() [19/38]

◆ operator<<() [20/38]

◆ operator<<() [21/38]

◆ operator<<() [22/38]

◆ operator<<() [23/38]

◆ operator<<() [24/38]

◆ operator<<() [25/38]

◆ operator<<() [26/38]

◆ operator<<() [27/38]

◆ operator<<() [28/38]

◆ operator<<() [29/38]

◆ operator<<() [30/38]

◆ operator<<() [31/38]

◆ operator<<() [32/38]

◆ operator<<() [33/38]

◆ operator<<() [34/38]

◆ operator<<() [35/38]

◆ operator<<() [36/38]

◆ operator<<() [37/38]

◆ operator<<() [38/38]

◆ pos()

◆ readbin()

◆ readline()

◆ readtext()

◆ seek()