streams.h File Reference

Basic byte stream interfaces. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/objects.h"
#include "gate/strings.h"

Classes
struct	gate_memstream_impl

Macros
#define	GATE_STREAM_OPEN_READ   0x0001
#define	GATE_STREAM_OPEN_WRITE   0x0002
#define	GATE_STREAM_OPEN_READWRITE   (GATE_STREAM_OPEN_READ | GATE_STREAM_OPEN_WRITE)
#define	GATE_STREAM_OPEN_APPEND   0x0004
#define	GATE_STREAM_OPEN_APPENDWRITE   (GATE_STREAM_OPEN_APPEND | GATE_STREAM_OPEN_WRITE)
#define	GATE_STREAM_OPEN_APPENDREADWRITE   (GATE_STREAM_OPEN_APPEND | GATE_STREAM_OPEN_READ | GATE_STREAM_OPEN_WRITE)
#define	GATE_STREAM_OPEN_FLAGS_MASK   0x00ff
#define	GATE_INTERFACE_NAME_STREAM   GATE_INTERFACE_NAME_OBJECT GATE_INTERFACE_NAME_SEPARATOR "stream"
#define	gate_stream_read(stream, buffer, bufferlength, returned)   (stream)->vtbl->read((stream), (buffer), (bufferlength), (returned))
	Shortcut to gate_stream_t::read.
#define	gate_stream_peek(stream, buffer, bufferlength, returned)   (stream)->vtbl->peek((stream), (buffer), (bufferlength), (returned))
	Shortcut to gate_stream_t::peek.
#define	gate_stream_flush(stream)   (stream)->vtbl->flush((stream))
	Shortcut to gate_stream_t::flush.
#define	gate_stream_write(stream, buffer, bufferlength, written)   (stream)->vtbl->write((stream), (buffer), (bufferlength), (written))
	Shortcut to gate_stream_t::write.
#define	GATE_INTERFACE_NAME_RESOURCESTREAM   GATE_INTERFACE_NAME_STREAM GATE_INTERFACE_NAME_SEPARATOR "resource"
#define	GATE_STREAM_RESOURCE_DEFAULT   0x0000
#define	GATE_STREAM_RESOURCE_INPUT   0x0001
#define	GATE_STREAM_RESOURCE_OUTPUT   0x0002
#define	GATE_STREAM_RESOURCE_ERROR   0x0003
#define	gate_stream_get_resource(stream, resource_type, resource_handle)   (stream)->vtbl->get_resource((stream), (resource_type), (resource_handle))
	Returns the native resource handle of a stream.
#define	GATE_INTERFACE_NAME_CONTROLSTREAM   GATE_INTERFACE_NAME_RESOURCESTREAM GATE_INTERFACE_NAME_SEPARATOR "control"
#define	gate_stream_can_read(stream, return_value)   (stream)->vtbl->can_read((stream), (return_value))
	Shortcut to gate_controlstream_t::can_read.
#define	gate_stream_can_write(stream, return_value)   (stream)->vtbl->can_write((stream), (return_value))
	Shortcut to gate_controlstream_t::can_write.
#define	gate_stream_get_size(stream, return_value)   (stream)->vtbl->get_size((stream), (return_value))
	Shortcut to gate_controlstream_t::get_size.
#define	gate_stream_get_available(stream, return_value)   (stream)->vtbl->get_available((stream), (return_value))
	Shortcut to gate_controlstream_t::get_available.
#define	gate_stream_seek(stream, position, origin, new_position)   (stream)->vtbl->seek((stream), (position), (origin), (new_position))
	Shortcut to gate_controlstream_t::seek.
#define	gate_stream_reset(stream)   (stream)->vtbl->reset((stream))
	Shortcut to gate_controlstream_t::reset.
#define	gate_stream_close(stream, close_type)   (stream)->vtbl->close((stream), (close_type))
	Shortcut to gate_controlstream_t::close.
