#include <evo/iobase.h>

Inheritance diagram for StreamBase:

[legend]

Detailed Description

Base text and binary stream interface.

This extends IoBase and adds reading and writing text
Text I/O automatically handles newline conversion
For absolute best performance use binary I/O, if possible

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

Public Member Functions
	StreamBase ()
	Constructor. More...

virtual	~StreamBase ()
	Destructor. 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...

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

virtual bool	isopen () const
	Get whether stream is open. 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...

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

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

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

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

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

char *	write_direct_flush (Size &available, Size written_size, Size reserve_size)
	Flush data written directly to buffer and get pointer for appending more. More...

char *	write_direct_multi (Size &available, Size reserve_size)
	Get pointer for writing directly to buffer to append data and allow multiple passes for larger sizes. More...

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

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

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

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

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

Protected Attributes
Error	error_
	Last error code. More...

bool	excep_
	Whether to throw exceptions. More...

Member Typedef Documentation

◆ Size

typedef ulong Size

Data size type (ulong)

Constructor & Destructor Documentation

◆ StreamBase()

StreamBase ( )

inline

Constructor.

◆ ~StreamBase()

virtual ~StreamBase ( )

inlinevirtual

Destructor.

Member Function Documentation

◆ 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()

virtual 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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ isopen()

virtual bool isopen ( ) const

inlinevirtualinherited

Get whether stream is open.

Returns: Whether open

Reimplemented in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, StreamOut< IoFile >, StreamIn< T >, and StreamIn< IoFile >.

◆ 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

◆ readbin()

virtual 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 in SocketCast, Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamIn< T >, and StreamIn< IoFile >.

◆ readline()

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

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamIn< T >, and StreamIn< IoFile >.

◆ readtext()

virtual ulong readtext	(	char *	buf,
		ulong	size
	)

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamIn< T >, and StreamIn< IoFile >.

◆ write_direct()

virtual char* write_direct ( Size size )

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ write_direct_finish()

virtual bool write_direct_finish ( Size size )

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ write_direct_flush()

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

inline

Flush data written directly to buffer and get pointer for appending more.

This commits data written directly after previous call or write_direct_multi(), which must be called first
If reserve_size is 0 then this does the same as write_direct_finish() and returns a non-NULL but invalid pointer on success
Newlines in data written aren't converted

Parameters

available	Stores available size reserved in bytes, may be less than `reserve_size`, 0 if `reserve_size` was 0 [out]
written_size	Size written in bytes to flush, must not be greater than `available` size from previous call to this or write_direct_multi()
reserve_size	Requred size in bytes to reserve, 0 to finish

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

◆ write_direct_multi()

char* write_direct_multi	(	Size &	available,
		Size	reserve_size
	)

inline

Get pointer for writing directly to buffer to append data and allow multiple passes for larger sizes.

Call write_direct_flush() or write_direct_finish() to commit written data, or neither to cancel
If reserve_size is 0 then this does nothing and returns a non-NULL but invalid pointer
This will flush buffer to make room, if needed
Newlines in data written aren't converted

Parameters

available	Stores available size reserved in bytes, may be less than `reserve_size`, 0 if `reserve_size` was 0 [out]
reserve_size	Requred size in bytes to reserve

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

◆ writebin()

virtual 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 in SocketCast, Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ writechar()

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

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ writeline()

virtual ulong writeline	(	const char *	buf,
		ulong	size
	)

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ writequoted()

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

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

◆ writetext()

virtual ulong writetext	(	const char *	buf,
		ulong	size
	)

inlinevirtual

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 in Stream< T >, Stream< IoFile >, Stream< IoSocket >, StreamOut< T >, and StreamOut< IoFile >.

Member Data Documentation

◆ error_

Error error_

protectedinherited

Last error code.

◆ excep_

bool excep_

protectedinherited

Whether to throw exceptions.

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

evo/iobase.h

Detailed Description

Public Types

Public Member Functions

Protected Attributes

Member Typedef Documentation

◆ Size

Constructor & Destructor Documentation

◆ StreamBase()

◆ ~StreamBase()

Member Function Documentation

◆ error()

◆ excep() [1/2]

◆ excep() [2/2]

◆ flush()

◆ isopen()

◆ operator SafeBoolType()

◆ operator!()

◆ readbin()

◆ readline()

◆ readtext()

◆ write_direct()

◆ write_direct_finish()

◆ write_direct_flush()

◆ write_direct_multi()

◆ writebin()

◆ writechar()

◆ writeline()

◆ writequoted()

◆ writetext()

Member Data Documentation

◆ error_

◆ excep_