diff --git a/Data/ByteArray/Encoding.hs b/Data/ByteArray/Encoding.hs --- a/Data/ByteArray/Encoding.hs +++ b/Data/ByteArray/Encoding.hs @@ -5,7 +5,7 @@ -- Stability : experimental -- Portability : unknown -- --- ByteArray base converting +-- Base conversions for 'ByteArray'. -- module Data.ByteArray.Encoding ( convertToBase @@ -21,13 +21,35 @@ import Data.Memory.Encoding.Base32 import Data.Memory.Encoding.Base64 --- | Different bases that can be used +-- $setup +-- >>> :set -XOverloadedStrings +-- >>> import Data.ByteString + +-- | The different bases that can be used. -- -- See for details. -- In particular, Base64 can be standard or -- . URL-safe -- encoding is often used in other specifications without -- characters. +-- +-- ==== Examples +-- +-- A quick example to show the differences: +-- +-- >>> let input = "Is 3 > 2?" :: ByteString +-- >>> let convertedTo base = convertToBase base input :: ByteString +-- >>> convertedTo Base16 +-- "49732033203e20323f" +-- >>> convertedTo Base32 +-- "JFZSAMZAHYQDEPY=" +-- >>> convertedTo Base64 +-- "SXMgMyA+IDI/" +-- >>> convertedTo Base64URLUnpadded +-- "SXMgMyA-IDI_" +-- >>> convertedTo Base64OpenBSD +-- "QVKeKw.8GBG9" +-- data Base = Base16 -- ^ similar to hexadecimal | Base32 | Base64 -- ^ standard Base64 @@ -35,7 +57,15 @@ | Base64OpenBSD -- ^ Base64 as used in OpenBSD password encoding (such as bcrypt) deriving (Show,Eq) --- | Convert a bytearray to the equivalent representation in a specific Base +-- | Encode some bytes to the equivalent representation in a specific 'Base'. +-- +-- ==== Examples +-- +-- Convert a 'ByteString' to base-64: +-- +-- >>> convertToBase Base64 ("foobar" :: ByteString) :: ByteString +-- "Zm9vYmFy" +-- convertToBase :: (ByteArrayAccess bin, ByteArray bout) => Base -> bin -> bout convertToBase base b = case base of Base16 -> doConvert (binLength * 2) toHexadecimal @@ -59,7 +89,20 @@ B.withByteArray b $ \bin -> f bout bin binLength --- | Try to Convert a bytearray from the equivalent representation in a specific Base +-- | Try to decode some bytes from the equivalent representation in a specific 'Base'. +-- +-- ==== Examples +-- +-- Successfully convert from base-64 to a 'ByteString': +-- +-- >>> convertFromBase Base64 ("Zm9vYmFy" :: ByteString) :: Either String ByteString +-- Right "foobar" +-- +-- Trying to decode invalid data will return an error string: +-- +-- >>> convertFromBase Base64 ("!!!" :: ByteString) :: Either String ByteString +-- Left "base64: input: invalid length" +-- convertFromBase :: (ByteArrayAccess bin, ByteArray bout) => Base -> bin -> Either String bout convertFromBase Base16 b | odd (B.length b) = Left "base16: input: invalid length" diff --git a/Data/ByteArray/Methods.hs b/Data/ByteArray/Methods.hs --- a/Data/ByteArray/Methods.hs +++ b/Data/ByteArray/Methods.hs @@ -51,13 +51,11 @@ import Prelude hiding (length, take, drop, span, concat, replicate, splitAt, null, pred, last, any, all) import qualified Prelude -#if defined(WITH_BYTESTRING_SUPPORT) && defined(WITH_FOUNDATION_SUPPORT) +#if defined(WITH_BYTESTRING_SUPPORT) && defined(WITH_BASEMENT_SUPPORT) import qualified Data.ByteString as SPE (ByteString) import qualified Basement.UArray as SPE (UArray) -#if MIN_VERSION_basement(0,0,5) import qualified Basement.Block as SPE (Block) #endif -#endif -- | Allocate a new bytearray of specific size, and run the initializer on this memory alloc :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba @@ -300,11 +298,9 @@ -- | Convert a bytearray to another type of bytearray convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout convert bs = inlineUnsafeCreate (length bs) (copyByteArrayToPtr bs) -#if defined(WITH_BYTESTRING_SUPPORT) && defined(WITH_FOUNDATION_SUPPORT) +#if defined(WITH_BYTESTRING_SUPPORT) && defined(WITH_BASEMENT_SUPPORT) {-# SPECIALIZE convert :: SPE.ByteString -> SPE.UArray Word8 #-} {-# SPECIALIZE convert :: SPE.UArray Word8 -> SPE.ByteString #-} -#if MIN_VERSION_basement(0,0,5) {-# SPECIALIZE convert :: SPE.ByteString -> SPE.Block Word8 #-} {-# SPECIALIZE convert :: SPE.Block Word8 -> SPE.ByteString #-} -#endif #endif diff --git a/Data/ByteArray/Sized.hs b/Data/ByteArray/Sized.hs --- a/Data/ByteArray/Sized.hs +++ b/Data/ByteArray/Sized.hs @@ -21,6 +21,9 @@ {-# LANGUAGE MultiParamTypeClasses #-} {-# LANGUAGE FunctionalDependencies #-} {-# LANGUAGE UndecidableInstances #-} +#if __GLASGOW_HASKELL__ >= 806 +{-# LANGUAGE NoStarIsType #-} +#endif module Data.ByteArray.Sized ( ByteArrayN(..) diff --git a/Data/ByteArray/Types.hs b/Data/ByteArray/Types.hs --- a/Data/ByteArray/Types.hs +++ b/Data/ByteArray/Types.hs @@ -28,21 +28,7 @@ import Data.Memory.PtrMethods (memCopy) -#ifdef WITH_FOUNDATION_SUPPORT - -#if MIN_VERSION_foundation(0,0,14) && MIN_VERSION_basement(0,0,0) -# define NO_LEGACY_FOUNDATION_SUPPORT -#else -# define LEGACY_FOUNDATION_SUPPORT -#endif - -#if MIN_VERSION_basement(0,0,5) -# define SUPPORT_BLOCK -#endif - -#if MIN_VERSION_basement(0,0,7) && __GLASGOW_HASKELL__ >= 800 && defined(SUPPORT_BLOCK) -# define SUPPORT_BLOCKN -#endif +#ifdef WITH_BASEMENT_SUPPORT import Data.Proxy (Proxy(..)) import Data.Word (Word8) @@ -52,29 +38,15 @@ import qualified Basement.String as Base (String, toBytes, Encoding(UTF8)) import qualified Basement.PrimType as Base (primSizeInBytes) -#ifdef SUPPORT_BLOCK import qualified Basement.UArray.Mutable as BaseMutable (withMutablePtrHint) import qualified Basement.Block as Block import qualified Basement.Block.Mutable as Block -#endif -#ifdef SUPPORT_BLOCKN import Basement.Nat import qualified Basement.Sized.Block as BlockN -#endif -#ifdef LEGACY_FOUNDATION_SUPPORT - -import qualified Foundation as F -import qualified Foundation.Collection as F -import qualified Foundation.String as F (toBytes, Encoding(UTF8)) -import qualified Foundation.Array.Internal as F -import qualified Foundation.Primitive as F (primSizeInBytes) - #endif -#endif - import Prelude hiding (length) -- | Class to Access size properties and data of a ByteArray @@ -108,9 +80,8 @@ return (r, Bytestring.PS fptr 0 sz) #endif -#ifdef WITH_FOUNDATION_SUPPORT +#ifdef WITH_BASEMENT_SUPPORT -#if MIN_VERSION_basement(0,0,5) baseBlockRecastW8 :: Base.PrimType ty => Block.Block ty -> Block.Block Word8 baseBlockRecastW8 = Block.unsafeCast -- safe with Word8 destination @@ -120,14 +91,11 @@ copyByteArrayToPtr ba dst = do mb <- Block.unsafeThaw (baseBlockRecastW8 ba) Block.copyToPtr mb 0 (castPtr dst) (Block.length $ baseBlockRecastW8 ba) -#endif -#ifdef SUPPORT_BLOCKN instance (KnownNat n, Base.PrimType ty, Base.Countable ty n) => ByteArrayAccess (BlockN.BlockN n ty) where length a = let Base.CountOf i = BlockN.lengthBytes a in i withByteArray a f = BlockN.withPtr a (f . castPtr) copyByteArrayToPtr bna = copyByteArrayToPtr (BlockN.toBlock bna) -#endif baseUarrayRecastW8 :: Base.PrimType ty => Base.UArray ty -> Base.UArray Word8 baseUarrayRecastW8 = Base.recast @@ -135,9 +103,7 @@ instance Base.PrimType ty => ByteArrayAccess (Base.UArray ty) where length a = let Base.CountOf i = Base.length (baseUarrayRecastW8 a) in i withByteArray a f = Base.withPtr (baseUarrayRecastW8 a) (f . castPtr) -#if MIN_VERSION_basement(0,0,5) copyByteArrayToPtr ba dst = Base.copyToPtr ba (castPtr dst) -#endif instance ByteArrayAccess Base.String where length str = let Base.CountOf i = Base.length bytes in i @@ -148,23 +114,17 @@ bytes = Base.toBytes Base.UTF8 str withByteArray s f = withByteArray (Base.toBytes Base.UTF8 s) f -#ifdef SUPPORT_BLOCK instance (Ord ty, Base.PrimType ty) => ByteArray (Block.Block ty) where allocRet sz f = do mba <- Block.new $ sizeRecastBytes sz Proxy a <- Block.withMutablePtrHint True False mba (f . castPtr) ba <- Block.unsafeFreeze mba return (a, ba) -#endif instance (Ord ty, Base.PrimType ty) => ByteArray (Base.UArray ty) where allocRet sz f = do mba <- Base.new $ sizeRecastBytes sz Proxy -#if MIN_VERSION_basement(0,0,5) a <- BaseMutable.withMutablePtrHint True False mba (f . castPtr) -#else - a <- Base.withMutablePtr mba (f . castPtr) -#endif ba <- Base.unsafeFreeze mba return (a, ba) @@ -174,57 +134,5 @@ in q + (if r == 0 then 0 else 1) where !(Base.CountOf szTy) = Base.primSizeInBytes p {-# INLINE [1] sizeRecastBytes #-} - -#ifdef LEGACY_FOUNDATION_SUPPORT - -uarrayRecastW8 :: F.PrimType ty => F.UArray ty -> F.UArray Word8 -uarrayRecastW8 = F.recast - -instance F.PrimType ty => ByteArrayAccess (F.UArray ty) where -#if MIN_VERSION_foundation(0,0,10) - length a = let F.CountOf i = F.length (uarrayRecastW8 a) in i -#else - length = F.length . uarrayRecastW8 -#endif - withByteArray a f = F.withPtr (uarrayRecastW8 a) (f . castPtr) - -instance ByteArrayAccess F.String where -#if MIN_VERSION_foundation(0,0,10) - length str = let F.CountOf i = F.length bytes in i -#else - length str = F.length bytes -#endif - where - -- the Foundation's length return a number of elements not a number of - -- bytes. For @ByteArrayAccess@, because we are using an @Int@, we - -- didn't see that we were returning the wrong @CountOf@. - bytes = F.toBytes F.UTF8 str - withByteArray s f = withByteArray (F.toBytes F.UTF8 s) f - -instance (Ord ty, F.PrimType ty) => ByteArray (F.UArray ty) where - allocRet sz f = do - mba <- F.new $ sizeRecastBytes sz Proxy - a <- F.withMutablePtr mba (f . castPtr) - ba <- F.unsafeFreeze mba - return (a, ba) - where -#if MIN_VERSION_foundation(0,0,10) - sizeRecastBytes :: F.PrimType ty => Int -> Proxy ty -> F.CountOf ty - sizeRecastBytes w p = F.CountOf $ - let (q,r) = w `Prelude.quotRem` szTy - in q + (if r == 0 then 0 else 1) - where !(F.CountOf szTy) = F.primSizeInBytes p - {-# INLINE [1] sizeRecastBytes #-} -#else - sizeRecastBytes :: F.PrimType ty => Int -> Proxy ty -> F.Size ty - sizeRecastBytes w p = F.Size $ - let (q,r) = w `Prelude.quotRem` szTy - in q + (if r == 0 then 0 else 1) - where !(F.Size szTy) = F.primSizeInBytes p - {-# INLINE [1] sizeRecastBytes #-} -#endif - -#endif - #endif diff --git a/Data/Memory/Encoding/Base16.hs b/Data/Memory/Encoding/Base16.hs --- a/Data/Memory/Encoding/Base16.hs +++ b/Data/Memory/Encoding/Base16.hs @@ -5,7 +5,10 @@ -- Stability : experimental -- Portability : unknown -- --- Hexadecimal escaper +-- Low-level Base16 encoding and decoding. +-- +-- If you just want to encode or decode some bytes, you probably want to use +-- the "Data.ByteArray.Encoding" module. -- {-# LANGUAGE MagicHash #-} {-# LANGUAGE UnboxedTuples #-} diff --git a/Data/Memory/Encoding/Base32.hs b/Data/Memory/Encoding/Base32.hs --- a/Data/Memory/Encoding/Base32.hs +++ b/Data/Memory/Encoding/Base32.hs @@ -5,7 +5,10 @@ -- Stability : experimental -- Portability : unknown -- --- Base32 +-- Low-level Base32 encoding and decoding. +-- +-- If you just want to encode or decode some bytes, you probably want to use +-- the "Data.ByteArray.Encoding" module. -- {-# LANGUAGE MagicHash #-} {-# LANGUAGE UnboxedTuples #-} diff --git a/Data/Memory/Encoding/Base64.hs b/Data/Memory/Encoding/Base64.hs --- a/Data/Memory/Encoding/Base64.hs +++ b/Data/Memory/Encoding/Base64.hs @@ -5,7 +5,10 @@ -- Stability : experimental -- Portability : unknown -- --- Base64 +-- Low-level Base64 encoding and decoding. +-- +-- If you just want to encode or decode some bytes, you probably want to use +-- the "Data.ByteArray.Encoding" module. -- {-# LANGUAGE MagicHash #-} {-# LANGUAGE UnboxedTuples #-} diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,5 @@ -Copyright (c) 2015 Vincent Hanquez +Copyright (c) 2015-2018 Vincent Hanquez +Copyright (c) 2017-2018 Nicolas Di Prima All rights reserved. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -37,24 +37,4 @@ Support ------- -Memory supports the following platform: - -* Windows >= 7 -* OSX >= 10.8 -* Linux - -On the following architectures: - -* x86-64 -* i386 - -On the following haskell versions: - -* GHC 7.10 -* GHC 8.0 -* GHC 8.2 - -Some older versions or different systems are possibly working too - - - +See [Haskell packages guidelines](https://github.com/vincenthz/haskell-pkg-guidelines/blob/master/README.md#support) diff --git a/memory.cabal b/memory.cabal --- a/memory.cabal +++ b/memory.cabal @@ -1,5 +1,5 @@ Name: memory -version: 0.14.16 +version: 0.14.17 Synopsis: memory and related abstraction stuff Description: Chunk of memory, polymorphic byte array management and manipulation @@ -25,7 +25,7 @@ Build-Type: Simple Homepage: https://github.com/vincenthz/hs-memory Bug-Reports: https://github.com/vincenthz/hs-memory/issues -Cabal-Version: >=1.18 +cabal-version: 1.18 extra-doc-files: README.md CHANGELOG.md source-repository head @@ -38,6 +38,11 @@ Manual: True Flag support_foundation + Description: add support for foundation strings and unboxed array (deprecated use support_basement) + Default: True + Manual: True + +Flag support_basement Description: add support for foundation strings and unboxed array Default: True Manual: True @@ -75,7 +80,10 @@ Data.ByteArray.Methods Data.ByteArray.MemView Data.ByteArray.View - Build-depends: base >= 4 && < 5 + if impl(ghc < 8.0) + buildable: False + else + build-depends: base , ghc-prim -- FIXME armel or mispel is also little endian. -- might be a good idea to also add a runtime autodetect mode. @@ -94,12 +102,10 @@ if flag(support_deepseq) CPP-options: -DWITH_DEEPSEQ_SUPPORT Build-depends: deepseq >= 1.1 - if flag(support_foundation) - CPP-options: -DWITH_FOUNDATION_SUPPORT - Build-depends: basement, - foundation >= 0.0.8 - if impl(ghc >= 8.0) - Exposed-modules: Data.ByteArray.Sized + if flag(support_foundation) || flag(support_basement) + CPP-options: -DWITH_BASEMENT_SUPPORT + Build-depends: basement + exposed-modules: Data.ByteArray.Sized ghc-options: -Wall -fwarn-tabs default-language: Haskell2010 @@ -111,12 +117,23 @@ Other-modules: Imports SipHash Utils - Build-Depends: base >= 3 && < 5 + Build-Depends: base , bytestring , memory - , basement - , foundation >= 0.0.8 + , basement >= 0.0.7 + , foundation ghc-options: -Wall -fno-warn-orphans -fno-warn-missing-signatures -threaded default-language: Haskell2010 if flag(support_foundation) - CPP-options: -DWITH_FOUNDATION_SUPPORT + CPP-options: -DWITH_BASEMENT_SUPPORT + +-- Test-Suite test-examples +-- default-language: Haskell2010 +-- type: exitcode-stdio-1.0 +-- hs-source-dirs: tests +-- ghc-options: -threaded +-- Main-is: DocTests.hs +-- Build-Depends: base >= 3 && < 5 +-- , memory +-- , bytestring +-- , doctest diff --git a/tests/Tests.hs b/tests/Tests.hs --- a/tests/Tests.hs +++ b/tests/Tests.hs @@ -19,11 +19,8 @@ import qualified SipHash -#ifdef WITH_FOUNDATION_SUPPORT -import qualified Foundation as F -#if MIN_VERSION_basement(0,0,5) +#ifdef WITH_BASEMENT_SUPPORT import Basement.Block (Block) -#endif import Basement.UArray (UArray) #endif @@ -33,7 +30,7 @@ arbitrary = Positive <$> between (0, 255) data Backend = BackendByte | BackendScrubbedBytes -#ifdef WITH_FOUNDATION_SUPPORT +#ifdef WITH_BASEMENT_SUPPORT #if MIN_VERSION_basement(0,0,5) | BackendBlock #endif @@ -52,7 +49,7 @@ case backend of BackendByte -> ArbitraryBS `fmap` ((B.pack `fmap` replicateM (fromIntegral n) arbitrary) :: Gen Bytes) BackendScrubbedBytes -> ArbitraryBS `fmap` ((B.pack `fmap` replicateM (fromIntegral n) arbitrary) :: Gen ScrubbedBytes) -#ifdef WITH_FOUNDATION_SUPPORT +#ifdef WITH_BASEMENT_SUPPORT #if MIN_VERSION_basement(0,0,5) BackendBlock -> ArbitraryBS `fmap` ((B.pack `fmap` replicateM (fromIntegral n) arbitrary) :: Gen (Block Word8)) #endif @@ -82,10 +79,8 @@ Group x [ Group "Bytes" (l withBytesWitness) , Group "ScrubbedBytes" (l withScrubbedBytesWitness) -#ifdef WITH_FOUNDATION_SUPPORT -#if MIN_VERSION_basement(0,0,5) +#ifdef WITH_BASEMENT_SUPPORT , Group "Block" (l withBlockWitness) -#endif , Group "UArray" (l withUArrayWitness) #endif ] @@ -222,7 +217,7 @@ ] , testShowProperty "showing" $ \witnessID expectedShow (Words8 l) -> (show . witnessID . B.pack $ l) == expectedShow l -#ifdef WITH_FOUNDATION_SUPPORT +#ifdef WITH_BASEMENT_SUPPORT , testFoundationTypes #endif ] @@ -278,19 +273,19 @@ in B.span (const False) b == (B.empty, b) ] -#ifdef WITH_FOUNDATION_SUPPORT -testFoundationTypes = Group "Foundation" - [ CheckPlan "allocRet 4 _ :: F.UArray Int8 === 4" $ do - x <- pick "allocateRet 4 _" $ (B.length :: F.UArray F.Int8 -> Int) . snd <$> B.allocRet 4 (const $ return ()) +#ifdef WITH_BASEMENT_SUPPORT +testFoundationTypes = Group "Basement" + [ CheckPlan "allocRet 4 _ :: UArray Int8 === 4" $ do + x <- pick "allocateRet 4 _" $ (B.length :: UArray Int8 -> Int) . snd <$> B.allocRet 4 (const $ return ()) validate "4 === x" $ x === 4 - , CheckPlan "allocRet 4 _ :: F.UArray Int16 === 4" $ do - x <- pick "allocateRet 4 _" $ (B.length :: F.UArray F.Int16 -> Int) . snd <$> B.allocRet 4 (const $ return ()) + , CheckPlan "allocRet 4 _ :: UArray Int16 === 4" $ do + x <- pick "allocateRet 4 _" $ (B.length :: UArray Int16 -> Int) . snd <$> B.allocRet 4 (const $ return ()) validate "4 === x" $ x === 4 - , CheckPlan "allocRet 4 _ :: F.UArray Int32 === 4" $ do - x <- pick "allocateRet 4 _" $ (B.length :: F.UArray F.Int32 -> Int) . snd <$> B.allocRet 4 (const $ return ()) + , CheckPlan "allocRet 4 _ :: UArray Int32 === 4" $ do + x <- pick "allocateRet 4 _" $ (B.length :: UArray Int32 -> Int) . snd <$> B.allocRet 4 (const $ return ()) validate "4 === x" $ x === 4 - , CheckPlan "allocRet 4 _ :: F.UArray Int64 === 8" $ do - x <- pick "allocateRet 4 _" $ (B.length :: F.UArray F.Int64 -> Int) . snd <$> B.allocRet 4 (const $ return ()) + , CheckPlan "allocRet 4 _ :: UArray Int64 === 8" $ do + x <- pick "allocateRet 4 _" $ (B.length :: UArray Int64 -> Int) . snd <$> B.allocRet 4 (const $ return ()) validate "8 === x" $ x === 8 ] #endif diff --git a/tests/Utils.hs b/tests/Utils.hs --- a/tests/Utils.hs +++ b/tests/Utils.hs @@ -4,8 +4,7 @@ import Data.Word import Data.ByteArray (Bytes, ScrubbedBytes) -#ifdef WITH_FOUNDATION_SUPPORT -import qualified Foundation as F +#ifdef WITH_BASEMENT_SUPPORT import Basement.Block (Block) import Basement.UArray (UArray) #endif @@ -28,7 +27,7 @@ withScrubbedBytesWitness :: ScrubbedBytes -> ScrubbedBytes withScrubbedBytesWitness = id -#ifdef WITH_FOUNDATION_SUPPORT +#ifdef WITH_BASEMENT_SUPPORT withBlockWitness :: Block Word8 -> Block Word8 withBlockWitness = withWitness (Witness :: Witness (Block Word8))