#define	gate_stream_get_position(stream, position)   gate_stream_seek((stream), 0, GATE_STREAM_SEEK_CURRENT, position)
	Returns the current absolute position within the stream (by using seek(0, CURRENT)
#define	GATE_STREAM_SEEK_BEGIN   0x0000
#define	GATE_STREAM_SEEK_CURRENT   0x0001
#define	GATE_STREAM_SEEK_END   0x0002
#define	GATE_STREAM_CLOSE_DEFAULT   0x0000
#define	GATE_STREAM_CLOSE_INPUT   0x0001
#define	GATE_STREAM_CLOSE_OUTPUT   0x0002
#define	GATE_STREAM_CLOSE_ERROR   0x0003
#define	GATE_INTERFACE_NAME_MEMSTREAM   GATE_INTERFACE_NAME_STREAM GATE_INTERFACE_NAME_SEPARATOR "memory"
#define	gate_memstream_get_data(obj)   (obj)->vtbl->get_data((obj))
	Shortcut to gate_memstream_t::get_data.
#define	gate_memstream_size(obj)   (obj)->vtbl->size((obj))
	Shortcut to gate_memstream_t::size.
#define	gate_memstream_reserve(obj, space)   (obj)->vtbl->reserve((obj), space)
	Shortcut to gate_memstream_t::reserve.
#define	gate_memstream_fill(obj, item, count)   (obj)->vtbl->fill((obj), item, count)
	Shortcut to gate_memstream_t::fill.
#define	gate_memstream_discard(obj, count)   (obj)->vtbl->discard((obj), count)
	Shortcut to gate_memstream_t::discard.
#define	gate_memstream_discard_back(obj, count)   (obj)->vtbl->discard_back((obj), count)
	Shortcut to gate_memstream_t::discard_back.
#define	gate_memstream_reset(obj)   (obj)->vtbl->reset((obj))
	Shortcut to gate_memstream_t::reset.
#define	GATE_INTERFACE_NAME_STRINGSTREAM   GATE_INTERFACE_NAME_STREAM GATE_INTERFACE_NAME_SEPARATOR "stringstream"
#define	gate_stringstream_get_data(obj)   (obj)->vtbl->get_data((obj))
	Shortcut to gate_stringstream_t::get_data.
#define	gate_stringstream_size(obj)   (obj)->vtbl->size((obj))
	Shortcut to gate_stringstream_t::size.
#define	gate_stringstream_get_current_view(obj, ptr_output)   (obj)->vtbl->get_current_view((obj), (ptr_output))
	Shortcut to gate_stringstream_t::get_current_view.
#define	gate_stringstream_to_string(obj, ptr_output)   (obj)->vtbl->to_string((obj), (ptr_output))
	Shortcut to gate_stringstream_t::to_string.

Typedefs
typedef struct gate_memstream_impl	gate_memstream_impl_t

Functions
	GATE_INTERFACE (gate_stream)
GATE_CORE_API gate_result_t	gate_stream_read_block (gate_stream_t *stream, char *buffer, gate_size_t bufferlength, gate_size_t *returned)
GATE_CORE_API gate_result_t	gate_stream_read_line (gate_stream_t *stream, char *buffer, gate_size_t bufferlength, gate_size_t *returned)
GATE_CORE_API gate_result_t	gate_stream_write_block (gate_stream_t *stream, char const *buffer, gate_size_t bufferlength, gate_size_t *written)
GATE_CORE_API gate_result_t	gate_stream_print_cstr (gate_stream_t *stream, gate_cstr_t cstr)
GATE_CORE_API gate_result_t	gate_stream_print_wstr (gate_stream_t *stream, gate_wstr_t wstr, gate_size_t wstr_len)
GATE_CORE_API gate_result_t	gate_stream_println_cstr (gate_stream_t *stream, char const *text)
GATE_CORE_API gate_result_t	gate_stream_print_int (gate_stream_t *stream, gate_int32_t num)
GATE_CORE_API gate_result_t	gate_stream_print_uint (gate_stream_t *stream, gate_uint32_t num)
GATE_CORE_API gate_result_t	gate_stream_print_int64 (gate_stream_t *stream, gate_int64_t num)
GATE_CORE_API gate_result_t	gate_stream_print_uint64 (gate_stream_t *stream, gate_uint64_t num)
GATE_CORE_API gate_result_t	gate_stream_print_real (gate_stream_t *stream, gate_real64_t num, unsigned intlen, unsigned decimallen, unsigned grouplen)
GATE_CORE_API gate_result_t	gate_stream_print_string (gate_stream_t *stream, gate_string_t const *text)
GATE_CORE_API gate_result_t	gate_stream_print (gate_stream_t *stream,...)
GATE_CORE_API gate_size_t	gate_stream_scan_char8 (gate_stream_t *stream, gate_char8_t *chr)
GATE_CORE_API gate_size_t	gate_stream_scan_char16 (gate_stream_t *stream, gate_char16_t *chr)
GATE_CORE_API gate_size_t	gate_stream_scan_char32 (gate_stream_t *stream, gate_char32_t *chr)
GATE_CORE_API gate_size_t	gate_stream_scan_int (gate_stream_t *stream, gate_int32_t *num)
GATE_CORE_API gate_size_t	gate_stream_scan_uint (gate_stream_t *stream, gate_uint32_t *num)
GATE_CORE_API gate_size_t	gate_stream_scan_int64 (gate_stream_t *stream, gate_int64_t *num)
GATE_CORE_API gate_size_t	gate_stream_scan_uint64 (gate_stream_t *stream, gate_uint64_t *num)
GATE_CORE_API gate_size_t	gate_stream_scan_real (gate_stream_t *stream, gate_real64_t *num)
GATE_CORE_API gate_size_t	gate_stream_scan_string (gate_stream_t *stream, gate_string_t *text)
GATE_CORE_API gate_result_t	gate_stream_transfer_buffer (gate_stream_t *src, gate_stream_t *dst, char *buffer, gate_size_t buffersize)
GATE_CORE_API gate_result_t	gate_stream_transfer_limit (gate_stream_t *src, gate_uint64_t limit, gate_stream_t *dst, gate_uint64_t *transferred)
GATE_CORE_API gate_result_t	gate_stream_transfer (gate_stream_t *src, gate_stream_t *dst)
GATE_CORE_API gate_result_t	gate_stream_skip (gate_stream_t *src, gate_uint64_t count, gate_uint64_t *bytes_skipped)
	GATE_INTERFACE (gate_resourcestream)
	GATE_INTERFACE (gate_controlstream)
	GATE_INTERFACE (gate_memstream)
GATE_CORE_API gate_memstream_t *	gate_memstream_create (gate_size_t capacity)
	Creates a new memory stream on heap (readable/writable)
GATE_CORE_API gate_memstream_t *	gate_memstream_create_static (void *buffer, gate_size_t capacity, gate_size_t used)
	Creates a memory stream using a static fixed buffer (readable/writable)
GATE_CORE_API gate_memstream_t *	gate_memstream_create_static_unmanaged (gate_memstream_impl_t *impl, void *buffer, gate_size_t capacity, gate_size_t used)
	Initializes a memory stream as a local unmanaged structure without reference counting (readable/writable)
GATE_CORE_API gate_memstream_t *	gate_memstream_create_static_unmanaged_readonly (gate_memstream_impl_t *impl, void const *buffer, gate_size_t capacity, gate_size_t used)
	Initializes a memory stream as a local unmanaged structure without reference counting (read-only)
	GATE_INTERFACE (gate_stringstream)
GATE_CORE_API gate_stringstream_t *	gate_stringstream_create (gate_size_t capacity)
	Creates a new string stream object.
GATE_CORE_API gate_stringstream_t *	gate_stringstream_create_builder (gate_strbuilder_t *external_strbuilder)
	Creates a new string stream object from an external string-builder object.
GATE_CORE_API gate_stream_t *	gate_nullstream ()
	Creates a NULL-stream that accepts and discards all write()s and returns 0 bytes on read()s.

Detailed Description

Basic byte stream interfaces.

Macro Definition Documentation

GATE_STREAM_CLOSE_DEFAULT

#define GATE_STREAM_CLOSE_DEFAULT   0x0000

Closes the stream following the streams defaults

GATE_STREAM_CLOSE_ERROR

#define GATE_STREAM_CLOSE_ERROR   0x0003

Closes the error resources of the stream

GATE_STREAM_CLOSE_INPUT

#define GATE_STREAM_CLOSE_INPUT   0x0001

Closes the input resources of the stream

GATE_STREAM_CLOSE_OUTPUT

#define GATE_STREAM_CLOSE_OUTPUT   0x0002

Closes the output resources of the stream

gate_stream_get_resource

#define gate_stream_get_resource	(		stream,
			resource_type,
			resource_handle )   (stream)->vtbl->get_resource((stream), (resource_type), (resource_handle))

