Charin   built-in function

The Charin function returns a sequence of characters from an input stream, at the current read position.

If there are insufficient characters available, the result will contain only the characters which remain .. AND the NOTREADY condition is raised.

When the default input stream is associated with keyboard input, the program will wait until the user types sufficient characters at the keyboard. The user may have difficulty identifying the program is waiting for input.

result = Charin( [ stream ] [, [ start ] [, length ] ] )

stream

the name of the input stream. The default input stream is used if this argument is absent, or the empty string is specified as a stream name.

start

an optional starting position. This must be a positive whole number. A value of 1 locates the first character in the stream.

When the start argument is absent, text is read from the current read position associated with the stream. The read position is the offset where a prior Charin or Linein request completed. Initially the read position is the beginning of the input stream.

length

an optional number of characters to obtain. This must be 0 or a positive whole number. When the length is unspecified, one character is obtained.

When the length argument is omitted, and the start arguments is present the current read position of the stream is set to the start position, and the empty string is returned.

Examples: say Charin() -- shows one character that is obtained from the default input stream. say Charin( '' ) -- shows one character that is obtained from the default input stream. say Charin( '', , 3 ) -- shows three characters that are obtained from the default input stream. say Charin( '', 5, 3 ) -- shows three characters that begin at the 5th position of the default input stream. say Charin( 'file1' ) -- shows one character that is obtained from the stream named 'file1'