Document that useAsCStringLen does not append NUL (#612)

* Document that useAsCStringLen does not append NUL * Update Data/ByteString.hs Co-authored-by: Matthew Craven <[email protected]> --------- Co-authored-by: Matthew Craven <[email protected]>
haskell · Sep 15, 2023 · 6034af8 · 6034af8
1 parent 16d6b7e
commit 6034af8
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 4 deletions.
diff --git a/Data/ByteString.hs b/Data/ByteString.hs
@@ -1797,9 +1797,13 @@ useAsCString (BS fp l) action =
     pokeByteOff buf l (0::Word8)
     action (castPtr buf)
 
--- | /O(n) construction/ Use a @ByteString@ with a function requiring a @CStringLen@.
--- As for @useAsCString@ this function makes a copy of the original @ByteString@.
+-- | /O(n) construction/ Use a @ByteString@ with a function requiring a 'CStringLen'.
+-- As for 'useAsCString' this function makes a copy of the original @ByteString@.
 -- It must not be stored or used after the subcomputation finishes.
+--
+-- Beware that this function is not required to add a terminating @\NUL@ byte at the end of the 'CStringLen' it provides.
+-- If you need to construct a pointer to a null-terminated sequence, use 'useAsCString'
+-- (and measure length independently if desired).
 useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
 useAsCStringLen p@(BS _ l) f = useAsCString p $ \cstr -> f (cstr,l)
 

diff --git a/Data/ByteString/Short/Internal.hs b/Data/ByteString/Short/Internal.hs
@@ -1758,10 +1758,14 @@ useAsCString sbs action =
       action buf
   where l = length sbs
 
--- | /O(n) construction./ Use a @ShortByteString@ with a function requiring a @CStringLen@.
--- As for @useAsCString@ this function makes a copy of the original @ShortByteString@.
+-- | /O(n) construction./ Use a @ShortByteString@ with a function requiring a 'CStringLen'.
+-- As for 'useAsCString' this function makes a copy of the original @ShortByteString@.
 -- It must not be stored or used after the subcomputation finishes.
 --
+-- Beware that this function does not add a terminating @\NUL@ byte at the end of 'CStringLen'.
+-- If you need to construct a pointer to a null-terminated sequence, use 'useAsCString'
+-- (and measure length independently if desired).
+--
 -- @since 0.10.10.0
 useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a
 useAsCStringLen sbs action =