feat(third_party/bazel): Check in rules_haskell from Tweag

third_party/bazel/rules_haskell/examples/primitive/Data/Primitive.hs

@@ -0,0 +1,85 @@
+{-# LANGUAGE MagicHash #-}
+{-# OPTIONS_GHC -fno-warn-duplicate-exports #-}
+-- |
+-- Module      : Data.Primitive
+-- Copyright   : (c) Roman Leshchinskiy 2009-2012
+-- License     : BSD-style
+--
+-- Maintainer  : Roman Leshchinskiy <rl@cse.unsw.edu.au>
+-- Portability : non-portable
+--
+-- Reexports all primitive operations
+--
+module Data.Primitive (
+  -- * Re-exports
+  module Data.Primitive.Types
+  ,module Data.Primitive.Array
+  ,module Data.Primitive.ByteArray
+  ,module Data.Primitive.Addr
+  ,module Data.Primitive.SmallArray
+  ,module Data.Primitive.UnliftedArray
+  ,module Data.Primitive.PrimArray
+  ,module Data.Primitive.MutVar
+  -- * Naming Conventions
+  -- $namingConventions
+) where
+
+import Data.Primitive.Types
+import Data.Primitive.Array
+import Data.Primitive.ByteArray
+import Data.Primitive.Addr
+import Data.Primitive.SmallArray
+import Data.Primitive.UnliftedArray
+import Data.Primitive.PrimArray
+import Data.Primitive.MutVar
+
+{- $namingConventions
+For historical reasons, this library embraces the practice of suffixing
+the name of a function with the type it operates on. For example, three
+of the variants of the array indexing function are:
+
+> indexArray      ::           Array      a -> Int -> a
+> indexSmallArray ::           SmallArray a -> Int -> a
+> indexPrimArray  :: Prim a => PrimArray  a -> Int -> a
+
+In a few places, where the language sounds more natural, the array type
+is instead used as a prefix. For example, @Data.Primitive.SmallArray@
+exports @smallArrayFromList@, which would sound unnatural if it used
+@SmallArray@ as a suffix instead.
+
+This library provides several functions traversing, building, and filtering
+arrays. These functions are suffixed with an additional character to
+indicate their the nature of their effectfulness:
+
+* No suffix: A non-effectful pass over the array.
+* @-A@ suffix: An effectful pass over the array, where the effect is 'Applicative'.
+* @-P@ suffix: An effectful pass over the array, where the effect is 'PrimMonad'.
+
+Additionally, an apostrophe can be used to indicate strictness in the elements.
+The variants with an apostrophe are used in @Data.Primitive.Array@ but not
+in @Data.Primitive.PrimArray@ since the array type it provides is always strict in the element.
+For example, there are three variants of the function that filters elements
+from a primitive array.
+
+> filterPrimArray  :: (Prim a               ) => (a ->   Bool) -> PrimArray a ->    PrimArray a
+> filterPrimArrayA :: (Prim a, Applicative f) => (a -> f Bool) -> PrimArray a -> f (PrimArray a)
+> filterPrimArrayP :: (Prim a, PrimMonad   m) => (a -> m Bool) -> PrimArray a -> m (PrimArray a)
+
+As long as the effectful context is a monad that is sufficiently affine
+the behaviors of the 'Applicative' and 'PrimMonad' variants produce the same results
+and differ only in their strictness. Monads that are sufficiently affine
+include:
+
+* 'IO' and 'ST'
+* Any combination of 'MaybeT', 'ExceptT', 'StateT' and 'Writer' on top
+  of another sufficiently affine monad.
+
+There is one situation where the names deviate from effectful suffix convention
+described above. Throughout the haskell ecosystem, the 'Applicative' variant of
+'map' is known as 'traverse', not @mapA@. Consequently, we adopt the following
+naming convention for mapping:
+
+> mapPrimArray :: (Prim a, Prim b) => (a -> b) -> PrimArray a -> PrimArray b
+> traversePrimArray :: (Applicative f, Prim a, Prim b) => (a -> f b) -> PrimArray a -> f (PrimArray b)
+> traversePrimArrayP :: (PrimMonad m, Prim a, Prim b) => (a -> m b) -> PrimArray a -> m (PrimArray b)
+-}