Line Input #

Reads one line of text from a file

Syntax
	Line Input #file number, string_variable_1
		or
	Line Input #file number, string_variable_2 , max_length

Parameters
	file number
		file number of an file opened for KeyPgInputfilemodeInput
	string_variable_1
		variable-length or fixed_length (and known) string, to receive the 
		line of text
	string_variable_2
		dereferenced {z|w}string pointer or {z|w}string variable passed by 
		reference (string buffer size unknown for both), to receive the line 
		of text
	max_length
		maximum number of characters allowed to be written to the string 
		buffer, including the NULL terminator

Description
	Reads a line from an open text file (opened for KeyPgInputfilemodeInput through a bound 
	file number) and stores it in a string variable.  

	A line of text ends at, but does not include the end of line characters. 
	An end of line character may be the LF character (KeyPgChrChr(10)) or the CRLF 
	character pair (KeyPgChrChr(13,10)).

	Two syntaxes are available:
		* The first syntax is only allowed when the string buffer size 
		  (provided by string_variable_1) is either variable or fixed (and 
		  known).
		* The second syntax with max_length parameter is only allowed when 
		  the string buffer size (provided by string_variable_2) is unknown. 
		  This happens for dereferenced KeyPgZstringZString/KeyPgWstringWString pointers, or KeyPgZstringZString/
		  KeyPgWstringWString variables passed by reference. This can used to truncate 
		  the text line to be read, or avoid overflowing beyond allocated 
		  data of the provided string buffer.

	Note:
		- Using Line Input # is naturally dedicated to Input Access file 
		mode.
		- It is also allowed in Binary/Random Access file mode, but this was 
		never well tested and results may vary.

Example
	Open "myfile.txt" For Output As #1
	Print #1, "Hello, World"
	Close #1

	Dim s As String
	Open "myfile.txt" For Input As #1
	Line Input #1, s
	Close #1
	Print "'" & s & "'"

	Const maxlength = 6  '' max 5 characters plus 1 null terminal character
	Dim pz As ZString Ptr = CAllocate(maxlength, SizeOf(ZString))
	Open "myfile.txt" For Input As #1
	Line Input #1, *pz, maxlength
	Close #1
	Print "'" & *pz & "'"
	Deallocate(pz)

Version
	* Before fbc 1.10.0, the second syntax (with max_length parameter) was 
	  not supported.

Differences from QB
	* None

See also
	* KeyPgLineinputLine Input
	* KeyPgInputPpInput #
	* KeyPgOpenOpen
	* KeyPgInputfilemodeInput (File Mode)

