FPS: useAsCString variants

[Donald Bruce Stewart]

bulat.ziganshin:
> Hello Donald,
> 
> Friday, July 14, 2006, 8:11:22 AM, you wrote:
> 
> >> afaik, CStringLen don't require zero byte at the end of string. So the
> >> following implementation will be much faster and still correct (not
> >> tested, it's just sketch):
> 
> > Well spotted! I've applied this patch, with a tiny tweak (you missed a
> > withForeignPtr in useAsCStringLen).
> 
> thanks. after writing this letter i spotted unsafeUseAsCStringLen and
> used it. now i'm curious about having these 4 functions:
> 
> useAsCString
> useAsCStringLen
> unsafeUseAsCString
> unsafeUseAsCStringLen
> 
> and differences between their behavior. may be, it will be better to
> keep only first two functions, with semantics already implemented
> (with my patch) - `useAsCString` add zero byte while useAsCStringLen doesn't ?

Ok, the story is:

We'd like to be able to efficiently pass ByteStrings to C. However,
    * CString has to be null terminated
    * ByteStrings aren't null terminated.

So, we have:
    useAsCString,           which copies a ByteString, and adds a \0 byte, O(n)
    unafeUseAsCString,      zero-copy version, assumes there's already a null byte, O(1)

Now, on the other hand, we have the CStringLen type, which doesn't need
a null byte. The CString type is isomorphic to a ByteString, so:

    useAsCStringLen,        which is just a cast. O(1)
    unsafeUseAsCStringLen   is a synonym for useAsCStringLen. 

I've clarified the documentation for the CString functions to make this
clear.

Cheers,
  Don