Returns the native resource handle of a stream.

Parameters

[in]	stream	Pointer to stream object
[in]	resource_type	GATE_STREAM_RESOURCE_* type of handle to retrieve
[out]	resource_handle	Pointer to output resource handle variable

Returns

GATE_RESULT_* result code

GATE_STREAM_RESOURCE_DEFAULT

#define GATE_STREAM_RESOURCE_DEFAULT   0x0000

Requests the default resource handle of a stream

GATE_STREAM_RESOURCE_ERROR

#define GATE_STREAM_RESOURCE_ERROR   0x0003

Requests the error resource handle of a stream

GATE_STREAM_RESOURCE_INPUT

#define GATE_STREAM_RESOURCE_INPUT   0x0001

Requests the input resource handle of a stream

GATE_STREAM_RESOURCE_OUTPUT

#define GATE_STREAM_RESOURCE_OUTPUT   0x0002

Requests the output resource handle of a stream

GATE_STREAM_SEEK_BEGIN

#define GATE_STREAM_SEEK_BEGIN   0x0000

Seeks a new access position in stream relative to the absolute BEGIN of the stream

GATE_STREAM_SEEK_CURRENT

#define GATE_STREAM_SEEK_CURRENT   0x0001

Seeks a new access position in stream relative to the CURRENT position of the stream

