Standard library · Basics

io

Reading from the keyboard, reading and writing files, and writing to standard error.

import io

On this page

Functions

Most programs have to read something and write something. The io package holds the simplest ways to do it: read one line from the user, read or write a whole file in one go, or work through an open file piece by piece.

The functions that take a file name, such as ReadFile, open and close the file themselves. The functions that take a File* work on a file you opened yourself with os.Open; remember to close it with Close.

Sizes in this package are counted in bytes, not characters. Outside ASCII one character takes several bytes, so reading a file in chunks can split a character across two chunks.

Functions

`Input`

func Input(): str

Reads one line from standard input, usually the keyboard, and returns it without the line ending. It is the same thing input "" does. The example below waits for you to type, so here it is only compiled and not run.

io-Input.salam

import io

func main:
    print "What is your name? "
    name := io.Input()
    println "Welcome,", name
end

`Read`

func Read(f: File*, size: u64): str

Reads up to size bytes from the current position in the file. At the end of the file it returns an empty string.

io-Read.salam

import io
import os

func main:
    io.WriteFile("data.txt", "salam\ndonya\npayan\n")
    f := os.Open("data.txt", "rb")
    println io.Readline(f)
    println io.Read(f, 3 as u64)
    io.Seek(f, 0, 0)
    print io.ReadAll(f)
    io.Close(f)
end

Outputsalam don salam donya payan

`Readline`

func Readline(f: File*): str

Reads one line from the file, without the line ending. At the end of the file it returns an empty string.

The example for this item is shown with the ones above: io-Read.salam

`Write`

func Write(f: File*, data: str): int

Writes a string to an open file and returns the number of bytes written.

io-Write.salam

import io
import os

func main:
    f := os.Open("report.txt", "wb")
    n := io.Write(f, "today's report\n")
    io.Close(f)
    println "bytes written:", n
    src := os.Open("report.txt", "rb")
    dst := os.Open("copy.txt", "wb")
    println "copied:", io.Copy(dst, src), "bytes"
    io.Close(src)
    io.Close(dst)
    print io.ReadFile("copy.txt")
end

Outputbytes written: 15 copied: 15 bytes today's report

`Seek`

func Seek(f: File*, offset: i64, whence: int): int

Moves the reading and writing position in a file. offset is a distance in bytes and whence says where to count from: zero is the start of the file, one is the current position and two is the end. It returns zero on success.

The example for this item is shown with the ones above: io-Read.salam

`Close`

func Close(f: File*)

Closes the file. Every file you open has to be closed once, and defer is a good place for it.

The example for this item is shown with the ones above: io-Read.salam

`ReadFile`

func ReadFile(path: str): str

Reads the whole content of a file in one go. If the file does not exist, or cannot be read, it returns an empty string.

io-ReadFile.salam

import io

func main:
    path := "note.txt"
    io.WriteFile(path, "first line\n")
    io.AppendFile(path, "second line\n")
    print io.ReadFile(path)
    println io.ReadFile("a file that is not there.txt") == ""
end

Outputfirst line second line true

`WriteFile`

func WriteFile(path: str, data: str): int

Creates the file, or empties it if it already exists, and writes the string into it. It returns the number of bytes written, or minus one if the file could not be opened.

The example for this item is shown with the ones above: io-ReadFile.salam

`AppendFile`

func AppendFile(path: str, data: str): int

Adds the string to the end of the file, leaving what was already there alone. If the file does not exist it is created. Like WriteFile it returns a byte count or minus one.

The example for this item is shown with the ones above: io-ReadFile.salam

`Lines`

func Lines(path: str): Vector<str>

Reads a file and returns its lines in a vector. Trailing whitespace and the empty final line are dropped. Release the vector with free when you are done with it.

io-Lines.salam

import io

func main:
    mut lines := Vector {} as Vector<str>
    defer lines.free()
    lines.push("apple")
    lines.push("pomegranate")
    lines.push("grape")
    written := io.WriteLines("fruit.txt", lines)
    println "wrote:", written, "bytes"
    read := io.Lines("fruit.txt")
    defer read.free()
    each i, line in read:
        println i + 1, line
    end
end

Outputwrote: 24 bytes 1 apple 2 pomegranate 3 grape

`EPrint`

func EPrint(s: str)

Writes a string to standard error, without a line break. Errors and warnings belong here rather than in the program's real output.

io-EPrint.salam

import io

func main:
    println "this goes to standard output"
    io.EPrint("warning: ")
    io.EPrintln("this message goes to standard error")
    print "no line break yet..."
    io.Flush()
    println ""
end

Outputthis goes to standard output warning: this message goes to standard error no line break yet...

`EPrintln`

func EPrintln(s: str)

Like EPrint, but moves to the next line after the message.

The example for this item is shown with the ones above: io-EPrint.salam

`Flush`

func Flush()

Writes out whatever is still sitting in the output buffer. Useful when you have written something with print that has no line ending and want the user to see it at once.

The example for this item is shown with the ones above: io-EPrint.salam

`ReadAll`

func ReadAll(f: File*): str

Reads everything left from the current position to the end of the file.

The example for this item is shown with the ones above: io-Read.salam

`Copy`

func Copy(dst: File*, src: File*): i64

Writes everything left in the file src into the file dst and returns the number of bytes copied. It suits large files, since it never holds the whole file in memory.

The example for this item is shown with the ones above: io-Write.salam

`WriteLines`

func WriteLines(path: str, lines: Vector<str>): int

Writes each element of a vector as one line of the file. An existing file is rewritten. It returns a byte count, or minus one.

The example for this item is shown with the ones above: io-Lines.salam