feat(file): Implement character read and write functions for LocalFile

[Mauller]

• Merge Before: refactor(recorder): Replace fopen with FileSystem in Replay Recorder #1233

This PR adds extra character handling interfaces to the File class and implements the functionality into the LocalFile class.
The ram file just implements stubs that return errors if used as character handling is not required.

[xezon]

I think this should return Char.

[Mauller]

I have it replicating the behaviour of what the file stream functions do, fgetc in this case, unless we aren't bothered about replicating it?

[xezon]

Ah ok. I inquired with Chat Gippity and it appears to be ok then:

---

fgetc() returns an int instead of char for a very practical reason:

It needs to be able to represent every possible char value and an extra special value — EOF — which indicates the end of the file or an error.

---

The problem if it returned char

• Suppose char is 8 bits (typical), it can only hold values 0 to 255 (unsigned) or -128 to 127 (signed).
• EOF is defined as a negative integer (usually -1), which must be distinguishable from any valid byte value.
• If fgetc() returned char, there would be no way to tell the difference between reading a byte 0xFF (255) and EOF (−1) on systems where char is signed — they'd both appear as -1.

---

The solution

• fgetc() returns an int with a range large enough to:

  1. Represent all possible unsigned char values (0–255).
  2. Also represent EOF as a distinct value (usually -1).

---

Example

#include <stdio.h>

int main(void) {
    FILE *f = fopen("data.bin", "rb");
    int ch;

    while ((ch = fgetc(f)) != EOF) {  // ch is int, not char
        printf("Byte: %02X\n", (unsigned char)ch);
    }

    fclose(f);
}

Here:

• ch is int so it can hold EOF.
• We cast to (unsigned char) when we want to treat the result as a byte.

---

Quick summary

fgetc returns int so it can safely distinguish between any valid byte value and EOF.

If you want, I can also explain why getchar() follows the same rule and how it’s tied to the C standard’s type promotion rules — which is actually an interesting historical detail. Would you like me to go into that?

[xezon]

I think this should return the result of write instead of the character that was passed, or EOF, which is not an intuitive result.

[Mauller]

i was mostly copying what the file stream type functions return with fputc etc.
they return the character written or EOF if it failed.

[xezon]

Ok makes sense then.