The read/write operation structure. More...

Inheritance diagram for SDL::IOStreamRef:

Public Member Functions
PropertiesRef	GetProperties () const
	Get the properties associated with an IOStreamRef.

IOStatus	GetStatus () const
	Query the stream status of an IOStreamRef.

Sint64	GetSize () const
	Use this function to get the size of the data stream in an IOStreamRef.

Sint64	Seek (Sint64 offset, IOWhence whence)
	Seek within an IOStreamRef data stream.

Sint64	Tell () const
	Determine the current read/write offset in an IOStreamRef data stream.

std::string	Read (size_t size=-1)
	Read from a data source.

size_t	Read (TargetBytes buf)
	Read from a data source.

size_t	Write (SourceBytes buf)
	Write to an IOStreamRef data stream.

size_t	print (std::string_view fmt, auto... args)

size_t	println (std::string_view fmt, auto... args)

size_t	printf (SDL_PRINTF_FORMAT_STRING const char *fmt,...)
	Print to an IOStreamRef data stream.

size_t	vprintf (SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap)
	Print to an IOStreamRef data stream.

void	Flush ()
	Flush any buffered data in the stream.

StringResult	LoadFile ()
	Load all the data from an SDL data stream.

template<class T >
OwnArray< T >	LoadFileAs ()
	Load all the data from an SDL data stream.

void	SaveFile (SourceBytes data)
	Save all the data into an SDL data stream.

Uint8	ReadU8 ()
	Use this function to read a byte from an IOStreamRef.

Sint8	ReadS8 ()
	Use this function to read a signed byte from an IOStreamRef.

Uint16	ReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.

Sint16	ReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.

Uint16	ReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.

Sint16	ReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.

Uint32	ReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.

Sint32	ReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.

Uint32	ReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.

Sint32	ReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.

Uint64	ReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.

Sint64	ReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.

Uint64	ReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.

Sint64	ReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.

void	WriteU8 (Uint8 value)
	Use this function to write a byte to an IOStreamRef.

void	WriteS8 (Sint8 value)
	Use this function to write a signed byte to an IOStreamRef.

void	WriteU16LE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStreamRef as little-endian data.

void	WriteS16LE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStreamRef as little-endian data.

void	WriteU16BE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStreamRef as big-endian data.

void	WriteS16BE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStreamRef as big-endian data.

void	WriteU32LE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStreamRef as little-endian data.

void	WriteS32LE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStreamRef as little-endian data.

void	WriteU32BE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStreamRef as big-endian data.

void	WriteS32BE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStreamRef as big-endian data.

void	WriteU64LE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStreamRef as little-endian data.

void	WriteS64LE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStreamRef as little-endian data.

void	WriteU64BE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStreamRef as big-endian data.

void	WriteS64BE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStreamRef as big-endian data.

std::optional< Uint8 >	TryReadU8 ()
	Use this function to read a byte from an IOStreamRef.

std::optional< Sint8 >	TryReadS8 ()
	Use this function to read a byte from an IOStreamRef.

std::optional< Uint16 >	TryReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.

std::optional< Sint16 >	TryReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.

std::optional< Uint16 >	TryReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.

std::optional< Sint16 >	TryReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.

std::optional< Uint32 >	TryReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.

std::optional< Sint32 >	TryReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.

std::optional< Uint32 >	TryReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.

std::optional< Sint32 >	TryReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.

std::optional< Uint64 >	TryReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.

std::optional< Sint64 >	TryReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.

std::optional< Uint64 >	TryReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.

std::optional< Sint64 >	TryReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.

constexpr	Resource (T resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

Public Member Functions inherited from SDL::Resource< SDL_IOStream * >
constexpr	Resource (SDL_IOStream * resource={})
	Constructs from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< SDL_IOStream * > > auto &resource)
	Constructs from pointer like.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

constexpr	operator bool () const
	True if contains a valid resource.

constexpr	operator value_type () const
	Converts back to underlying type.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_IOStream *	get () const
	Return contained resource;.

