Curl support RFC

[Steven Schveighoffer]

On Mon, 14 Mar 2011 07:20:26 -0400, Lars T. Kyllingstad  
<public at kyllingen.nospamnet> wrote:

> On Mon, 14 Mar 2011 02:36:07 -0700, Jonathan M Davis wrote:
>
>> On Monday 14 March 2011 02:16:12 Jonas Drewsen wrote:
>>> On 13/03/11 23.44, Andrei Alexandrescu wrote:
>>> > On 3/11/11 9:20 AM, Jonas Drewsen wrote:
>>> >> Hi,
>>> >>
>>> >> So I've spent some time trying to wrap libcurl for D. There is a lot
>>> >> of things that you can do with libcurl which I did not know so I'm
>>> >> starting out small.
>>> >>
>>> >> For now I've created all the declarations for the latest public curl
>>> >> C api. I have put that in the etc.c.curl module.
>>> >
>>> > Great! Could you please create a pull request for that?
>>>
>>> Will do as soon as I've figured out howto create a pull request for a
>>> single file in a branch. Anyone knows how to do that on github? Or
>>> should I just create a pull request including the etc.curl wrapper as
>>> well?
>>
>> You can't. A pull request is for an entire branch. It pulls _everything_
>> from that branch which differs from the one being merged with. git cares
>> about commits, not files. And pulling from another repository pulls all
>> of the commits which you don't have. So, if you want to do a pull
>> request, you create a branch with exactly the commits that you wanted
>> merged in on it. No more, no less.
>>
>>> >> On top of that I've created a more D like api as seen below. This is
>>> >> located in the 'etc.curl' module. What you can see below currently
>>> >> works but before proceeding further down this road I would like to
>>> >> get your comments on it.
>>> >>
>>> >> //
>>> >> // Simple HTTP GET with sane defaults // provides the .content,
>>> >> .headers and .status //
>>> >> writeln( Http.get("http://www.google.com").content );
>>> >
>>> > Sweet. As has been discussed, often the content is not text so you
>>> > may want to have content return ubyte[] and add a new property such
>>> > as "textContent" or "text".
>>>
>>> I've already changed it to void[] as done in the std.file module. Is
>>> ubyte[] better suited?
>>
>> That's debatable. Some would argue one way, some another. Personally,
>> I'd argue ubyte[]. I don't like void[] one bit. Others would agree with
>> me, and yet others would disagree. I don't think that there's really a
>> general agreement on whether void[] or ubyte[] is better when it comes
>> to reading binary data like that.
>
> I also think ubyte[] is best, because:
>
> 1. It can be used directly.  (You can't get an element from a void[]
> array without casting it to something else first.)
>
> 2. There are no assumptions about the type of data contained in the
> array.  (char[] arrays are assumed to be UTF-8 encoded.)
>
> 3. ubyte[] arrays are (AFAIK) not scanned by the GC.  (void[] arrays may
> contain pointers and must therefore be scanned.)

This isn't exactly true.  arrays *created* as void[] will be scanned.   
Arrays created as ubyte[] and then cast to void[] will not be scanned.

However, it is far too easy while dealing with a void[] array to have it  
mysteriously flip its bit to scan-able.

> I think the rule of thumb should be:  If the array contains raw data of
> unspecified type, but no pointers or references, use ubyte[].
>
> void[] is very useful for input parameters, however, since all arrays are
> implicitly castable to void[]:
>
>   void writeData(void[] data) { ... }
>
>   writeData("Hello World!");
>   writeData([1, 2, 3, 4]);

I think (and this differs from  my previous opinion) const(void)[] should  
be used for input parameters where any array type could be passed in.   
However, ubyte[] should be used for output parameters and for internal  
storage.  void[] just has too many pitfalls to be used anywhere but where  
its implicit casting ability is useful.

-Steve