Binary

// A text file stores numbers as digits. A binary file stores the bytes of the values themselves:
// a `uint16` is always two bytes, a `uint32` four and a `float64` eight, however large the
// value. Every record has the same size, so a reader knows exactly how many bytes to expect.
//
// `Io` has a function pair for each fixed-width type, such as `WriteUint32` and `ReadUint32`.
// Each takes an `Endian` naming the byte order; the Endian lesson explains why that must be
// stated. Here the format simply says little endian, on both sides.
//
// The real lesson is about bytes that do not arrive. `File::Read` is one attempt and may return
// fewer bytes than asked; at the end of a file it fails with `EndOfStream`. The fixed-width
// functions are built on `ReadExact` and `WriteAll`, which keep calling until every byte of the
// value has moved. If the stream ends part-way through a value, `ReadUint32` fails instead of
// assembling a number from the bytes it got plus whatever was in memory. A short file is an
// error to report, never a value to guess.
//
// The file lives in this package's `Bin/` folder, and the program deletes it at the end.
import Allocator::{ Allocator, SystemAllocator };
import FileSystem::{ DeleteFile, File, OpenOptions };
import Io::{ Endian, IoError, PrintLine, ReadFloat64, ReadUint16, ReadUint32, WriteFloat64,
             WriteUint16, WriteUint32 };
import Path::{ OsString, Path };
import Text::TextError;

// Reads one record. Any field that cannot be read whole fails the whole record.
func ReadRecord(file: &var File) -> ! IoError {
    let version = ReadUint16(file, Endian::Little)?;
    let count = ReadUint32(file, Endian::Little)?;
    let average = ReadFloat64(file, Endian::Little)?;
    PrintLine("  version {}, count {}, average {}", version, count, average);
}

// Opens the file, reads a record from it, and reports a short file instead of passing it on.
func ShowRecord(allocator: Allocator, path: Path) -> ! IoError {
    var reading = File::Open(allocator, path, OpenOptions::Reading())?;
    PrintLine("{} holds {} bytes", path, reading.Size()?);
    ReadRecord(reading) catch {
        error if error.IsEnd() => {
            PrintLine("  the file ends inside a field: record refused");
        },
        error => fail error
    };
    reading.Close()?;
}

func Main() -> ! IoError | TextError {
    var system = SystemAllocator();
    let allocator: Allocator = system;
    var holder = OsString::FromText(allocator, "Bin/record.bin")?;
    let path = Path::FromView(holder.View());

    // 2 + 4 + 8 bytes: fourteen, whatever the values are.
    var writing = File::Open(allocator, path, OpenOptions::Writing())?;
    WriteUint16(writing, Endian::Little, 3)?;
    WriteUint32(writing, Endian::Little, 1200000)?;
    WriteFloat64(writing, Endian::Little, 2.75)?;
    writing.Close()?;
    ShowRecord(allocator, path)?;

    // Cut the file in the middle of the last field, as a crash part-way through writing might
    // have left it. Plain `write` permission, without `Writing`'s emptying of the file.
    var options = OpenOptions();
    options.write = true;
    var cutting = File::Open(allocator, path, options)?;
    cutting.SetLength(10)?;
    cutting.Close()?;
    ShowRecord(allocator, path)?;

    DeleteFile(allocator, path)?;
}