constexpr const SDL_IOStream *	operator-> () const
	Access to fields.

constexpr SDL_IOStream *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	reset (SDL_IOStream *resource)
	Close and free an allocated IOStreamRef structure.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_IOStream * >
using	value_type = SDL_IOStream *
	The raw resource type.

Detailed Description

This operates as an opaque handle. There are several APIs to create various types of I/O streams, or an app can supply an IOStreamInterface to IOStream.Open() to provide their own stream implementation behind this struct's abstract interface.

Since: This struct is available since SDL 3.2.0.

Category:: Resource

See also: IOStream

Member Function Documentation

◆ Flush()

void SDL::IOStreamRef::Flush ( )

inline

This function makes sure that any buffered data is written to the stream. Normally this isn't necessary but if the stream is a pipe or socket it guarantees that any pending data is sent.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromFile; IOStreamRef.Write

◆ GetProperties()

PropertiesRef SDL::IOStreamRef::GetProperties ( ) const

inline

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetSize()

Sint64 SDL::IOStreamRef::GetSize ( ) const

inline

Returns: the size of the data stream in the IOStreamRef on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetStatus()

IOStatus SDL::IOStreamRef::GetStatus ( ) const

inline

This information can be useful to decide if a short read or write was due to an error, an EOF, or a non-blocking operation that isn't yet ready to complete.

An IOStreamRef's status is only expected to change after a IOStreamRef.Read or IOStreamRef.Write call; don't expect it to change if you just call this query function in a tight loop.

Returns: an IOStatus enum with the current state.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ LoadFile()

StringResult SDL::IOStreamRef::LoadFile ( )

inline

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported via datasize.

Returns: the data in bytes

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadFile; IOStreamRef.SaveFile

◆ LoadFileAs()

template<class T >

OwnArray< T > SDL::IOStreamRef::LoadFileAs ( )

inline

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported via datasize.

Returns: the data in bytes

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadFile; IOStreamRef.SaveFile

◆ print()

size_t SDL::IOStreamRef::print	(	std::string_view	fmt,
		auto...	args
	)

inline

Category:: Formatted string

◆ printf()

size_t SDL::IOStreamRef::printf	(	SDL_PRINTF_FORMAT_STRING const char *	fmt,
			...
	)

inline

Warning: this is not typesafe! Prefer using print() and println()

This function does formatted printing to the stream.

Parameters

fmt	a printf() style format string.
...	additional parameters matching % tokens in the `fmt` string, if any.

Returns: the number of bytes written or 0 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.vprintf; IOStreamRef.Write

◆ println()

size_t SDL::IOStreamRef::println	(	std::string_view	fmt,
		auto...	args
	)

inline

Category:: Formatted string

◆ Read() [1/2]

std::string SDL::IOStreamRef::Read ( size_t size = -1 )

inline

This function reads up size bytes from the data source to the area pointed at by ptr. This function may read less bytes than requested.

This function will return zero when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If zero is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

size	the number of bytes to read from the data source.

Returns: the bytes, or empty string on end of file or other failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.Write; IOStreamRef.GetStatus

◆ Read() [2/2]

size_t SDL::IOStreamRef::Read ( TargetBytes buf )

inline

This function reads up size bytes from the data source to the area pointed at by ptr. This function may read less bytes than requested.

This function will return zero when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If zero is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

buf	the buffer to read data into.

Returns: the number of bytes read, or 0 on end of file or other failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.Write; IOStreamRef.GetStatus

◆ ReadS16BE()

Sint16 SDL::IOStreamRef::ReadS16BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS16LE()

Sint16 SDL::IOStreamRef::ReadS16LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS32BE()

Sint32 SDL::IOStreamRef::ReadS32BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS32LE()

Sint32 SDL::IOStreamRef::ReadS32LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS64BE()

Sint64 SDL::IOStreamRef::ReadS64BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS64LE()

Sint64 SDL::IOStreamRef::ReadS64LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS8()

Sint8 SDL::IOStreamRef::ReadS8 ( )

