I/O Streams

SDL provides an abstract interface for reading and writing data streams. More...

Classes
struct	SDL::IOStreamBase
	The read/write operation structure. More...
struct	SDL::IOStreamRef
	Handle to a non owned iOStream. More...
struct	SDL::IOStream
	Handle to an owned iOStream. More...

Typedefs
using	SDL::IOStatus = SDL_IOStatus
	IOStreamBase status, set by a read or write operation.
using	SDL::IOWhence = SDL_IOWhence
	Possible whence values for IOStreamBase seeking.
using	SDL::IOStreamInterface = SDL_IOStreamInterface
	The function pointers that drive an IOStreamBase.

Functions
IOStream	SDL::IOFromMem (TargetBytes mem)
	Use this function to prepare a read-write memory buffer for use with IOStreamBase.
IOStream	SDL::IOFromConstMem (SourceBytes mem)
	Use this function to prepare a read-only memory buffer for use with IOStreamBase.
IOStream	SDL::IOFromDynamicMem ()
	Use this function to create an IOStreamBase that is backed by dynamically allocated memory.
StringResult	SDL::LoadFile (StringParam file)
	Load all the data from a file path.
template<class T >
OwnArray< T >	SDL::LoadFileAs (StringParam file)
	Load all the data from a file path.
void	SDL::SaveFile (StringParam file, SourceBytes data)
	Save all the data into a file path.

Variables
constexpr IOStatus	SDL::IO_STATUS_READY
	Everything is ready (no errors and not EOF).
constexpr IOStatus	SDL::IO_STATUS_ERROR
	Read or write I/O error.
constexpr IOStatus	SDL::IO_STATUS_EOF = SDL_IO_STATUS_EOF
	End of file.
constexpr IOStatus	SDL::IO_STATUS_NOT_READY
	Non blocking I/O, not ready.
constexpr IOStatus	SDL::IO_STATUS_READONLY
	Tried to write a read-only buffer.
constexpr IOStatus	SDL::IO_STATUS_WRITEONLY
	Tried to read a write-only buffer.
constexpr IOWhence	SDL::IO_SEEK_SET
	Seek from the beginning of data.
constexpr IOWhence	SDL::IO_SEEK_CUR
	Seek relative to current read point.
constexpr IOWhence	SDL::IO_SEEK_END
	Seek relative to the end of data.

Detailed Description

It offers implementations for files, memory, etc, and the app can provide their own implementations, too.

SDL_IOStream is not related to the standard C++ iostream class, other than both are abstract interfaces to read/write data.

Typedef Documentation

IOStatus

using SDL::IOStatus = typedef SDL_IOStatus

Since

This enum is available since SDL 3.2.0.

IOStreamInterface

using SDL::IOStreamInterface = typedef SDL_IOStreamInterface

Applications can provide this struct to IOStreamBase.IOStreamBase() to create their own implementation of IOStreamBase. This is not necessarily required, as SDL already offers several common types of I/O streams, via IOStreamBase.IOStreamBase().

This structure should be initialized using SDL_INIT_INTERFACE()

Since

This struct is available since SDL 3.2.0.

See also

SDL_INIT_INTERFACE

IOWhence

using SDL::IOWhence = typedef SDL_IOWhence

These map to the same "whence" concept that fseek or lseek use in the standard C runtime.

Since

This enum is available since SDL 3.2.0.

Function Documentation

IOFromConstMem()

IOStream SDL::IOFromConstMem ( SourceBytes  mem )

inline

This function sets up an IOStreamBase struct based on a memory area of a certain size. It assumes the memory area is not writable.

Attempting to write to this IOStreamBase stream will report an error without writing to the memory buffer.

This memory buffer is not copied by the IOStreamBase; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to write to a memory buffer, you should use IOFromMem() with a writable buffer of memory instead.

The following properties will be set at creation time by SDL:

• prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
• prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a read-only buffer to feed an IOStreamBase stream.

