class io.File

Overview

This class provides a standard synchronous interface for reading from and writing to files or devices. More…

import "io_base.jncx"
import "io_File.jnc"

class File {
    // fields

    bool readonly m_isOpen;

    // properties

    uintptr_t const property m_osHandle;
    io.FileKind const property m_kind;
    uint64_t const property m_size;
    uint64_t property m_position;

    // construction

    construct();
    destruct();

    // methods

    bool errorcode open(
        string_t name,
        io.FileOpenFlags flags = 0
    );

    void close();
    bool errorcode setSize(uint64_t size);

    size_t errorcode read(
        void* p,
        size_t size
    );

    size_t errorcode write(
        void const* p,
        size_t size
    );

    bool errorcode flush();

    // aliases

    alias dispose = close;
};

Detailed Documentation

This class provides a standard synchronous interface for reading from and writing to files or devices.

All the methods of this class are mapped directly to underlying Operating System API(not to the C-runtime library). A typical sequence of steps when working with a file usually looks like this:

  • Open a file with open method;

  • Read from the file using read method;

  • Write to the file using write method;

  • Close the file with close method.

It’s recommended to use disposable pattern when working with local file variables. Whether or not to use exception semantics or a traditional error code depends on what deems to be more convenient in each particular case.

Sample code:

void foo(void const* data) {
    disposable io.File file;
    file.open("data.txt");
    file.write(data, dynamic sizeof(data));
    // ...

catch:
    // handle the error
} // file will be closed no matter how we leave the function

See also:

io.FileStream, io.MappedFile

Fields

bool readonly m_isOpen

Holds the open status for the file, i.e. true if opened; false otherwise.

Properties

uint64_t const property m_size

This property is used for getting and setting file size.

Reading from this property returns current size of the file; writing to it sets new size [1].

uint64_t property m_position

This property is used for getting and setting [1] current file position, i.e. the offset at which file contents will be accessed by read and write methods.

Accessing this property for sequential devices(which do not support access at random-offset) likely results in exception being thrown (unless the underlying OS silently ignores position read/write and does not return any IO error).

Methods

bool errorcode open(
    string_t name,
    io.FileOpenFlags flags = 0
)

Opens or creates a file or device.

The function accepts two arguments. The first one, name specifies the name of the file/device. The second one, flags, can be used to specify open options. Check io.FileOpenFlags for the complete list of options.

Returns true on success. If file or device could not be opened, IO error supplied by operating system is set and then the function returns false [2].

void close()

Closes a previously opened file, does nothing if the file is not opened. This function always succeeds.

Sometimes it may be convenient to use disposable pattern to ensure timely invokation of close [3].

size_t errorcode read(
    void* p,
    size_t size
)

Attempts to read up to size bytes from file into the buffer pointed to by p.

Returns the actual amount of bytes read or -1 if error occurs.

If read operation is unsuccessful, IO error supplied by the operating system is set and then the function returns -1 [2].

If this function is called when there is no incoming data on the opened device, it blocks until either the data arrives, or the file is closed.

size_t errorcode write(
    void const* p,
    size_t size
)

Attempts to write size bytes from the buffer pointed to by p into the file.

Returns the actual amount of bytes written on success. If write operation is unsuccessful, IO error supplied by the operating system is set and then the function returns -1 [2].

Aliases

alias dispose = close

Effectively makes io.File a disposable class [3].

Footnotes