Introduction to the Scanner Class for Input

Imagine a program that asks a user to type several test scores on a single line, separated by spaces. The program does not receive a neat list of numbers. It receives one long stream of characters, and somewhere inside that stream are the individual scores the program actually cares about. Before the program can do anything useful, it needs a way to cut that stream into meaningful pieces.

The Scanner class in Java is the tool that performs this cutting. It was introduced in the package java.util to make reading basic data types from a character input source easier. Java's built-in support for basic input has long been considered thin, or dependent on fairly advanced techniques, so the Scanner was added for everyday use. It is not a complete solution to every input problem, but it is a substantial improvement for beginners and for many ordinary programs.

A token is one meaningful piece of input. Tokens are separated from one another by delimiters. Unless you change the setting, a Scanner uses whitespace as its delimiter. Here, whitespace means spaces, tabs, and end-of-line markers. Those separator characters tell the scanner where one token stops and the next one begins.

Once the separation has done its job, the whitespace itself is set aside. It is not handed to your program as part of any token. Keep this in mind, because it explains a surprise you will meet later when reading whole lines.

Reading the diagram from left to right: the number 12 is one token, apple is another, and 3.5 is the third. The spaces and the line break sit between tokens and mark the boundaries, but they are not part of any token that the program receives.

The most basic reading method is next. Each call to next reads the next token from the input source and returns it as a String. Because the return type is String, the program receives the token exactly as the characters appeared, with no attempt to interpret them as numbers. This makes next the right choice when the input is words, codes, or any value you want to keep as text.

Most of the time, a program reading numbers does not want the text version. Methods such as nextInt and nextDouble read the next token and then try to convert it into a value of type int or double. The same family of methods exists for the other primitive types. The conversion is the key difference from next: the method reads the token and attempts to turn it into the requested primitive type, rather than returning the characters unchanged.

Token-based methods ignore line boundaries when they pick out pieces of input. Sometimes that is not what you want. The nextLine method works differently. It reads everything up to the next end-of-line marker and returns the result as a String. The end-of-line marker is consumed during the read, but it is not included in the returned text. Because nextLine is not organized around tokens, the returned text can contain spaces, tabs, and other whitespace exactly as the user typed them. If the user presses Enter immediately, the returned value is the empty string.

A Scanner is a wrapper around an input source. It does not own the characters it reads. The source is chosen by the constructor: whatever you pass into the parentheses when you write new Scanner is the place the Scanner will draw characters from. The input routines, such as next and nextInt, are instance methods defined on the class, so you must create a Scanner object before you can call them.

The word source in that pattern is a placeholder for one of the permitted kinds of input. The constructor accepts several kinds. The source text names four of them directly: a Reader, an InputStream, a String, and a File. It notes that other possibilities exist, so treat those four as the set the source explicitly names rather than a complete list.

The most common case in introductory programs is reading from standard input, which is the keyboard in a typical console run. Passing System.in to the constructor tells the Scanner to read from standard input.

The three Scanners above differ only in the argument. Each one is wrapped around a different source, and each one exposes the same reading methods. Once the object exists, next, nextInt, and nextLine work the same way regardless of where the characters came from.

Follow the path of characters. The source holds the raw characters. The Scanner is created around that source, and it divides those characters into tokens using delimiters. Each read method then takes the next piece from that division and hands it to the program, either as a String or converted to a primitive type.

The same pipeline explains why the order of reads matters. The Scanner keeps its place in the source. Each read consumes what it needs and leaves the rest waiting for the next call. The next section shows exactly where that place sits after a token-based read.

nextInt reads the token 42 and converts it to an int. It stops at the end of that token. The end-of-line marker that follows 42 is a delimiter, and it has not been consumed by nextInt, because nextInt is organized around tokens and not lines. The marker is still waiting in the input.

A program often needs to know whether there is anything left to read before it attempts a read. The hasNext method answers that question for tokens. It returns a boolean value that is true when at least one more token remains in the input source. The companion methods hasNextInt and hasNextDouble go a step further. They return true only when the next token exists and represents a value of the requested type. The hasNextLine method plays the same role for lines, returning true when at least one more line remains.

The pattern most programs follow is that a check comes first, and a read happens only when the check says a value is waiting. This keeps a loop from trying to read past the end of its input. The typed check matters as well. A hasNextInt test confirms not only that a token exists but that the token can be read as an int, so the check and the read agree with each other.

Most of the trouble beginners meet with Scanner comes from switching between token-based and line-based reading without thinking about where the input position sits. The following mistakes come up repeatedly.