Deprecate cstring{,Utf8} in Builder/Prim.hs

These become aliases to cstringLiteral and cstringUtf8Literal
in Builder/Internal.hs.

Author: hs-viktor

Data/ByteString/Builder.hs

@@ -440,18 +440,18 @@ char8 :: Char -> Builder
 char8 = P.primFixed P.char8
 
 -- | Char8 encode a 'String'.
-{-# INLINE [1] string8 #-} -- phased to allow P.cstring rewrite
+{-# INLINE [1] string8 #-} -- phased to allow cstringLiteral rewrite
 string8 :: String -> Builder
 string8 = P.primMapListFixed P.char8
 
 -- GHC desugars string literals with unpackCString# which the simplifier tends
 -- to promptly turn into build (unpackFoldrCString# s), so we match on both.
 {-# RULES
 "string8/unpackCString#" forall s.
-  string8 (unpackCString# s) = P.cstring s
+  string8 (unpackCString# s) = cstringLiteral s
 
 "string8/unpackFoldrCString#" forall s.
-  string8 (build (unpackFoldrCString# s)) = P.cstring s
+  string8 (build (unpackFoldrCString# s)) = cstringLiteral s
  #-}
 
 ------------------------------------------------------------------------------
@@ -467,19 +467,19 @@ charUtf8 = P.primBounded P.charUtf8
 --
 -- Note that 'stringUtf8' performs no codepoint validation and consequently may
 -- emit invalid UTF-8 if asked (e.g. single surrogates).
-{-# INLINE [1] stringUtf8 #-} -- phased to allow P.cstring rewrite
+{-# INLINE [1] stringUtf8 #-} -- phased to allow cstringLiteral rewrite
 stringUtf8 :: String -> Builder
 stringUtf8 = P.primMapListBounded P.charUtf8
 
 {-# RULES
 "stringUtf8/unpackCStringUtf8#" forall s.
-  stringUtf8 (unpackCStringUtf8# s) = P.cstringUtf8 s
+  stringUtf8 (unpackCStringUtf8# s) = cstringUtf8Literal s
 
 "stringUtf8/unpackCString#" forall s.
-  stringUtf8 (unpackCString# s) = P.cstring s
+  stringUtf8 (unpackCString# s) = cstringLiteral s
 
 "stringUtf8/unpackFoldrCString#" forall s.
-  stringUtf8 (build (unpackFoldrCString# s)) = P.cstring s
+  stringUtf8 (build (unpackFoldrCString# s)) = cstringLiteral s
  #-}
 
 instance IsString Builder where

Data/ByteString/Builder/Internal.hs

@@ -86,8 +86,8 @@ module Data.ByteString.Builder.Internal (
   , byteStringCopy
   , byteStringInsert
   , byteStringThreshold
-  , cstring
-  , cstringUtf8
+  , cstringLiteral
+  , cstringUtf8Literal
 
   , lazyByteStringCopy
   , lazyByteStringInsert
@@ -867,13 +867,14 @@ byteStringInsert =
 -- Raw CString encoding
 ------------------------------------------------------------------------------
 
--- | A null-terminated ASCII encoded 'Foreign.C.String.CString'.
--- Null characters are not representable.
+-- | Builder for raw 'Addr#' pointers to null-terminated primitive ASCII
+-- strings that are free of embedded (overlong-encoded as the two-byte sequence
+-- @0xC0 0x80@) null characters.
 --
 -- @since 0.11.5.0
-{-# INLINABLE cstring #-}
-cstring :: Addr# -> Builder
-cstring = \addr -> builder $ \k br -> do
+{-# INLINABLE cstringLiteral #-}
+cstringLiteral :: Addr# -> Builder
+cstringLiteral = \addr -> builder $ \k br -> do
     let ip   = Ptr addr
 #if __GLASGOW_HASKELL__ >= 811
         ipe  = Ptr (addr `plusAddr#` (cstringLength# addr))
@@ -882,20 +883,21 @@ cstring = \addr -> builder $ \k br -> do
 #endif
     wrappedBytesCopyStep (BufferRange ip ipe) k br
 
--- | A null-terminated UTF-8 encoded 'Foreign.C.String.CString'.
--- Null characters can be encoded as @0xc0 0x80@.
+-- | Builder for raw 'Addr#' pointers to null-terminated primitive UTF-8
+-- encoded strings that may contain embedded overlong-encodings (as the
+-- two-byte sequence @0xC0 0x80@) of null characters.
 --
 -- @since 0.11.5.0
-cstringUtf8 :: Addr# -> Builder
-cstringUtf8 = \addr0 -> builder $ \k br -> do
+{-# INLINABLE cstringUtf8Literal #-}
+cstringUtf8Literal :: Addr# -> Builder
+cstringUtf8Literal = \addr0 -> builder $ \k br -> do
 #if __GLASGOW_HASKELL__ >= 811
     let len = cstringLength# addr0
 #else
     (I# len) <- fromIntegral <$> S.c_strlen (Ptr addr0)
 #endif
     nullAt <- c_strstr (Ptr addr0) (Ptr "\xc0\x80"#)
     cstringUtf8_step addr0 len nullAt k br
-{-# INLINABLE cstringUtf8 #-}
 
 cstringUtf8_step :: Addr# -> Int# -> Ptr Word8 -> BuildStep r -> BuildStep r
 cstringUtf8_step addr len ((== nullPtr) -> True) k br =

Data/ByteString/Builder/Prim.hs

@@ -433,8 +433,8 @@ module Data.ByteString.Builder.Prim (
   -- a decimal number with UTF-8 encoded characters.
   , charUtf8
 
-  , cstring     -- Backwards-compatibility re-exports from Internal.hs
-  , cstringUtf8 -- these no longer make use of the BoundPrim API.
+  , cstring
+  , cstringUtf8
 
 {-
   -- * Testing support
@@ -468,9 +468,7 @@ import           Data.ByteString.Builder.Prim.ASCII
 
 import           Foreign
 import           Foreign.C.Types
-import           Foreign.C.String (CString)
 import           Foreign.ForeignPtr.Unsafe (unsafeForeignPtrToPtr)
-import           GHC.Int (Int (..))
 import           GHC.Word (Word8 (..))
 import           GHC.Exts
 import           GHC.IO
@@ -665,6 +663,26 @@ primMapLazyByteStringBounded w =
     L.foldrChunks (\x b -> primMapByteStringBounded w x `mappend` b) mempty
 
 
+-- | Builder for raw 'Addr#' pointers to null-terminated primitive ASCII
+-- strings that are free of embedded (overlong-encoded as the two-byte sequence
+-- @0xC0 0x80@) null characters.
+--
+-- @since 0.11.0.0
+{-# DEPRECATED cstring "Use cstringLiteral instead" #-}
+cstring :: Addr# -> Builder
+cstring = cstringLiteral
+{-# INLINE cstring #-}
+
+-- | Builder for raw 'Addr#' pointers to null-terminated primitive UTF-8
+-- encoded strings that may contain embedded overlong-encodings (as the
+-- two-byte sequence @0xC0 0x80@) of null characters.
+--
+-- @since 0.11.0.0
+{-# DEPRECATED cstringUtf8 "Use cstringUtf8Literal instead" #-}
+cstringUtf8 :: Addr# -> Builder
+cstringUtf8 = cstringUtf8Literal
+{-# INLINE cstringUtf8 #-}
+
 ------------------------------------------------------------------------------
 -- Char8 encoding
 ------------------------------------------------------------------------------

bench/BenchAll.hs

@@ -33,10 +33,13 @@ import           Data.ByteString.Builder.Extra         (byteStringCopy,
 import           Data.ByteString.Builder.Internal      (ensureFree)
 import           Data.ByteString.Builder.Prim          (BoundedPrim, FixedPrim,
                                                         (>$<))
+import qualified Data.ByteString.Builder.Internal      as BI
 import qualified Data.ByteString.Builder.Prim          as P
 import qualified Data.ByteString.Builder.Prim.Internal as PI
 
 import           Foreign
+import           GHC.Exts (Addr#)
+import           GHC.Ptr (Ptr(..))
 
 import System.Random
 
@@ -247,6 +250,13 @@ largeTraversalInput = S.concat (replicate 10 byteStringData)
 smallTraversalInput :: S.ByteString
 smallTraversalInput = S8.pack "The quick brown fox"
 
+asciiLit, utf8Lit :: Ptr Word8
+asciiLit = Ptr "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"#
+utf8Lit  = Ptr "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\xc0\x80xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"#
+
+addrOf :: Ptr Word8 -> Addr#
+addrOf (Ptr addr) = addr
+
 main :: IO ()
 main = do
   defaultMain
@@ -256,11 +266,11 @@ main = do
         , benchB' "ensureFree 8"  ()  (const (ensureFree 8))
         , benchB' "intHost 1"     1   intHost
         , benchB' "UTF-8 String (naive)" "hello world\0" fromString
-        , benchB' "UTF-8 String"  () $ \() -> P.cstringUtf8 "hello world\0"#
+        , benchB' "UTF-8 String"  () $ \() -> BI.cstringUtf8Literal "hello world\xc0\x80"#
         , benchB' "String (naive)" "hello world!" fromString
-        , benchB' "String"        () $ \() -> P.cstring "hello world!"#
-        , benchB' "AsciiLit64"   () $ \() -> P.cstring "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"#
-        , benchB' "Utf8Lit64"   () $ \() -> P.cstringUtf8 "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\xc0\x80xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"#
+        , benchB' "String"        () $ \() -> BI.cstringLiteral "hello world!"#
+        , benchB' "AsciiLit"      () $ \() -> BI.cstringLiteral (addrOf asciiLit)
+        , benchB' "Utf8Lit"       () $ \() -> BI.cstringUtf8Literal (addrOf utf8Lit)
         ]
 
       , bgroup "Encoding wrappers"

tests/builder/Data/ByteString/Builder/Tests.hs

@@ -994,11 +994,11 @@ testsUtf8 =
 testCString :: [TestTree]
 testCString =
     [ testProperty "cstring" $
-        toLazyByteString (BI.cstring "hello world!"#) ==
+        toLazyByteString (BI.cstringLiteral "hello world!"#) ==
         LC.pack "hello" `L.append` L.singleton 0x20
                         `L.append` LC.pack "world!"
     , testProperty "cstringUtf8" $
-        toLazyByteString (BI.cstringUtf8 "hello\xc0\x80\xc0\x80world\xc0\x80!"#) ==
+        toLazyByteString (BI.cstringUtf8Literal "hello\xc0\x80\xc0\x80world\xc0\x80!"#) ==
         LC.pack "hello" `L.append` L.singleton 0x00
                         `L.append` L.singleton 0x00
                         `L.append` LC.pack "world"