File

Description
The File datatype represents a file on disk and provides a set of methods to read, write, manipulate, and query files.
Files can be opened for reading, writing, or appending, and operations are available to handle file metadata such as size, existence, and names.

Typical use cases
Reading configuration files.
Logging information to text files.
Temporary data storage.
File manipulation tasks like copy, rename, or delete.

Notes
All file operations are performed in binary mode internally.
Reading functions return data as Unicode strings.
Methods generally return a success/failure boolean for file operations.
File paths are expected to be absolute or relative to the current working directory.
Methods do not throw exceptions; errors are logged and result in false or empty strings.
------------------------------------------------------------
Methods
------------------------------------------------------------

bool open(string path, string mode="r", bool create=false)

Opens a file at the given path.
Mode options: "r" = read, "w" = write, "a" = append, "rw" = read/write.
If create is true, the file will be created if it does not exist.
Returns true if the file was successfully opened.
------------------------------------------------------------
void close()

Closes the file if it is open.
After closing, read/write operations are not possible until the file is reopened.
------------------------------------------------------------
string read()

Reads the entire contents of the file and returns it as a string.
Returns an empty string if the file is not open.
------------------------------------------------------------
string readLine()

Reads the next line from the file.
Returns an empty string if the file is not open or EOF is reached.
------------------------------------------------------------
string read(int n)

Reads n characters from the file.
If fewer characters remain, returns only the remaining data.
Returns an empty string if the file is not open.
------------------------------------------------------------
bool eof()

Returns true if the end of the file has been reached.
Returns false if the file is not open.
------------------------------------------------------------
void write(string text)

Writes the given text at the current position.
Flushes the file buffer after writing.
No effect if the file is not open.
------------------------------------------------------------
void writeLine(string text)

Writes the given text followed by a newline character.
Flushes the file buffer after writing.
No effect if the file is not open.
------------------------------------------------------------
void append(string text)

Writes the given text at the end of the file.
Flushes the file buffer after writing.
No effect if the file is not open.
------------------------------------------------------------
int tell()

Returns the current position of the file pointer.
Returns -1 if the file is not open.
------------------------------------------------------------
bool seek(int pos)

Moves the file pointer to the specified position.
Returns true if successful, false if the file is not open or the position is invalid.
------------------------------------------------------------
int size()

Returns the size of the file in bytes.
Returns 0 if the file does not exist or cannot be accessed.
------------------------------------------------------------
bool exists(string path)

Returns true if a file exists at the given path.
------------------------------------------------------------
bool delete()
bool delete(string filename)

Deletes the file from disk.
If no parameter is provided, the file associated with this object is deleted.
If a filename is provided, the specified file will be deleted instead.
Returns true if deletion succeeded.
------------------------------------------------------------
bool rename(string newname)

Renames the file.
Returns true if the file was successfully renamed.
------------------------------------------------------------
bool copy(string dest)

Copies the file to the specified destination path.
Returns true if the copy succeeded.
------------------------------------------------------------
Example
void main()
{
    File file;
    string content;

    // Open for reading
    if (file.open("test.txt"))
        content = file.read();
    file.close();

    // Open for writing and create if needed
    if (file.open("output.txt", "w", true))
        file.writeLine("Hello World");
    file.close();

    // Append text
    if (file.open("output.txt", "a"))
        file.append("More text");
    file.close();

    // Check existence
    if (file.exists("output.txt"))
        Print("File exists");

    // Copy file
    file.copy("copy.txt");

    // Rename file
    file.rename("renamed.txt");

    // Delete file
    file.delete();
}