Writing files

Write bytes, text, or a kotlinx-io stream to a PlatformFile

write() and writeString() replace the content of a file, creating it if needed. For large or incremental writes, stream with sink().

​

Usage

nonWebMain

val file = FileKit.filesDir / "notes.txt"

file.writeString("Hello, FileKit!")
file.write("Hello again".encodeToByteArray())

Both are suspend functions that switch to Dispatchers.IO. The parent directory must exist: create it first with createDirectories(). Failures throw kotlinx.io.IOException or FileKitException.

These functions are not declared in commonMain. Call them from nonWebMain or a platform source set. The web has separate, experimental versions for the origin private file system: see Write on the web.

​

Copy another file’s content

write also takes a PlatformFile and streams its content into the destination, without loading it into memory:

nonWebMain

val destination = FileKit.filesDir / "copy.pdf"
destination write pickedFile

This works when the source size is unknown, as with some Android content:// files. It throws if the source is a directory or the same file as the destination. To copy into a folder or copy a whole tree, see File operations.

​

Stream with a sink

sink() returns a kotlinx-io RawSink. Pass append = true to add to the end of the file instead of replacing it:

nonWebMain

suspend fun appendLog(file: PlatformFile, line: String) = withContext(Dispatchers.IO) {
    file.sink(append = true).buffered().use { sink ->
        sink.writeString("$line\n")
    }
}

sink() does blocking I/O: call it on Dispatchers.IO, and close it with use so the data is flushed.

​

Write on the web

Browsers don’t let a page write to the user’s files. On JS and Wasm you have two options:

• Give the user a file with FileKit.download(bytes, fileName): see Download files.
• Store files in the browser’s private storage with the experimental origin private file system API, which provides its own write, writeString, and delete: see Files on the web.

​

Platform notes

Platform	Behavior
Android	Writing to a content:// file truncates it first (append = false), including on providers such as Google Drive. A file you create with / inside a picked folder is created as a new document.
iOS, macOS	Security-scoped access is started and stopped for you, also for sink() until you close it.
Web	Only origin private file system files can be written. Writing to a picked file throws.

​

Related

• Reading files
• File operations: copy, move, delete, and create directories
• File saver: let the user choose where to save