[Issue 17438] New: std.conv.parse documentation contradiction

[via Digitalmars-d-bugs]

https://issues.dlang.org/show_bug.cgi?id=17438

          Issue ID: 17438
           Summary: std.conv.parse documentation contradiction
           Product: D
           Version: D2
          Hardware: All
               URL: https://dlang.org/library/std/conv/parse.html
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: phobos
          Assignee: nobody at puremagic.com
          Reporter: braddr at puremagic.com

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?

--