www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 6232] New: And idea for std.string.toStringz docs

reply d-bugmail puremagic.com writes:
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



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: -------
Jun 30 2011
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=6232


Jonathan M Davis <jmdavisProg gmx.com> changed:

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



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: -------
Jun 30 2011
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=6232






 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.


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: -------
Jun 30 2011
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=6232




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: -------
Jun 30 2011
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=6232






 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


-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jun 30 2011
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=6232




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: -------
Jun 30 2011
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=6232






 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: -------
Jul 01 2011