Import std.io.file
std.io.file
std.io's files, a call at a time: reading and writing a whole file's bytes, text, or lines, adding to one, writing one atomically, what's at a path, and copying, moving, and deleting. Each has an Async twin, which libuv's thread pool does while the main thread goes on, and whose Await resumes there. A file that can't be used throws an IOError whose Kind says why. Open and Create give a FileStream, for reading and writing a file a part at a time.
std/io/file.fb
Types
FileKind
enum
Public Enum FileKindWhat's at a path.
-
A file.
-
A folder.
-
A link.
-
Something else, like a device or a pipe.
LineEnding
enum
Public Enum LineEndingWhat ends each line a file's lines are written with.
-
"\n", as on every OS unless asked.
-
"\r\n", as some Windows programs want.
Metadata
struct
Public Struct MetadataWhat's at a path, as File.Metadata found it: when it was last changed and read, and when it was made, which is Null where the OS or the disk doesn't say. IsReadOnly is whether its owner may not write it.
-
Whether it's a file, a folder, or a link.
-
How many bytes it holds.
-
When it was last changed.
-
When it was last read.
-
When it was made, or Null where the OS or the disk doesn't say.
-
Whether its owner may not write it.
-
Whether it's a file.
-
Whether it's a folder.
-
Whether it's a link.
File
class
Public Class FileA file's Static Methods, each a call that opens the file, does its work, and closes it.
-
@PanicsAtCaller Public Static Method ReadBytes(path: Path, most: Int64 = ARRAY_MOST): UInt8[] Throws IOErrorstatic method #The file's bytes. One that holds more than
mostbytes, which an array's most is the default for, throws an IOError of OTHER, found before reading them where the OS knows a file's size, and so does one that memory can't hold. Panics for a most below 0 or above an array's, 2^31 - 1. -
@PanicsAtCaller Public Static Async Method ReadBytesAsync(path: Path, most: Int64 = ARRAY_MOST): UInt8[] Throws IOErrorstatic method #What ReadBytes does, without blocking its thread: a call gives its Task.
-
@PanicsAtCaller Public Static Method ReadText(path: Path, most: Int64 = ALL): String Throws IOErrorstatic method #The file's bytes as text, with U+FFFD for each one that doesn't start well-formed UTF-8. Its line breaks stay as they are, and so does a byte order mark. One that holds more than
mostbytes, or more than memory does, throws an IOError of OTHER, as ReadBytes does. -
@PanicsAtCaller Public Static Async Method ReadTextAsync(path: Path, most: Int64 = ALL): String Throws IOErrorstatic method #What ReadText does, without blocking its thread: a call gives its Task.
-
@PanicsAtCaller Public Static Method ReadLines(path: Path, most: Int64 = ALL): String[] Throws IOErrorstatic method #The file's text in lines, split at "\n" and at "\r\n", without them. A last line with no line break after it is one too, and an empty file has none. One that holds more than
mostbytes throws as ReadText does. -
@PanicsAtCaller Public Static Async Method ReadLinesAsync(path: Path, most: Int64 = ALL): String[] Throws IOErrorstatic method #What ReadLines does, without blocking its thread: a call gives its Task.
-
Makes the file hold the
bytes, made when it isn't there, and replacing what it held when it is. -
Public Static Async Method WriteBytesAsync(path: Path, bytes: UInt8[]) Throws IOErrorstatic method #What WriteBytes does, without blocking its thread: a call gives its Task.
-
Makes the file hold the
text's UTF-8 bytes, as they are, as WriteBytes does. -
What WriteText does, without blocking its thread: a call gives its Task.
-
Public Static Method WriteLines(path: Path, lines: String[], ending: LineEnding = LineEnding.LF) Throws IOErrorstatic method #Makes the file hold the
lines, each withendingafter it, as WriteBytes does. -
Public Static Async Method WriteLinesAsync(path: Path, lines: String[], ending: LineEnding = LineEnding.LF) Throws IOErrorstatic method #What WriteLines does, without blocking its thread: a call gives its Task.
-
Adds the
bytesto the end of the file, made when it isn't there. -
Public Static Async Method AppendBytesAsync(path: Path, bytes: UInt8[]) Throws IOErrorstatic method #What AppendBytes does, without blocking its thread: a call gives its Task.
-
Adds the
text's UTF-8 bytes to the end of the file, as AppendBytes does. -
What AppendText does, without blocking its thread: a call gives its Task.
-
Public Static Method AppendLines(path: Path, lines: String[], ending: LineEnding = LineEnding.LF) Throws IOErrorstatic method #Adds the
lines, each withendingafter it, to the end of the file, as AppendBytes does. -
Public Static Async Method AppendLinesAsync(path: Path, lines: String[], ending: LineEnding = LineEnding.LF) Throws IOErrorstatic method #What AppendLines does, without blocking its thread: a call gives its Task.
-
Writes the
bytesto a new temporary file in the file's folder, onto the disk, then renames it over the file, so the file holds either all of them or what it held before, even if the program or the machine stops partway. On POSIX it keeps the permissions the file had. For a link, the file it leads to is replaced, as a plain write writes through it, and the link stays. -
Public Static Async Method WriteBytesAtomicAsync(path: Path, bytes: UInt8[]) Throws IOErrorstatic method #What WriteBytesAtomic does, without blocking its thread: a call gives its Task.
-
Writes the
text's UTF-8 bytes atomically, as WriteBytesAtomic does. -
Public Static Async Method WriteTextAtomicAsync(path: Path, text: String) Throws IOErrorstatic method #What WriteTextAtomic does, without blocking its thread: a call gives its Task.
-
Whether there's a file at the
path, or a link to one; not a folder. One the program can't look at isn't there, as far as it can tell. -
What Exists does, without blocking its thread: a call gives its Task.
-
How many bytes the file holds. A folder throws an IOError of IS_A_DIRECTORY.
-
What Size does, without blocking its thread: a call gives its Task.
-
Public Static Method Metadata(path: Path, followLinks: Bool = True): Metadata Throws IOErrorstatic method #What's at the
path, or at what it links to unlessfollowLinksis False, which gives a link's own. -
Public Static Async Method MetadataAsync(path: Path, followLinks: Bool = True): Metadata Throws IOErrorstatic method #What Metadata does, without blocking its thread: a call gives its Task.
-
Copies the file at
fromtoto, replacing a file there. A folder at either end throws an IOError of IS_A_DIRECTORY. -
What Copy does, without blocking its thread: a call gives its Task.
-
Moves, or renames, the file or folder at
fromtoto, replacing a file there. A file moved to another disk is copied there, then deleted. A folder goes only where nothing is, else an IOError of ALREADY_EXISTS onto a folder and NOT_A_DIRECTORY onto anything else, and a file onto a folder is IS_A_DIRECTORY, the same on every OS. -
What Move does, without blocking its thread: a call gives its Task.
-
Deletes the file, or the link, at the
path, and gives whether there was one. A folder throws an IOError of IS_A_DIRECTORY; Dir.Remove deletes one. -
What Delete does, without blocking its thread: a call gives its Task.
-
The file opened to read, as a FileStream from its start.
-
What Open does, without blocking its thread: a call gives its Task.
-
@PanicsAtCaller Public Static Method Open(path: Path, options: OpenOptions): FileStream Throws IOErrorstatic method #The file opened as the
optionssay, as a FileStream from its start, or at its end when it appends. Panics foroptionsno file opens with: none of Read, Write, and Append, or Create, CreateNew, or Truncate without Write or Append, or Truncate with Append. -
@PanicsAtCaller Public Static Async Method OpenAsync(path: Path, options: OpenOptions): FileStream Throws IOErrorstatic method #What Open does, without blocking its thread: a call gives its Task.
-
A FileStream to write the file, made when it isn't there, and emptied when it is.
-
What Create does, without blocking its thread: a call gives its Task.
-
Makes the file read-only, or, when
readOnlyis False, writable by its owner. -
Public Static Async Method SetReadOnlyAsync(path: Path, readOnly: Bool) Throws IOErrorstatic method #What SetReadOnly does, without blocking its thread: a call gives its Task.
Report an issue with this page or with FutureBlitz on GitHub.