Text Input using TextIO

TextIO offers separate input functions for int, double, boolean, char, one-word String, and complete-line String values.

Programming

Why Input Needs Typed Functions

A program that asks a user for information needs that information in a usable form. A count of items should arrive as a whole number, a price may need a fractional part, and a yes or no answer should become a true or false value. TextIO is a set of input functions that handles this job. Instead of giving you one generic reader, it offers a separate function for each kind of value the program might need. Each function is responsible for reading one particular type, and it promises that the value it hands back to the program is legal for that type.

What do you think happens?

A program calls TextIO.getlnInt() and the user types abc. Does the program receive abc?

Reveal answer

Answer:

No. The program never receives the illegal entry. The computer asks the user to enter the value again.

Each TextIO function guarantees that it returns a legal value of its type. Because abc cannot be returned as an int, it is treated as illegal and the user is asked to re-enter the value.

Six Functions for Six Input Types

TextIO provides input functions for six kinds of values: int, double, boolean, char, one-word String, and complete-line String. The source material names four of these explicitly: TextIO.getlnInt() reads an int, TextIO.getlnBoolean() reads a boolean, TextIO.getlnWord() reads a one-word String, and TextIO.getln() reads a complete-line String. The functions for double and char follow the same naming pattern and are called TextIO.getlnDouble() and TextIO.getlnChar(). The table below pairs each input type with its function.

Value type wanted	TextIO function	What it reads
int	TextIO.getlnInt()	A whole number that can be stored in an int
double	TextIO.getlnDouble()	A number that can be stored as a double
boolean	TextIO.getlnBoolean()	A yes/no, true/false, or 1/0 style response
char	TextIO.getlnChar()	A single character
one-word String	TextIO.getlnWord()	The next run of non-blank characters
complete-line String	TextIO.getln()	All characters up to the next carriage return, including spaces

Each supported input type has its own TextIO reading function.

Capturing a Return Value in a Variable

A TextIO function produces a value, and the program stores that value by assigning it to a variable. The source requires that the variable be declared before the input call, and that its type match the type the function returns. Declaring the variable first and then assigning the result is the pattern the source describes. The variable then holds the user's accepted entry, and the rest of the program can use it like any other value of that type.

Code walkthrough

int count;
count = TextIO.getlnInt();
System.out.println(count);

1
Line 1 declares a variable named count whose type is int. The variable exists before the input call.
2
Line 2 calls TextIO.getlnInt(). The function reads the user's entry, checks that it is a legal int, and returns it. The assignment operator stores that returned value in count.
3
Line 3 uses count like any other int, here printing it. Because the value came from TextIO, the program receives only a legal int.

count is declared as an int before any input is read
TextIO.getlnInt() waits for the user and returns a legal int
The returned int is stored in count

Worked example

Reading a price and a name

Write the statements that read a price as a double and a single word as a String, storing each in a variable.

1
Declare the variables first
The source requires a previously declared variable. Declare price as a double and word as a String before calling any input function.
2
Match each variable to its function
A double is read with TextIO.getlnDouble(). A one-word String is read with TextIO.getlnWord().
3
Assign each returned value
Write price = TextIO.getlnDouble(); and word = TextIO.getlnWord(); so each variable receives a legal value of its own type.

Result

The program holds a legal double in price and a one-word String in word, without any illegal entry reaching the program.

What Happens on Invalid Input

A common mistake is to think that every TextIO input function passes whatever the user types straight into the program. That is not how it works. Each function reads a particular type of value, and it checks whether the entry can be returned as that type. If the entry is illegal, the computer asks the user to enter the value again, and the program does not receive the first illegal value. For a TextIO.getlnInt() call, a non-numeric entry such as abc is illegal. A number that is too large or too small to be stored in an int is also illegal, and the computer asks again in the same way.

When does the program accept the input and continue, and what happens step by step when the entry does not match the expected type?

Read the flowchart as a loop. The computer prompts for an entry and checks it against the requested type. A no answer sends control back to the prompt, so the user is asked again. Only a yes answer lets the function return a value to the program. This is why the program can assume that the variable it receives holds a legal value of the requested type.

