7.4.14. CHARIN (Character Input)

Returns a string of up to length characters read from the character input stream name. (To understand the input and output functions, see Chapter 14, Input and Output Streams.) If you omit name, characters are read from STDIN, which is the default input stream. The default length is 1.

For persistent streams, a read position is maintained for each stream. Any read from the stream starts at the current read position by default. When the language processor completes reading, the read position is increased by the number of characters read. You can give a start value to specify an explicit read position. This read position must be a positive whole number and within the bounds of the stream, and must not be specified for a transient stream. A value of 1 for start refers to the first character in the stream. If start is not a positive whole number the appropriate syntax condition is raised. When the read position is past the bounds of the stream, the empty string is returned and the NOTREADY condition is raised.

If you specify a length of 0, then the read position is set to the value of start, but no characters are read and the null string is returned.

In a transient stream, if there are fewer than length characters available, the execution of the program generally stops until sufficient characters become available. If, however, it is impossible for those characters to become available because of an error or another problem, the NOTREADY condition is raised (see Section 14.5, “Errors during Input and Output”) and CHARIN returns with fewer than the requested number of characters.

Here are some examples:

Example 7.20. Builtin function CHARIN

CHARIN(myfile,1,3)   -->   "MFC"    /* the first 3        */
                                   /* characters         */
CHARIN(myfile,1,0)   -->   ""       /* now at start       */
CHARIN(myfile)       -->   "M"      /* after last call    */
CHARIN(myfile, ,2)   -->   "FC"     /* after last call    */

/* Reading from the default input (here, the keyboard)   */
/* User types "abcd efg"                                 */
CHARIN()             -->   "a"      /* default is         */
                                   /* 1 character        */
CHARIN(, ,5)         -->   "bcd e"

Notes:

CHARIN returns all characters that appear in the stream, including control characters such as line-end and end-of-file.
When CHARIN reads from the keyboard, program execution stops until you press the Enter key.