http://d.puremagic.com/issues/show_bug.cgi?id=6232

           Summary: And idea for std.string.toStringz docs
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: websites
        AssignedTo: nobody@puremagic.com
        ReportedBy: bearophile_hugs@eml.cc


--- Comment #0 from bearophile_hugs@eml.cc 2011-06-30 15:50:44 PDT ---
To the online docs of std.string.toStringz I suggest to add an example like this, that shows how to use the D type system to avoid passing not zero-terminated char* to C functions (C functions coming from C libraries, etc):


import std.string: toStringz;

struct CcharPtr {
    const char* ptr;
    alias ptr this;
}

// example of C function
extern(C) size_t strlen(CcharPtr str);

CcharPtr toStringz2(string s) {
    return CcharPtr(toStringz(s));
}

void main() {
    string s1 = "this is ";
    string s2 = s1 ~ "just a string";
    auto cs = toStringz2(s2);
    assert(s2.length == strlen(cs));
}

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=6232


Jonathan M Davis <jmdavisProg@gmx.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jmdavisProg@gmx.com


--- Comment #1 from Jonathan M Davis <jmdavisProg@gmx.com> 2011-06-30 17:27:01 PDT ---
That's a lot to add to the documentation for something which is completely unnecessary to use or understand the function. And it would only make sense if it were considered best practice to do this, and I think that you're going to have a hard time convincing people that they should do this in the general case. The typical thing to do with toStringz is to just pass the result directly to a C function and be done with it. Your suggestion is completely overkill in such cases.

This is an enhancement request, so I'm not going to just close it, but I really don't think that anything like this should be in the documentation. A function's documentation is for explaining what a function does and how its used, not for stuff like this. This sort of thing would only make sense if CcharPtr and tostringz2 were actually added to Phobos, in which case, the documentation would go on _them_, not toStringz.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=6232



