Filesystem » CnxFile module

enum CnxFileAccessMode

#include <include/Cnx/filesystem/File.h>

Use in a CnxFileOptions to specify the access mode a file should be opened with.

enum CnxFileOpenBehavior

#include <include/Cnx/filesystem/File.h>

Use in a CnxFileOptions to specify the behavior a file should be opened with.

enum CnxFileSeekOrigin

#include <include/Cnx/filesystem/File.h>

Use to identify where a seek should begin from when seeking in a CnxFile

typedef charFileBuffer[]

#include <include/Cnx/filesystem/File.h>

Basic buffer type used to provide buffered for a CnxFile

typedef enum CnxFileAccessMode CnxFileAccessMode

#include <include/Cnx/filesystem/File.h>

Use in a CnxFileOptions to specify the access mode a file should be opened with.

typedef enum CnxFileOpenBehavior CnxFileOpenBehavior

#include <include/Cnx/filesystem/File.h>

Use in a CnxFileOptions to specify the behavior a file should be opened with.

typedef struct CnxFileOptions CnxFileOptions

#include <include/Cnx/filesystem/File.h>

Use to specify the access mode and behavior a file should be opened with.

typedef struct CnxFile CnxFile

#include <include/Cnx/filesystem/File.h>

Cnx type used to manage reading and writing to/from a file, the buffering associated with the file, and closing it when it's no longer used.

Example:

#include <Cnx/filesystem/File.h>

void example(void) {
    let_mut maybe_file = cnx_file_open("my_file.txt");
    cnx_assert(cnx_result_is_ok(maybe_file), "Failed to open my_file.txt");
    CnxScopedFile file = cnx_result_unwrap(maybe_file);
    let my_important_number = 42;
    let my_important_float 24.0F;
    cnx_file_println(&file, "number: {}, float: {}", my_important_number, my_important_float);

    let_mut maybe_file2 = cnx_file_open("my_other_file.txt");
    cnx_assert(cnx_result_is_ok(maybe_file2), "Failed to open my_other_file.txt");
    CnxScopedFile file2 = cnx_result_unwrap(maybe_file2);
    let_mut maybe_read = cnx_file_read_line(&file2);
    if(cnx_result_is_ok(maybe_read)) {
        CnxScopedString str = cnx_result_unwrap(maybe_read);
        // do something with the line read from `my_other_file.txt`
    }

    // files automatically closed when they leave scope because they were declared as
    // `CnxScopedFile`
}

typedef enum CnxFileSeekOrigin CnxFileSeekOrigin

#include <include/Cnx/filesystem/File.h>

Use to identify where a seek should begin from when seeking in a CnxFile

static void file_deleter(FILE*restrict file, CnxAllocator allocator)

#include <include/Cnx/filesystem/File.h>

CnxDeleter function for smart pointers managing FILE*s

