File#

Fully qualified name: carb::filesystem::File

Defined in carb/filesystem/detail/IFileSystem2.h

class File#

Class representing an open file.

Public Functions

virtual void release() noexcept = 0#

Closes and destroys *this.

Call this function when you are done with *this.

Post:

*this is destroyed and must not be accessed anymore

virtual omni::expected<void, ErrorCode> close() noexcept = 0#

Closes the File.

Any further operation on the file will result in an error result.

Possible Error values

  • carb::ErrorCode InvalidOperation The file is already closed

  • Other errors based on underlying platform calls.

Returns:

void if successful, or a carb::ErrorCode indicating the outcome of the request.

virtual omni::expected<size_t, ErrorCode> getSize() noexcept = 0#

Gets the total size of the file.

Possible Error values

  • carb::ErrorCode InvalidOperation The file is already closed

  • Other errors based on underlying platform calls.

Note

Writable files will execute a flush() as part of this request.

Returns:

A size_t indicating the total size of the file in bytes if successful, or a carb::ErrorCode if an error occurs.

virtual omni::expected<FileTime, ErrorCode> getModTime() noexcept = 0#

Gets the time of last modification to the file.

Note

Writable files will execute a flush() as part of this request.

Returns:

A FileTime indicating the time this file was last modified if successful, or an carb::ErrorCode if an error occurs.

virtual omni::expected<FileTime, ErrorCode> getCreateTime(
) noexcept = 0#

Gets the time of creation of the file.

Returns:

A FileTime indicating the time this file was created if successful, or a carb::ErrorCode if an error occurs.

virtual omni::expected<size_t, ErrorCode> readChunk(
void *buffer,
size_t bytes,
) noexcept = 0#

Reads a chunk of binary data from the file.

Parameters:

  • buffer – A memory buffer to read the binary data into, must be at least bytes in size.

  • bytes – Number of bytes to read from the file into buffer.

Returns:

A size_t corresponding to the number of bytes read if successful, or a carb::ErrorCode if an error occurs.

virtual omni::expected<size_t, ErrorCode> writeChunk(
const void *buffer,
size_t bytes,
) noexcept = 0#

Writes a chunk of binary data to the file.

Parameters:

  • buffer – A memory buffer to write to the file.

  • bytes – The number of bytes from buffer to write to the file.

Returns:

A size_t corresponding to the number of bytes successfully written to the file, or an carb::ErrorCode if an error occurs. Note that the number of bytes written may be less than requested due to various reasons (i.e. disk full).

virtual omni::expected<omni::string, ErrorCode> readLine(
) noexcept = 0#

Reads a line of character data from a text file (including the \r or \n line-ending character(s) if any).

Possible Error values

  • carb::ErrorCode EndOfFile - File is at EOF (end of file)

  • carb::ErrorCode Fail - A generic error was reported while reading

  • Other errors may be reported based on the underlying platform calls

Note

This function considers a solo \n to be a line ending, as well as \r\n. A \r by itself is not considered a line ending.

Warning

This function includes the line endings, unlike the version 1.x API.

Returns:

An omni::string containing the line read from the file, if successful. The string may be empty if an empty line was read. The string may have line-ending characters at the end. If an error or end-of-file event occurs, a carb::ErrorCode is returned instead.

virtual omni::expected<void, ErrorCode> readLine(
omni::string &out,
) noexcept = 0#

Reads a line of character data from a text file (including the \r or \n line-ending character(s) if any).

Possible Error values

  • carb::ErrorCode EndOfFile - File is at EOF (end of file)

  • carb::ErrorCode Fail - A generic error was reported while reading

  • Other errors may be reported based on the underlying platform calls

Note

This function considers a solo \n to be a line ending, as well as \r\n. A \r by itself is not considered a line ending.

Note

This variation of readLine allows reading into an existing omni::string without always allocating a new one.

Warning

This function includes the line endings, unlike the version 1.x API.

Parameters:

out – An omni::string that will receive the line read from the file, overwriting the previous string. If an error occurs, this string is in a valid but undefined state. The string may have line-ending characters at the end. The line may be empty if read at the end of the file.

Returns:

void if a line was read. If an error or end-of-file event occurs, a carb::ErrorCode is returned instead.

virtual omni::expected<void, ErrorCode> writeLine(
cpp::string_view line,
) noexcept = 0#

Writes a line to the file.

Parameters:

line – The string data to write to the file. A \n will be appended to the string written to the file. If the file was opened in non-binary mode on Windows, a \r\n will be written instead.

Returns:

void if a line was written. If an error occurs a carb::ErrorCode is returned instead.

virtual omni::expected<void, ErrorCode> flush() noexcept = 0#

Flushes any unwritten data to the file.

Returns:

void if the flush was successful, or a carb::ErrorCode representing the failure.

virtual omni::expected<size_t, ErrorCode> getPosition(
) const noexcept = 0#

Retrieves the current file pointer position.

Similar to tell().

Note

The offset returned may be beyond the end of the existing file if bytes have not been written to the file or it has not been flushed.

Returns:

A size_t representing the file pointer position in bytes from the beginning of the file, or an error indicating why the file pointer could not be read.

virtual omni::expected<void, ErrorCode> setPosition(
int64_t offset,
FileWhence whence,
) noexcept = 0#

Sets the new file pointer position.

Parameters:

  • offset – the new position for the file pointer relative to the location specified by whence. This value may only be negative if whence is not FileWhence::eBegin, but the absolute position of the file may not be negative. This may specify a position beyond the current end of the file, but the file is not changed until data is written at that offset and flushed.

  • whence – the relative location to base offset from.

Returns:

void if set successfully, or a carb::ErrorCode indicating why the file pointer could not be set.

virtual omni::expected<void, ErrorCode> truncate() noexcept = 0#

Truncates the file at the current position.

The file position is set with setPosition. If the position is beyond the current end of the file, the file is filled with zero bytes. If the file is being shortened, all data in the file at and beyond the current file pointer will be removed.

Returns:

void if the truncation was successful, or a carb::ErrorCode indicating why the operation could not be completed if an error occurs.

virtual FileStatus getStatus() const noexcept = 0#

Retrieves the file status: whether at EOF, an error occurred, or no error state is recorded.

Returns:

A FileStatus indicating the current status of the file.

inline bool isEof() const noexcept#

Returns whether the file position pointer is at the end-of-file position.

Similar to C’s feof() function. Same as getStatus() == FileStatus::eEof.

Returns:

true if the file pointer is at end-of-file position. false otherwise.

inline bool isError() const noexcept#

Returns whether the file is in error state.

Similar to C’s ferror() function. Same as getStatus() == FileStatus::eError.

Returns:

true if the file is in error state. false otherwise.

virtual omni::expected<void, ErrorCode> getFileInfo(
FileInfo &info,
) noexcept = 0#

Fills a FileInfo structure with information about the file.

Parameters:

info – A reference to a structure to fill with information about the file. If an error occurs this struct is in a valid but undefined state.

Returns:

void if file info was successfully read, otherwise a carb::ErrorCode value indicating why the operation could not be completed (info is in a valid but undefined state).

inline omni::expected<void, ErrorCode> resetPositionBegin(
) noexcept#

Helper function to move the file position pointer to the beginning of the file.

Effectively return setPosition(0, FileWhence::eBegin);. See setPosition for more information.

Returns:

The result from setPosition.

inline omni::expected<void, ErrorCode> resetPositionEnd() noexcept#

Helper function to move the file position pointer to the end of the file.

Effectively return setPosition(0, FileWhence::eEnd);. See setPosition for more information.

Returns:

The result from setPosition.