GATE_STREAM_SEEK_END

#define GATE_STREAM_SEEK_END   0x0002

Seeks a new access position in stream relative to the absolute END of the stream

Function Documentation

gate_memstream_create()

GATE_CORE_API gate_memstream_t * gate_memstream_create

(

gate_size_t

capacity

)

Creates a new memory stream on heap (readable/writable)

Parameters

[in]

capacity

Amount of bytes to preallocate return New memstream instance

gate_memstream_create_static()

GATE_CORE_API gate_memstream_t * gate_memstream_create_static	(	void *	buffer,
		gate_size_t	capacity,
		gate_size_t	used )

Creates a memory stream using a static fixed buffer (readable/writable)

Parameters

[in]	buffer	Pointer to begin of static buffer to use
[in]	capacity	Capacity of buffer (maximum amount of usable bytes)
[in]	used	Amount of bytes already filled and ready to be read (counted from the beginning) return New memstream instance

gate_memstream_create_static_unmanaged()

GATE_CORE_API gate_memstream_t * gate_memstream_create_static_unmanaged	(	gate_memstream_impl_t *	impl,
		void *	buffer,
		gate_size_t	capacity,
		gate_size_t	used )

Initializes a memory stream as a local unmanaged structure without reference counting (readable/writable)

Parameters

[in,out]	impl	Pointer to memstream implementation structure to be initiaized
[in]	buffer	Pointer to begin of static buffer to use
[in]	capacity	Capacity of buffer (maximum amount of usable bytes)
[in]	used	Amount of bytes already filled and ready to be read (counted from the beginning) return New memstream instance

gate_memstream_create_static_unmanaged_readonly()

GATE_CORE_API gate_memstream_t * gate_memstream_create_static_unmanaged_readonly	(	gate_memstream_impl_t *	impl,
		void const *	buffer,
		gate_size_t	capacity,
		gate_size_t	used )

Initializes a memory stream as a local unmanaged structure without reference counting (read-only)

Parameters

[in,out]	impl	Pointer to memstream implementation structure to be initiaized
[in]	buffer	Pointer to begin of static buffer to use
[in]	capacity	Capacity of buffer (maximum amount of usable bytes)
[in]	used	Amount of bytes already filled and ready to be read (counted from the beginning) return New memstream instance

gate_nullstream()

GATE_CORE_API gate_stream_t * gate_nullstream

(

)

Creates a NULL-stream that accepts and discards all write()s and returns 0 bytes on read()s.

Returns

new null stream object

gate_stringstream_create()

GATE_CORE_API gate_stringstream_t * gate_stringstream_create

(

gate_size_t

capacity

)

Creates a new string stream object.

Parameters

[in]

capacity

Amount of bytes to preallocate internally

Returns

new string-stream object

gate_stringstream_create_builder()

GATE_CORE_API gate_stringstream_t * gate_stringstream_create_builder

(

gate_strbuilder_t *

external_strbuilder

)

Creates a new string stream object from an external string-builder object.

Parameters

[in]

external_strbuilder

Pointer to strbuilder object to be imported and used

Returns

new string-stream object