Please help me understand this function signature: std.stdio.File.byLine

[H. S. Teoh]

On Thu, Jul 15, 2021 at 06:08:45PM +0000, Scotpip via Digitalmars-d-learn wrote:
[...]
> ```
> auto byLine(Terminator, Char) (
>   KeepTerminator keepTerminator = No.keepTerminator,
>   Terminator terminator = '\x0a'
> )
> if (isScalarType!Terminator);
> 
> auto byLine(Terminator, Char) (
>   KeepTerminator keepTerminator,
>   Terminator terminator
> )
> if (is(immutable(ElementEncodingType!Terminator) == immutable(Char)));
> ```
> 
> To specify the line ending, it appears to be asking for a type
> "Terminator" which I can't find in the library. Doing the obvious
> doesn't work:
> 
> ```
> // Err: cannot deduce function from argument types
> myFile.byLine(`\r\n`);
> ```
> Also, how would you specify the Char type as a parameter?

First, notice that there are two sets of parentheses in the above quoted
declarations. The first set are compile-time parameters (template
parameters), while the second are runtime parameters.

`Terminator` and `Char` are listed as compile-time parameters, meaning
that they are types specified by the caller, so there is no definition
for them -- the caller defines what they will be. (More on this later.)

Secondly, note the order of parameters in the second set of parentheses:
`keepTerminator` first, then `terminator`. This is why your example
above doesn't compile: you're trying to specify a terminator where the
function expects a KeepTerminator parameter.

Now, a fully-specified invocation of byLine would specify both
compile-time and runtime parameters, e.g.:

	auto r = File(...)
		.byLine!(string,char)(Yes.KeepTerminator, "\r\n");

In this case, Terminator == string, Char == char.

But generally, the D compiler is pretty good at inferring types for you
automatically, so in this case, since the runtime parameters already
adequately imply what the compile-time arguments will be, so you could
just leave them out and write simply:

	auto r = File(...)
		.byLine(Yes.KeepTerminator, "\r\n");


> The examples are unenlightening as they only show the default case, so
> any help would be much appreciated. Any wider tips on how to read
> these cryptic signatures would be a bonus!

Please file a bug against the documentation about this.  Examples should
cover not only the default case, but should also illustrate how to use
non-default values.  This is a shortcoming in the documentation.


T

-- 
MS Windows: 64-bit rehash of 32-bit extensions and a graphical shell for a 16-bit patch to an 8-bit operating system originally coded for a 4-bit microprocessor, written by a 2-bit company that can't stand 1-bit of competition.