#include <evo/io.h>

Inheritance diagram for PipeIn:

[legend]

Detailed Description

Input stream for reading from pipe.

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

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

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

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

Public Member Functions
	PipeIn (bool exceptions=1)
	Constructor. More...

void	attach (Handle handle, bool owned=true)
	Attach existing input stream. More...

RawBuffer &	bufread ()
	Advanced: Access primary read 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...

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

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

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

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 Member Functions
void	init ()
	Initialize and reset buffers for a new stream. More...

Protected Attributes
IoReader	bufrd_
	Buffered reader. More...

IoFile	device_
	I/O handle. 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...

Member Typedef Documentation

◆ ExceptionInT

typedef IoFile ::ExceptionInT ExceptionInT

inherited

Stream input exception type

◆ Handle

typedef IoFile ::Handle Handle

inherited

Low-level handle type (OS dependent)

◆ Size

typedef ulong Size

inherited

Data size type (ulong)

◆ This

typedef StreamIn<IoFile > This

inherited

This stream type.

Constructor & Destructor Documentation

◆ PipeIn()

PipeIn ( bool exceptions = 1 )

inline

Constructor.

Parameters

exceptions Whether to enable exceptions on error, default set by Evo config: EVO_EXCEPTIONS

Member Function Documentation

◆ attach()

void attach	(	Handle	handle,
		bool	owned = `true`
	)

inlineinherited

Attach existing input stream.

Parameters

handle	Handle to attach, must be valid
owned	Whether to take ownership and close handle, false detaches on close()

◆ 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

◆ close()

bool close ( )

inlineinherited

Close stream.

Never throws an exception, even if close fails

Returns: Whether successful, always true

◆ detach()

Handle detach ( )

inlineinherited

Detach current stream.

Never throws an exception

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

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

◆ handle()

Handle handle ( ) const

inlineinherited

Get stream handle for low-level calls.

Returns: Stream handle

◆ init()

void init ( )

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.

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

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.

◆ write_direct()

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

◆ write_direct_finish()

virtual 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 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
	)

inlineinherited

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
	)

inlineinherited

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`
	)

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

◆ writeline()

virtual 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 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`
	)

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

◆ writetext()

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

Member Data Documentation

◆ bufrd_

IoReader bufrd_

protectedinherited

Buffered reader.

◆ device_

IoFile device_

protectedinherited

I/O handle.

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

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

evo/io.h

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ ExceptionInT

◆ Handle

◆ Size

◆ This

Constructor & Destructor Documentation

◆ PipeIn()

Member Function Documentation

◆ attach()

◆ bufread()

◆ close()

◆ detach()

◆ error()

◆ excep() [1/2]

◆ excep() [2/2]

◆ flush()

◆ handle()

◆ init()

◆ 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

◆ bufrd_

◆ device_

◆ error_

◆ excep_

◆ owned_