Reading One Word Versus a Whole Line

Both String functions return text, but they do not read the same amount of it. TextIO.getlnWord() skips any spaces and carriage returns first, then reads non-blank characters until it reaches the next space or carriage return. TextIO.getln() reads every character typed up to the next carriage return, including spaces. In both cases the carriage return is read and discarded, so it is not included in the returned String.

When the user types hello world, how do getlnWord() and getln() differ in what they return?

java

String first = TextIO.getlnWord();
String rest = TextIO.getln();

String first = TextIO.getlnWord();
String rest = TextIO.getln();

Notes on the code

getlnWord() stops at the first space
getln() returns everything up to the carriage return
The carriage return itself is never part of either result

Choose getlnWord() when you need a single token, such as a name or a code with no spaces. Choose getln() when the user's entry may legitimately contain spaces, such as a full address or a sentence. Using the wrong one changes the answer the program receives even though the typed text is the same.

How getlnBoolean Interprets Responses

TextIO.getlnBoolean() turns a response into a boolean. The source states that it accepts several true and false forms, including yes, no, y, n, 1, and 0, and that either letter case is accepted. Responses in the true set produce true, and responses in the false set produce false. Any other response is illegal for a boolean, so the computer asks the user to enter the value again, following the same rule as the other input functions.

Which user responses map to true, which map to false, and what happens to a response outside that set?

The mapping shows that the function is not limited to a single spelling. Both yes and y produce true, and both no and n produce false. Letter case does not matter, so YES and Yes are treated the same as yes. The response maybe is outside the listed set, so it is not converted to either value. The computer treats it as an illegal entry and asks again.

Mistakes Beginners Make with TextIO

Common mistake
Assuming the program receives whatever the user typed
Why it fails
Each TextIO function checks the entry against its type. Illegal entries are never passed to the program.
Do this instead
Expect the function to keep asking until it has a legal value, and store only that legal value.
Common mistake
Assigning the result to a variable of the wrong type
What it looks like
```
int total; total = TextIO.getlnDouble();
```
Why it fails
The source requires the variable to match the type of the returned value. A double result does not match an int variable.
Do this instead
```
Declare the variable with the same type as the function returns, such as double total; total = TextIO.getlnDouble();
```
Common mistake
Using getlnWord() when the user is expected to type a phrase
What it looks like
A user types hello world, and getlnWord() returns only hello.
Why it fails
getlnWord() stops at the first space, so the rest of the phrase is not part of the returned String.
Do this instead
Use TextIO.getln() when the entry may contain spaces.
Common mistake
Forgetting that the carriage return is discarded and never appears in the returned String

Trace the Input Choices

EASY

A program needs the user's age as a whole number, their full name including spaces, and whether they want email updates as a yes or no answer. Name the TextIO function you would use for each value, and describe what the program would do if the user typed fifty-two for the age.

Hints

Match each value to a type in the table, then to its function.
The full name may contain spaces, so think about which String function reads a complete line.
A word that is not a number is illegal for an int, so the computer asks the user to enter the value again.

Your attempt (not saved)

Key Takeaways for TextIO Input

1
TextIO provides a separate input function for each supported type: int, double, boolean, char, one-word String, and complete-line String.
2
A returned value is stored by assigning it to a previously declared variable whose type matches the function's return type.
3
An illegal entry is never passed to the program; the computer asks the user to enter the value again.
4
getlnWord() reads one run of non-blank characters, while getln() reads the whole line including spaces, and neither includes the carriage return.
5
getlnBoolean() maps responses such as yes, y, 1 to true and no, n, 0 to false, ignoring letter case, and rejects anything else.

At a glance

TextIO provides a separate input function for each supported type, including int, double, boolean, char, one-word String, and complete-line String.
The returned value must be assigned to a previously declared variable with the matching type.
Illegal entries are never received by the program; the computer asks the user to re-enter the value.
getlnWord() reads one run of non-blank characters, while getln() reads a whole line including spaces, and the carriage return is always discarded.
getlnBoolean() accepts forms such as yes, no, y, n, 1, and 0 in either letter case.