--- Comment #2 from bearophile_hugs@eml.cc 2011-06-30 18:18:46 PDT ---
(In reply to comment #1)
> That's a lot to add to the documentation for something which is completely unnecessary to use or understand the function.

Good documentation must show non-obvious but important usages of the functions too. See below.


> And it would only make sense if
> it were considered best practice to do this, and I think that you're going to
> have a hard time convincing people that they should do this in the general
> case. The typical thing to do with toStringz is to just pass the result
> directly to a C function and be done with it. Your suggestion is completely
> overkill in such cases.

This suggestion of mine may be wrong, ad surely there are ways to improve it (in the name I've used too). But so far in D.learn I've seen three times people talk about bugs coming from not passing zero terminated strings to C functions. toStringz solves the problem, but you have to remember to use it in the first place.

Languages with good type systems like Haskell, F#, ATS, etc show that tons of bugs are avoidable using type systems in a smarter way. D type system isn't as refined as Haskell or Scala one, but it's good enough, if used well, to avoid many C-string bugs.


> This is an enhancement request, so I'm not going to just close it, but I really don't think that anything like this should be in the documentation. A function's documentation is for explaining what a function does and how its used, not for stuff like this.

This example shows how to use D type system and toStringz. Tricks and smart usages are at the right place in docs. Delphi documentation shows this well.

Another example are the itertools recipes present in the docs only: http://docs.python.org/library/itertools.html#recipes


> This sort of thing would only make sense if
> CcharPtr and tostringz2 were actually added to Phobos, in which case, the
> documentation would go on _them_, not toStringz.

This is probably not going to happen, Walter doesn't want "swallow" functions in Phobos. So they need to go in lists of "recipes" or examples in the docs.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=6232



--- Comment #3 from Jonathan M Davis <jmdavisProg@gmx.com> 2011-06-30 18:28:29 PDT ---
Your suggestion doesn't help at all with remembering to use zero-terminated strings when calling C code. For that you have to remember that you need to do that and that toStringz is the function to use to get a zero-terminated string. Adding your example to toStringz's documenation wouldn't help anyone remember to use it.

If anything is wrong with the type system, it's the fact that it implicitly converts arrays to pointers, but even if it required you to use the ptr property instead, people would still have to remember to use toStringz for strings. So, such a change to type system wouldn't help any. Are your suggestion only helps as far as the type system goes if all of the C functions in druntime or wherever use CcharPtr instead of char*, since if the function takes char*, you can still pass a string directly to them even if you have CcharPtr to use if you want to. So, I don't see how this suggestion helps much of anything.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=6232



--- Comment #4 from bearophile_hugs@eml.cc 2011-06-30 18:57:48 PDT ---
(In reply to comment #3)
> Your suggestion doesn't help at all with remembering to use zero-terminated strings when calling C code.

> Are your
> suggestion only helps as far as the type system goes if all of the C functions
> in druntime or wherever use CcharPtr instead of char*, since if the function
> takes char*, you can still pass a string directly to them even if you have
> CcharPtr to use if you want to. So, I don't see how this suggestion helps much
> of anything.

With extern(C) you are free to give to C functions a signature that you want.

In this example strlen() is meant as an example of random user-defined function
from some third-party C lib. Maybe using strlen() is not a clear enough
example, I have to use the frobaz() C function instead.

The idea here is that you define their signature using something like CcharPtr. If you do this, the type system will catch your bugs because you can't pass a char* to those C functions.

Similar tricks, or ones based on more complex type system features, allow you to kill bugs in F# code, ATS code, etc.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=6232



--- Comment #5 from Jonathan M Davis <jmdavisProg@gmx.com> 2011-06-30 19:30:18 PDT ---
1. It only helps if you're actually keeping zero-terminated strings around, which is likely an atypical use case. Usually, you pass it to the C function and forget about it.

2. Even if your suggestion does help prevent bugs, _none_ of the C functions in druntime are going to be declared to use CcharPtr, so it doesn't help at all unless you're declaring a bunch of C declarations yourself. So, it makes no sense to put the suggestion in the standard library's documentation. If CcharPtr were in druntime or Phobos that would be different, but it isn't.

There are plenty of suggestions which could be given to improve code quality. That doesn't mean that they belong in the standard library's documentation. If there were some sort of page with tips for D programmers, then perhaps it could go there, but I really don't think that it has any business going in the standard docs.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=6232



--- Comment #6 from bearophile_hugs@eml.cc 2011-07-01 07:19:12 PDT ---
(In reply to comment #5)
> 1. It only helps if you're actually keeping zero-terminated strings around,

You just call the function nested:

strlen(toStringz2(s2))


Hiding CcharPtr inside toStringz2 seems useful to avoid the mistake of using just CcharPtr(someCharPointer):

auto toStringz2(string s) {
    static struct CcharPtr {
        const char* ptr;
        alias ptr this;
    }

    return CcharPtr(toStringz(s));
}

// example of C function
extern(C) size_t strlen(ReturnType!toStringz2 str);

You are also free to add a wrapper, for the cases where you are sure to already have a zero terminated C string.


> 2. Even if your suggestion does help prevent bugs, _none_ of the C functions in druntime are going to be declared to use CcharPtr,

Who knows :-)


> so it doesn't help at all
> unless you're declaring a bunch of C declarations yourself.

If you are writing a wrapper for a C library I think the improved safety is worth the effort of writing:

extern(C) size_t foobar(ReturnType!toStringz2 str1, ReturnType!toStringz2
str2);

instead of:

extern(C) size_t foobar(const char* str1, const char* str2);

The work involved to write this is not significant.


> There are plenty of suggestions which could be given to improve code quality. That doesn't mean that they belong in the standard library's documentation. If there were some sort of page with tips for D programmers, then perhaps it could go there, but I really don't think that it has any business going in the standard docs.

Even if this idea of toStringz2 is not so good and people will want to close down this enhancement suggestion, I like the general idea of showing and suggesting good idioms in the standard library. Delphi, Python and Ruby (and maybe PHP too) libraries do it and I have appreciated this. Just a list of functions and classes is not enough. You have to show how to use things well, too.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------