Returns

a valid IOStream on success.

Exceptions

Error

on failure.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

IOFromMem

IOStreamRef.Close

IOStreamBase.Read

IOStreamBase.Seek

IOStreamBase.Tell

IOFromDynamicMem()

IOStream SDL::IOFromDynamicMem ( )

inline

This supports the following properties to provide access to the memory and control over allocations:

• prop::IOStream.DYNAMIC_MEMORY_POINTER: a pointer to the internal memory of the stream. This can be set to nullptr to transfer ownership of the memory to the application, which should free the memory with free(). If this is done, the next operation on the stream must be IOStreamRef.Close().
• prop::IOStream.DYNAMIC_CHUNKSIZE_NUMBER: memory will be allocated in multiples of this size, defaulting to 1024.

Returns

a valid IOStream on success.

Exceptions

Error

on failure.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

IOStreamRef.Close

IOStreamBase.Read

IOStreamBase.Seek

IOStreamBase.Tell

IOStreamBase.Write

IOFromMem()

IOStream SDL::IOFromMem ( TargetBytes  mem )

inline

This function sets up an IOStreamBase struct based on a memory area of a certain size, for both read and write access.

This memory buffer is not copied by the IOStreamBase; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to make sure the IOStreamBase never writes to the memory buffer, you should use IOFromConstMem() with a read-only buffer of memory instead.

The following properties will be set at creation time by SDL:

• prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
• prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a buffer to feed an IOStreamBase stream.

Returns

a valid IOStream on success.

Exceptions

Error

on failure.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

IOFromConstMem

IOStreamRef.Close

IOStreamBase.Flush

IOStreamBase.Read

IOStreamBase.Seek

IOStreamBase.Tell

IOStreamBase.Write

LoadFile()

StringResult SDL::LoadFile ( StringParam  file )

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.

Parameters

file	the path to read all available data from.

Returns

the data.

Exceptions

Error

on failure.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

See also

IOStreamBase.LoadFile

SaveFile

LoadFileAs()

template<class T >

OwnArray< T > SDL::LoadFileAs ( StringParam  file )

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.

Parameters

file	the path to read all available data from.

Returns

the data.

Exceptions

Error

on failure.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

See also

IOStreamBase.LoadFile

SaveFile

SaveFile()

void SDL::SaveFile ( StringParam  file, SourceBytes  data  )

inline

Parameters

file	the path to write all available data into.
data	the data 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

IOStreamBase.SaveFile

LoadFile

Variable Documentation

IO_SEEK_CUR

constexpr IOWhence SDL::IO_SEEK_CUR

constexpr

Initial value:

=
  SDL_IO_SEEK_CUR

IO_SEEK_END

constexpr IOWhence SDL::IO_SEEK_END

constexpr

Initial value:

=
  SDL_IO_SEEK_END

IO_SEEK_SET

constexpr IOWhence SDL::IO_SEEK_SET

constexpr

Initial value:

=
  SDL_IO_SEEK_SET

IO_STATUS_ERROR

constexpr IOStatus SDL::IO_STATUS_ERROR

constexpr

Initial value:

=
  SDL_IO_STATUS_ERROR

IO_STATUS_NOT_READY

constexpr IOStatus SDL::IO_STATUS_NOT_READY

constexpr

Initial value:

=
  SDL_IO_STATUS_NOT_READY

IO_STATUS_READONLY

constexpr IOStatus SDL::IO_STATUS_READONLY

constexpr

Initial value:

=
  SDL_IO_STATUS_READONLY

IO_STATUS_READY

constexpr IOStatus SDL::IO_STATUS_READY

constexpr

Initial value:

=
  SDL_IO_STATUS_READY

IO_STATUS_WRITEONLY

constexpr IOStatus SDL::IO_STATUS_WRITEONLY

constexpr

Initial value:

=
  SDL_IO_STATUS_WRITEONLY