Bug 17438 – std.conv.parse documentation contradiction

The documentation at the top contains this text (edited to number the bullets for discussion): ------ The parse family of functions works quite like the to family, except that: 1) It only works with character ranges as input. 2) It takes the input by reference. (This means that rvalues - such as string literals - are not accepted: use to instead.) 3) It advances the input to the position following the conversion. 4) It does not throw if it could not convert the entire input. ------ The important part is #4. Several of the parse functions can and do throw. Just scan down the page. As a demonstration: $ cat bugparse.d module bugparse; void main(string[] args) { import std.conv : parse; string s = "a"; int val = parse!int(s, 10); } $ dmd -ofbugparse -g bugparse.d $ ./bugparse std.conv.ConvException@/home/braddr/sandbox/dmd-2.074.0/linux/bin64/../../src/phobos/std/conv.d(2111): Unexpected 'a' when converting from type string to type int ---------------- /home/braddr/sandbox/dmd-2.074.0/linux/bin64/../../src/phobos/std/conv.d:81 pure @safe int std.conv.parse!(int, immutable(char)[]).parse(ref immutable(char)[]) [0x432b92] /home/braddr/sandbox/dmd-2.074.0/linux/bin64/../../src/phobos/std/conv.d:2389 pure @safe int std.conv.parse!(int, immutable(char)[]).parse(ref immutable(char)[], uint) [0x4327fe] bugparse.d:8 _Dmain [0x432189] ??:? _D2rt6dmain211_d_run_mainUiPPaPUAAaZiZ6runAllMFZ9__lambda1MFNlZv [0x43d30f] ??:? scope void rt.dmain2._d_run_main(int, char**, extern (C) int function(char[][])*).tryExec(scope void delegate()) [0x43d23f] ??:? scope void rt.dmain2._d_run_main(int, char**, extern (C) int function(char[][])*).runAll() [0x43d2b8] ??:? scope void rt.dmain2._d_run_main(int, char**, extern (C) int function(char[][])*).tryExec(scope void delegate()) [0x43d23f] ??:? _d_run_main [0x43d1af] ??:? main [0x43b1ed] ??:? __libc_start_main [0x3544982f] So.. doc bug or major implementation bug?

The documentation says: Throws: A ConvException If an overflow occurred during conversion or if no character of the input was meaningfully converted. "if no character of the input was meaningfully converted" is the key part, so at least for the example you presented, I don't see a problem.

Re-read the description of the parse family of functions I cut and pasted into the bug report (which is still what the page says). The entire family is documented as not throwing. One function does, and that it documents at the specific site of that variant doesn't give it license to violate the spec at the higher level. One of them is still wrong, and it's that it throws.

(In reply to Brad Roberts from comment #2) > The entire family > is documented as not throwing. Where does it say that? I think you're misinterpreting what "It does not throw if it could not convert the entire input" means. It does not mean "it does not throw, period". It also doesn't mean "It does not throw if it could not convert any part of the input". What it means is that if it finds a valid value at the start of the input, which it consumes and returns, it leaves the rest of the input in place, which is useful when you need to parse as much of a string (or character range) up until a non-specific separator or character not representing the value.

The description of the function family, as quoted above, says "It does not throw if it could not convert the entire input." Personally I don't find that ambiguous, but I guess we do have a sample size of one of it being misinterpreted. I find it unambiguous because if you were to interpret it as "it does not throw", it would mean that 1) the last part of the sentence would be redundant as well as misleading, and would have no reason to be included; 2) as pointed out, it would contradict the individual functions' "Throws:" sections; 3) if the functions were to never throw, what would their return value be when absolutely no useful information was extracted from the input text? Since as far as I can see this issue was filed out of a misinterpretation of the documentation, and there's been no reply to my last comment in over 24h, I guess the misunderstanding has been settled; either way, I don't see any actionable point here right now. If you think that the misunderstanding occurred due to something lacking in the documentation and can suggest a concrete improvement to the documentation that would avoid such a misunderstanding from occurring again, please reopen and/or submit a pull request. (In reply to Brad Roberts from comment #2) > Re-read the description of the parse family of functions I cut and pasted > into the bug report (which is still what the page says). Funny how you're telling people to re-read things when the misunderstanding was on your side. Let's be nice, OK? :)