Scanning input with fmt

The fmt package reads as well as writes. Its scan functions fill pointers and return how many values they read and what went wrong, and the three variants Sscan, Fscan and Scan differ only in the source: a string, an io.Reader or standard input. Part 6 ended with the failures of concurrency; Part 7 is the standard library, starting with the package every Go program imports.

Sscan: a string into variables

Sscan splits the input on white space and reads each value into the pointer it is given. The count is the number of values that were read, and the error is nil when it read all of them. The pointers are ordinary & addresses: the function writes through them, which is why a value type cannot be passed directly.

package main import "fmt" func main() { var name string var age int n, err := fmt.Sscan("ada 36", &name, &age) fmt.Println("n:", n, "name:", name, "age:", age, "err:", err) }

go build -o app main.go && ./app

n: 2 name: ada age: 36 err: <nil>

Two values were read, the string and the integer, and the error is nil. A space between two values is enough for Sscan; a comma, a colon or a dash is not, and that is what the format version is for.

Sscanf: a format

Sscanf takes a format like the print side: ordinary characters must match, %d reads an integer and the spaces around a verb are flexible. The date below has dashes that the format repeats, so the three numbers land in the three variables in the order they appear.

package main import "fmt" func main() { var year, month, day int n, err := fmt.Sscanf("2026-11-18", "%d-%d-%d", &year, &month, &day) fmt.Println("n:", n) fmt.Println("date:", year, month, day) fmt.Println("err:", err) }

go build -o app main.go && ./app

n: 3
date: 2026 11 18
err: <nil>

The format must match the text exactly: a different separator, a missing field or a trailing character stops the scan at that point and returns a count below three. The count is the useful part, because a partially read value is worse than a failed one: n == 3 is the success test.

Fscan: any reader

Fscan reads from an io.Reader, which in this program is a strings.Reader. The three values are a string, an int and a float, and the scan reads each one with the type of the pointer. This is the variant to use in a test or in a program that reads a file, because the reader can be anything: a file, a network connection, an embedded asset.

package main import ( "fmt" "strings" ) func main() { reader := strings.NewReader("alice 3 4.5") var name string var count int var score float64 n, err := fmt.Fscan(reader, &name, &count, &score) fmt.Println("n:", n, "err:", err) fmt.Println(name, count, score) }

go build -o app main.go && ./app

n: 3 err: <nil>
alice 3 4.5

The float printed as 4.5 because that is the shortest decimal that round-trips, which is the same rule the print verbs follow. Fscan does not consume more than the values it read, so a second call continues after the third one, and the reader is the shared position.

The count and the error

A wrong type is not a panic: the scan stops, returns the number of values that did fit, and describes the first problem. The text "abc" cannot become an int, so nothing is read and the error says what the scan expected. A program that needs a specific message maps the error to its own, and a program that needs the position uses the index in the error text.

package main import "fmt" func main() { var n int count, err := fmt.Sscan("abc", &n) fmt.Println("count:", count) fmt.Println("error:", err) }

go build -o app main.go && ./app

count: 0
error: expected integer

The error is an error from the package, not a typed failure, so a caller that needs a category checks the count and wraps the message. A scan that reads zero values because the input was empty reports EOF instead, which is how a loop over lines ends.

Scan and the terminal

fmt.Scan reads from standard input, and from a terminal it waits for a whole line before it returns anything, because the terminal driver buffers until the newline. That is why a prompt written with Print needs a Flush or the prompt appears after the input: the standard output of a program attached to a terminal is line buffered. Scanln stops at the newline, while Scan treats it as white space.

For line-oriented input the next lessons use bufio.Scanner instead: it returns whole lines, has a buffer size a program can raise, and does not need a format string. The scan functions of fmt are at their best on small, fixed records, such as the three fields above.

Exercises

  1. Change the date format to %d/%d/%d and run the program. What are the count and the error, and which value was read before the mismatch?
  2. Read four values from a string with three, and print the count. What does the fourth variable hold?
  3. Use Fscan twice on the same reader. Which value does the second call read, and what does that say about the reader position?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does fmt.Sscan take?

    Answer

    A string and pointers to the variables

    It writes through the pointers.

  2. What does a scan return?

    Answer

    The number of values read and an error

    The count is the success test.

  3. What separates values in Sscan without a format?

    Answer

    White space

    Spaces, tabs and newlines all count.

  4. What does Sscanf add over Sscan?

    Answer

    A format that non-space separators must match

    The dashes in the date are part of the format.

  5. What is Fscan for?

    Answer

    Reading from any io.Reader

    A strings.Reader, a file or a connection all work.

  6. What happens when the input has the wrong type?

    Answer

    The scan stops and returns the count so far with an error

    The error says what was expected.

  7. What does Sscan return for an empty input?

    Answer

    count 0 and io.EOF

    EOF is how a loop over records ends.

  8. Why does a prompt sometimes appear after the input?

    Answer

    The terminal buffers output and the prompt was not flushed

    A terminal is line buffered.

  9. Which function returns whole lines with a larger buffer?

    Answer

    bufio.Scanner

    It is the next lesson.

  10. What does the count 3 in the date example mean?

    Answer

    Three values were read successfully

    Each verb filled one variable.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev