WriteBankAtomic ( file$,bank[,offset][,count] )
Parameters
|
file$ - destination path bank - Bank holding the bytes to write offset (optional) - first byte of the range; 0 (default) count (optional) - number of bytes to write; -1 writes from offset to the end (default) |
Description
|
Atomically writes an exact Bank range to a file, byte for byte. The binary sibling of WriteTextAtomic, for save headers, packed level data and any format you build in a Bank with PokeByte and PokeInt. The atomic contract is the same: the bytes go to a hidden sibling file in the same directory, get flushed and closed, and only then replace the destination with write-through semantics. A crash mid-save can never leave a truncated save on disk - readers see the complete old file or the complete new file, and a failed write leaves the previous file untouched. The write is completely byte-transparent: no BOM, no newline translation, no transformation of any kind, so a Sha256Bank digest of the range equals a Sha256File digest of the result. Offset and count select any sub-range of the Bank (count -1 means "from offset to the end"); a zero-length write is valid and publishes an empty file. An out-of-range interval is a programming error. Returns true on success; on failure it returns 0 and sets the FilesystemError diagnostics (message, code, path). Missing folders are not created - call CreateDirTree first. The guarantee covers this one file - not a multi-file transaction, and not failing hardware or unusual network filesystems. Like every write command in this family it is main-thread-only. For the full rules, see the Application Data language reference. Requires Extended mode. See also: WriteTextAtomic, SaveJsonAtomic, CreateDirTree, Sha256Bank, CreateBank. |
Example
; WriteBankAtomic Example ; ----------------------- ; Requires Extended mode. ; Build a tiny binary save header in a Bank: ; 4 magic bytes "SAVE", then a version Int, then the gold amount bank=CreateBank(12) PokeByte bank,0,Asc("S") PokeByte bank,1,Asc("A") PokeByte bank,2,Asc("V") PokeByte bank,3,Asc("E") PokeInt bank,4,3 ; Save format version PokeInt bank,8,1250 ; Gold ; WriteBankAtomic publishes the exact bytes atomically - a crash ; mid-write can never leave a truncated save on disk If WriteBankAtomic("savegame_example.bin",bank)=0 Then RuntimeError FilesystemError() Print "Wrote savegame_example.bin ("+FileSize("savegame_example.bin")+" bytes)" Print "" ; Read the file back to prove the bytes are untransformed file=ReadFile("savegame_example.bin") magic$=Chr(ReadByte(file))+Chr(ReadByte(file))+Chr(ReadByte(file))+Chr(ReadByte(file)) version=ReadInt(file) gold=ReadInt(file) CloseFile file Print "Read back - magic: "+magic+" version: "+version+" gold: "+gold FreeBank bank ; Clean up the file this example created DeleteFile "savegame_example.bin" Print "" Print "Press any key to close the example" WaitKey End
Index