Conflict between std.file write() and std.stdio write()

Craig Dillabaugh craig.dillabaugh at gmail.com
Fri Oct 4 07:12:14 PDT 2013


On Thursday, 3 October 2013 at 21:58:18 UTC, Jonathan M Davis 
wrote:
> On Thursday, October 03, 2013 22:57:22 Craig Dillabaugh wrote:
>> On Thursday, 3 October 2013 at 19:49:07 UTC, Jonathan M Davis
>> 
>> wrote:
>> > On Thursday, October 03, 2013 20:57:20 Craig Dillabaugh 
>> > wrote:
>> >> On Thursday, 3 October 2013 at 18:12:01 UTC, Jonathan M 
>> >> Davis
>> 
>> clip
>> 
>> >> > - Jonathan M Davis
>> >> 
>> >> Fair enough. As you point out the fix is pretty simple.
>> >> 
>> >> However, I can't seem to remember in C++ or any other 
>> >> language
>> >> (not that I know all that many other languages) coming 
>> >> across a
>> >> function in the standard library that conflicted with 
>> >> another
>> >> function in the standard library in this way. I am likely to
>> >> get
>> >> corrected on that claim though :o)
>> > 
>> > I'm sure that it could be found somewhere, but C++ avoids it
>> > for two reasons:
>> > 
>> > 1. As good as the STL is, it's pathetically small.
>> > 2. It only uses one namespace, so it _has_ to avoid 
>> > conflicts,
>> > even if that
>> > means using uglier names.
>> > 
>> > Java or C# might have some conflicts (I'm not sure - they
>> > certainly have much
>> > richer standard libraries than C++ does), but they almost
>> > always avoid it,
>> > because they're don't even allow free functions, so you only
>> > end up having to
>> > worry about class names conflicting. Their module systems are
>> > also different
>> > from D's (particularly C#'s), which changes things a bit.
>> > 
>> > Other languages like python tend to force you to give the 
>> > full
>> > path anyway,
>> > which avoids conflicts.
>> > 
>> > The reason that D runs into them is because the default is to
>> > pull everything
>> > into the current module when you import it. If we'd taken the
>> > approach of
>> > making you give the full import path by default or forcing 
>> > you
>> > to explicitly
>> > import each symbol, then it wouldn't be a problem (though 
>> > that
>> > would obviously
>> > cause other problems).
>> > 
>> > And we'll definitely pick different names where appropriate,
>> > but if the best
>> > names for two different functions in two different modules
>> > happen to be the same
>> > name, then we're going to use it. And in same cases, we very
>> > purposely picked
>> > the same name, because the functions did the same type of 
>> > thing
>> > (e.g. the
>> > functions in std.ascii and std.uni which do the same thing 
>> > but
>> > for ASCII and
>> > Unicode respectively).
>> > 
>> > - Jonathan M Davis
>> 
>> That is an excellent explanation. Thank you.
>> 
>> Do you think it would be worth noting the conflict in the
>> documentation for readText()/write()?
>> 
>> I should have mentioned in my original post that I likely could
>> have figured out the workaround for this, and I posted here 
>> more
>> because I was surprised that std.stdio and std.file would have 
>> a
>> conflict! It seems like something folks new to D might run into
>> with some frequency, and be thinking "whats up with that!".
>> 
>> If others think it is a good idea, maybe I will head over to
>> gitHub and try to add something.
>
> I'm inclined to think that there's no need, since people 
> learning D should
> know how the module system works, and I'd prefer not to clutter 
> the
> documentation, but I also haven't been a newbie for a very long 
> time.
>
> - Jonathan M Davis

There are two problems with this for newbies:

1. They may not understand the module system well.
2. The may not know that a string = char array, and that as such 
it may not even occur to them that write() will accept a string. 
Now a careful reading of the docs for readText() should clue them 
in that string = char array, but when you are new to a language 
and trying to absorb the new syntax it is something that can 
easily be overlooked.

I have just enough D experience now that for the most part I 
don't struggle to follow the documentation, but I remember when I 
was new to D I found it very frustrating. That is even after 
reading Anderi's book (maybe I am a slow learner, but I am likely 
fairly representative of the average coder!) Now part of that is 
the known shortage of documentation, but often example code can 
be hard to follow, for example, from write:

    int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];
    write("filename", a);
    assert(cast(int[]) read("filename") == a);

Consider the final 'assert' line.  On the one hand, it shows how 
to concisely use language features and good D coding practices, 
however, on the other hand  there is an awful lot going on in a 
single line of code. To someone who knows the language it looks 
trivial, but it can be a bit overwhelming to a newbie who wants 
to see if they can use this new language to write some text to a 
file!

I guess the more fundamental question is, what is the purpose of 
the documentation?  Is it a quick reference for D users, or is it 
a resource for people trying to learn the language?  I learned 
C++ using Qt, largely from their online docs. The Qt 
documentation is a reference, but it also tends to provide lots 
of explanation.

I've seen both, documentation strictly as a reference for those 
who already know how to use it, and docs with more focus on 
explaining how things work to the uninitiated.  I tend to like 
the later approach, but it is certainly debatable.


More information about the Digitalmars-d-learn mailing list