CnxResult(i32) cnx_file_write_bytes(CnxFile *restrict file

#include <include/Cnx/filesystem/File.h>

Writes the given bytes to the file.

Attempts to write bytes in the given byte array, bytes to the file. Writing will fail if file was not opened with write access permissions or for any reason fwrite or similar libc functions may fail

CnxResult(CnxString) cnx_file_read(CnxFile *restrict file

#include <include/Cnx/filesystem/File.h>

Reads num_chars characters from file and returns them in a CnxString

Reads a line of text from file and returns it in a CnxString

Reads num_chars characters from file and returns them in a CnxString allocated with the given memory allocator.

Attempts to read num_chars characters from file, returning the result in a CnxString. May read less than num_chars characters if EOF is reached. Reading will fail if the file was not opened with read access permissions or for any reason fread or similar libc functions may fail.

Attempts to read num_chars characters from file, returning the result in a CnxString allocated with the given memory allocator. May read less than num_chars characters if EOF is reached. Reading will fail if the file was not opened with read access permissions or for any reason fread or similar libc functions may fail.

Attempts to read a line of text from file, returning the result in a CnxString. May read less than a line if EOF is reached before a newline is encountered. Reading will fail if the file was not opened with read access permissions or for any reason fread or similar libc functions may fail.

Attempts to read a line of text from file, returning the result in a CnxString. May read less than a line if EOF is reached before a newline is encountered. Reading will fail if the file was not opened with read access permissions or for any reason fread or similar libc functions may fail.

CnxResult(usize) cnx_file_read_bytes(CnxFile *restrict file

#include <include/Cnx/filesystem/File.h>

Reads up to max_num_bytes bytes from file and writes them to bytes, returning the number of bytes read.

Attempts to read up to max_num_bytes bytes from file, and writes them to bytes. May read less than max_num_bytes bytes if EOF is reached. Returns the number of bytes read when successful. Reading will fail if the file was not opened with read access permissions or for any reason fread or similar libc functions may fail.

CnxResult cnx_file_flush(CnxFile*restrict file)

#include <include/Cnx/filesystem/File.h>

Flushes the given file.

Attempts to flush the given file. Flushing may fail for any reason fflush from libc may fail.

CnxResult cnx_file_seek(CnxFile*restrict file, i64 offset, CnxFileSeekOrigin origin)

#include <include/Cnx/filesystem/File.h>

Seeks to the given location in the file

Attempts to seek to the location indicated by origin and offset in the file. May fail for any reason fseek from libc may fail.

void cnx_file_close(CnxFile*restrict file)

#include <include/Cnx/filesystem/File.h>

Closes the given file

Closes the given file, freeing the allocated buffer and any operating system level resources associated with the file.

#define CnxScopedFile

#include <include/Cnx/filesystem/File.h>

Declare a CnxFile with this to ensure that it's automatically closed when it leaves its containing scope.

Example:

#include <Cnx/filesystem/File.h>

void example(void) {
    let_mut maybe_file = cnx_file_open("my_file.txt");
    cnx_assert(cnx_result_is_ok(maybe_file), "Failed to open my_file.txt");
    CnxScopedFile file = cnx_result_unwrap(maybe_file);
    let my_important_number = 42;
    let my_important_float 24.0F;
    cnx_file_println(&file, "number: {}, float: {}", my_important_number, my_important_float);

    let_mut maybe_file2 = cnx_file_open("my_other_file.txt");
    cnx_assert(cnx_result_is_ok(maybe_file2), "Failed to open my_other_file.txt");
    CnxScopedFile file2 = cnx_result_unwrap(maybe_file2);
    let_mut maybe_read = cnx_file_read_line(&file2);
    if(cnx_result_is_ok(maybe_read)) {
        CnxScopedString str = cnx_result_unwrap(maybe_read);
        // do something with the line read from `my_other_file.txt`
    }

    // files automatically closed when they leave scope because they were declared as
    // `CnxScopedFile`
}

#define CNX_FILE_DEFAULT_OPTIONS

#include <include/Cnx/filesystem/File.h>

The default options used to open a CnxFile

The default behavior for opening a file with Cnx is to open in read/write mode, truncate contents on opening, and create a new file if one didn't already exist (equivalent to "w+")

#define CNX_FILE_DEFAULT_BUFFER_SIZE

#include <include/Cnx/filesystem/File.h>

The default buffer size used for newly opened CnxFiles.

This is the default buffer size used for newly opened CnxFiles. It can be overridden by explicitly passing buffer_size to cnx_file_open.

On Windows or MacOS, this is 8K. On other platforms this will be equivalent to that platform's BUFSIZ

#define cnx_file_open(...)

#include <include/Cnx/filesystem/File.h>

Opens the file at the given path, using the default allocator to allocate the memory used for buffering.

Attempts to open the file at the given path. path must be a valild path for a file. By default, this uses CNX_FILE_DEFAULT_OPTIONS for options, the CnxFileOptions indicating file opening permissions and behavior, and CNX_FILE_DEFAULT_BUFFER_SIZE for buffer_size, the buffer size to allocate and use for buffering in the file. Both of these can be passed explicit values to override this behavior, however.

options must be a valid combination of CnxFileAccessMode and CnxFileOpenBehavior. For example, CnxFileRead combined with CnxFileTruncate would be an invalid pairing, and would result in this returning an error. Valid combinations are those equivalent to a valid mode for fopen.

#define cnx_file_open_with_allocator(...)

#include <include/Cnx/filesystem/File.h>

Opens the file at the given path, using the given allocator to allocate the memory used for buffering.

Attempts to open the file at the given path. path must be a valild path for a file. By default, this uses CNX_FILE_DEFAULT_OPTIONS for options, the CnxFileOptions indicating file opening permissions and behavior, and CNX_FILE_DEFAULT_BUFFER_SIZE for buffer_size, the buffer size to allocate and use for buffering in the file. Both of these can be passed explicit values to override this behavior, however.

options must be a valid combination of CnxFileAccessMode and CnxFileOpenBehavior. For example, CnxFileRead combined with CnxFileTruncate would be an invalid pairing, and would result in this returning an error. Valid combinations are those equivalent to a valid mode for fopen.

#define cnx_file_print(file, format_string, ...)

#include <include/Cnx/filesystem/File.h>

Prints the string resulting from formatting format_string and the formatting arguments to the given file.

Attempts to write the string resulting from formatting to the file. Writing will fail if file was not opened with write access permissions or for any reason fwrite or similar libc functions may fail

#define cnx_file_println(file, format_string, ...)

#include <include/Cnx/filesystem/File.h>

Prints the string resulting from formatting format_string and the formatting arguments to the given file, followed by a newline.

Attempts to write the string resulting from formatting, followed by a newline, to the file. Writing will fail if file was not opened with write access permissions or for any reason fwrite or similar libc functions may fail

#define cnx_file_print_with_allocator(file, allocator, format_string, ...)

#include <include/Cnx/filesystem/File.h>

Prints the string resulting from formatting format_string and the formatting arguments to the given file, using the provided allocator for any memory allocations necessary to perform the string formatting.

Attempts to write the string resulting from formatting to the file. Writing will fail if file was not opened with write access permissions or for any reason fwrite or similar libc functions may fail

#define cnx_file_println_with_allocator(file, allocator, format_string, ...)

#include <include/Cnx/filesystem/File.h>

Prints the string resulting from formatting format_string and the formatting arguments to the given file, followed by a newline. Uses the provided allocator for any memory allocations necessary to perform the string formatting.

Attempts to write the string resulting from formatting, followed by a newline, to the file. Writing will fail if file was not opened with write access permissions or for any reason fwrite or similar libc functions may fail

#define cnx_file_is_symlink(file)

#include <include/Cnx/filesystem/File.h>

Returns whether the given file is actually symbolic link.

#define cnx_file_has_extension(file, extension)

#include <include/Cnx/filesystem/File.h>

Returns whether the given file has the given file extension.

#define cnx_file_get_extension(file)

#include <include/Cnx/filesystem/File.h>

Returns the file extension of the given file

Attempts to get the file extension of the given file. If it does not have a file extension, then this will return None().

#define cnx_file_get_name(file)

#include <include/Cnx/filesystem/File.h>

Returns the file name of the given file, including the file extension, if it has one.

#define cnx_file_get_name_without_extension(file)

#include <include/Cnx/filesystem/File.h>

Returns the file name of the given file, excluding the file extension, if it has one.

#define cnx_file_get_parent_directory(file)

#include <include/Cnx/filesystem/File.h>

Returns the parent directory of the given file as an absolute path.