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

Fri, 04 Oct 2013 07:16:33 -0700

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.

Reply via email to