inline

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU16BE()

Uint16 SDL::IOStreamRef::ReadU16BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU16LE()

Uint16 SDL::IOStreamRef::ReadU16LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU32BE()

Uint32 SDL::IOStreamRef::ReadU32BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU32LE()

Uint32 SDL::IOStreamRef::ReadU32LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU64BE()

Uint64 SDL::IOStreamRef::ReadU64BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU64LE()

Uint64 SDL::IOStreamRef::ReadU64LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU8()

Uint8 SDL::IOStreamRef::ReadU8 ( )

inline

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ reset()

static void SDL::IOStreamRef::reset ( SDL_IOStream * resource )

inlinestatic

IOStream.Close() closes and cleans up the IOStreamRef stream. It releases any resources used by the stream and frees the IOStreamRef itself. This returns true on success, or false if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream for any reason, this function reports an error, but the IOStreamRef is still invalid once this function returns.

This call flushes any buffered writes to the operating system, but there are no guarantees that those writes have gone to physical media; they might be in the OS's file cache, waiting to go to disk later. If it's absolutely crucial that writes go to disk immediately, so they are definitely stored even if the power fails before the file cache would have caught up, one should call IOStreamRef.Flush() before closing. Note that flushing takes time and makes the system and your app operate less efficiently, so do so sparingly.

Parameters

resource IOStreamRef structure to close.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Open

◆ SaveFile()

void SDL::IOStreamRef::SaveFile ( SourceBytes data )

inline

Parameters

data	the buf to be written. If datasize is 0, may be nullptr or a invalid pointer.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SaveFile; IOStreamRef.LoadFile

◆ Seek()

Sint64 SDL::IOStreamRef::Seek	(	Sint64	offset,
		IOWhence	whence
	)

inline

This function seeks to byte offset, relative to whence.

whence may be any of the following values:

IO_SEEK_SET: seek from the beginning of data
IO_SEEK_CUR: seek relative to current read point
IO_SEEK_END: seek relative to the end of data

If this stream can not seek, it will return -1.

Parameters

offset	an offset in bytes, relative to `whence` location; can be negative.
whence	any of `IO_SEEK_SET`, `IO_SEEK_CUR`, `IO_SEEK_END`.

Returns: the final offset in the data stream after the seek or -1 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.Tell

◆ Tell()

Sint64 SDL::IOStreamRef::Tell ( ) const

inline

IOStreamRef.Tell is actually a wrapper function that calls the IOStreamRef's seek method, with an offset of 0 bytes from IO_SEEK_CUR, to simplify application development.

Returns: the current offset in the stream, or -1 if the information can not be determined.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.Seek

◆ TryReadS16BE()

std::optional< Sint16 > SDL::IOStreamRef::TryReadS16BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS16LE()

std::optional< Sint16 > SDL::IOStreamRef::TryReadS16LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS32BE()

std::optional< Sint32 > SDL::IOStreamRef::TryReadS32BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS32LE()

std::optional< Sint32 > SDL::IOStreamRef::TryReadS32LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS64BE()

std::optional< Sint64 > SDL::IOStreamRef::TryReadS64BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS64LE()

std::optional< Sint64 > SDL::IOStreamRef::TryReadS64LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS8()

std::optional< Sint8 > SDL::IOStreamRef::TryReadS8 ( )

inline

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU16BE()

std::optional< Uint16 > SDL::IOStreamRef::TryReadU16BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU16LE()

std::optional< Uint16 > SDL::IOStreamRef::TryReadU16LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU32BE()

std::optional< Uint32 > SDL::IOStreamRef::TryReadU32BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU32LE()

std::optional< Uint32 > SDL::IOStreamRef::TryReadU32LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU64BE()

std::optional< Uint64 > SDL::IOStreamRef::TryReadU64BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU64LE()

std::optional< Uint64 > SDL::IOStreamRef::TryReadU64LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU8()

std::optional< Uint8 > SDL::IOStreamRef::TryReadU8 ( )

inline

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ vprintf()

