WriteTextAtomic ( file$,text$ )
Parameters
|
file$ - destination path text$ - the text to write, as strict UTF-8 |
Description
|
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. Requires Extended mode. See also: WriteBankAtomic, SaveJsonAtomic, CreateDirTree, FilesystemError, Sha256File. |
Example
; WriteTextAtomic Example ; ----------------------- ; Requires Extended mode. ; 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
Index