|
file$ - destination path text$ - the text to write, as strict UTF-8 |
|
Atomically writes a String's exact UTF-8 bytes to a file. "Atomic" is what it buys your game: the text is written to a hidden sibling file in the same directory, flushed, closed, and only then published over the destination with write-through semantics. A crash or power cut mid-save can never leave a truncated or half-written file - readers see the complete old file or the complete new file, and a failed write leaves the previous file untouched, with no delete-then-rename window. That is the difference between "the save got lost" and "the save quietly rolled back one version". The bytes are exact: strict UTF-8, no BOM, no newline conversion, nothing appended. What you wrote is what Sha256File hashes and what ReadFile reads back. Because of that strictness, text that is not valid UTF-8 is refused up front - the write returns 0 without touching the destination. 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. For JSON documents prefer SaveJsonAtomic, and for binary data use WriteBankAtomic. 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. See also: WriteBankAtomic, SaveJsonAtomic, CreateDirTree, FilesystemError, Sha256File. |
; WriteTextAtomic Example
; -----------------------
; A message-of-the-day file for our game launcher
motd$="Welcome to Dragon Keep!"+Chr(10)+"Double XP all weekend."
; WriteTextAtomic writes the exact UTF-8 bytes to a hidden sibling
; file, then atomically replaces the destination - readers see the
; old file or the new file, never a half-written mixture.
If WriteTextAtomic("motd_example.txt",motd)=0 Then RuntimeError FilesystemError()
Print "Wrote motd_example.txt ("+FileSize("motd_example.txt")+" bytes)"
Print "No BOM and no newline conversion - the bytes are exact."
Print ""
; Read the file back to show what landed on disk
file=ReadFile("motd_example.txt")
Print "File contents:"
While Not Eof(file)
Print " "+ReadLine(file)
Wend
CloseFile file
; Clean up the file this example created
DeleteFile "motd_example.txt"
Print ""
Print "Press any key to close the example"
WaitKey
End