size_t SDL::IOStreamRef::vprintf	(	SDL_PRINTF_FORMAT_STRING const char *	fmt,
		va_list	ap
	)

inline

Warning: this is not typesafe! Prefer using print() and println()

This function does formatted printing to the stream.

Parameters

fmt	a printf() style format string.
ap	a variable argument list.

Returns: the number of bytes written or 0 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.printf; IOStreamRef.Write

◆ Write()

size_t SDL::IOStreamRef::Write ( SourceBytes buf )

inline

This function writes exactly size bytes from the area pointed at by ptr to the stream. If this fails for any reason, it'll return less than size to demonstrate how far the write progressed. On success, it returns size.

On error, this function still attempts to write as much as possible, so it might return a positive value less than the requested write size.

The caller can use IOStreamRef.GetStatus() to determine if the problem is recoverable, such as a non-blocking write that can simply be retried later, or a fatal error.

Parameters

buf	the bytes to write to

Returns: the number of bytes written, which will be less than size on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStreamRef.printf; IOStreamRef.Read; IOStreamRef.Seek; IOStreamRef.Flush; IOStreamRef.GetStatus

◆ WriteS16BE()

void SDL::IOStreamRef::WriteS16BE ( Sint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS16LE()

void SDL::IOStreamRef::WriteS16LE ( Sint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS32BE()

void SDL::IOStreamRef::WriteS32BE ( Sint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS32LE()

void SDL::IOStreamRef::WriteS32LE ( Sint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS64BE()

void SDL::IOStreamRef::WriteS64BE ( Sint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS64LE()

void SDL::IOStreamRef::WriteS64LE ( Sint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS8()

void SDL::IOStreamRef::WriteS8 ( Sint8 value )

inline

Parameters

value the byte value to write.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU16BE()

void SDL::IOStreamRef::WriteU16BE ( Uint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU16LE()

void SDL::IOStreamRef::WriteU16LE ( Uint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU32BE()

void SDL::IOStreamRef::WriteU32BE ( Uint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU32LE()

void SDL::IOStreamRef::WriteU32LE ( Uint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU64BE()

void SDL::IOStreamRef::WriteU64BE ( Uint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU64LE()

void SDL::IOStreamRef::WriteU64LE ( Uint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU8()

void SDL::IOStreamRef::WriteU8 ( Uint8 value )

inline

Parameters

value the byte value to write.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

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

SDL3pp/SDL3pp_iostream.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Flush()

◆ GetProperties()

◆ GetSize()

◆ GetStatus()

◆ LoadFile()

◆ LoadFileAs()

◆ print()

◆ printf()

◆ println()

◆ Read() [1/2]

◆ Read() [2/2]

◆ ReadS16BE()

◆ ReadS16LE()

◆ ReadS32BE()

◆ ReadS32LE()

◆ ReadS64BE()

◆ ReadS64LE()

◆ ReadS8()

◆ ReadU16BE()

◆ ReadU16LE()

◆ ReadU32BE()

◆ ReadU32LE()

◆ ReadU64BE()

◆ ReadU64LE()

◆ ReadU8()

◆ reset()

◆ SaveFile()

◆ Seek()

◆ Tell()

◆ TryReadS16BE()

◆ TryReadS16LE()

◆ TryReadS32BE()

◆ TryReadS32LE()

◆ TryReadS64BE()

◆ TryReadS64LE()

◆ TryReadS8()

◆ TryReadU16BE()

◆ TryReadU16LE()

◆ TryReadU32BE()

◆ TryReadU32LE()

◆ TryReadU64BE()

◆ TryReadU64LE()

◆ TryReadU8()

◆ vprintf()

◆ Write()

◆ WriteS16BE()

◆ WriteS16LE()

◆ WriteS32BE()

◆ WriteS32LE()

◆ WriteS64BE()

◆ WriteS64LE()

◆ WriteS8()

◆ WriteU16BE()

◆ WriteU16LE()

◆ WriteU32BE()

◆ WriteU32LE()

◆ WriteU64BE()

◆ WriteU64LE()

◆ WriteU8()