-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An implementation of the Futhark data format.
--   
--   The Futhark compiler and its tools uses a simple external data
--   representation to encode arrays and scalars. This package implements
--   both a Haskell-level representation of these values, as well as
--   utility functions for reading and writing values in both the textual
--   and binary format.
@package futhark-data
@version 1.0.2.0


-- | This module defines an efficient value representation of the Futhark
--   data format.
module Futhark.Data

-- | An efficiently represented Futhark value, represented as a shape
--   vector and a value vector, which contains elements in row-major order.
--   The size of the value vector must be equal to the product of the shape
--   vector. This is not enforced by the representation, but consuming
--   functions may give unexpected results if this invariant is broken.
--   Scalars are represented with an empty shape vector.
--   
--   Use <a>valueText</a> to get a human-readable representation, and
--   <a>put</a> to obtain binary a representation.
--   
--   The <a>Eq</a> instance is the naive one, meaning that no values
--   containing NaNs will be considered equal. Use the functions from
--   <a>Futhark.Data.Compare</a> if this is not what you want.
data Value
I8Value :: Vector Int -> Vector Int8 -> Value
I16Value :: Vector Int -> Vector Int16 -> Value
I32Value :: Vector Int -> Vector Int32 -> Value
I64Value :: Vector Int -> Vector Int64 -> Value
U8Value :: Vector Int -> Vector Word8 -> Value
U16Value :: Vector Int -> Vector Word16 -> Value
U32Value :: Vector Int -> Vector Word32 -> Value
U64Value :: Vector Int -> Vector Word64 -> Value
F16Value :: Vector Int -> Vector Half -> Value
F32Value :: Vector Int -> Vector Float -> Value
F64Value :: Vector Int -> Vector Double -> Value
BoolValue :: Vector Int -> Vector Bool -> Value

-- | The value vector type.
type Vector = Vector

-- | Construct a textual representation of the value as a strict text.
valueText :: Value -> Text

-- | The scalar types supported by the value format.
data PrimType
I8 :: PrimType
I16 :: PrimType
I32 :: PrimType
I64 :: PrimType
U8 :: PrimType
U16 :: PrimType
U32 :: PrimType
U64 :: PrimType
F16 :: PrimType
F32 :: PrimType
F64 :: PrimType
Bool :: PrimType

-- | Textual primitive type as a strict text.
primTypeText :: PrimType -> Text

-- | The number of bytes taken up by a single element of this type.
primTypeBytes :: PrimType -> Int

-- | The type of a simple Futhark value, comprising a shape and an element
--   type.
data ValueType
ValueType :: [Int] -> PrimType -> ValueType

-- | Prettyprint a value type with empty dimensions as a strict text. This
--   is needed for Futhark server programs, whose types are un-sized.
valueTypeTextNoDims :: ValueType -> Text

-- | Get the type of a value.
valueType :: Value -> ValueType

-- | Get the element type of a value.
valueElemType :: Value -> PrimType

-- | The shape of a value. Empty list in case of a scalar.
valueShape :: Value -> [Int]

-- | Prettyprint a value type as a strict text.
valueTypeText :: ValueType -> Text

-- | A class for Haskell values that can be retrieved from <a>Value</a>.
--   This is a convenience facility - don't expect it to be fast.
class GetValue t
getValue :: GetValue t => Value -> Maybe t

-- | A class for Haskell values that can be converted to <a>Value</a>. This
--   is a convenience facility - don't expect it to be fast.
class PutValue t

-- | This may fail for cases such as irregular arrays.
putValue :: PutValue t => t -> Maybe Value

-- | Produce a list of the immediate elements of the value. That is, a 2D
--   array will produce a list of 1D values. A zero-dimensional value will
--   produce an empty list. While lists are of course inefficient, the
--   actual values are just slices of the original value, which makes them
--   fairly space-efficient (but beware space leaks).
valueElems :: Value -> [Value]
instance GHC.Show.Show Futhark.Data.Value
instance GHC.Classes.Eq Futhark.Data.Value
instance GHC.Enum.Bounded Futhark.Data.PrimType
instance GHC.Enum.Enum Futhark.Data.PrimType
instance GHC.Show.Show Futhark.Data.PrimType
instance GHC.Classes.Ord Futhark.Data.PrimType
instance GHC.Classes.Eq Futhark.Data.PrimType
instance GHC.Show.Show Futhark.Data.ValueType
instance GHC.Classes.Ord Futhark.Data.ValueType
instance GHC.Classes.Eq Futhark.Data.ValueType
instance Futhark.Data.PutValue GHC.Int.Int8
instance Futhark.Data.PutValue GHC.Int.Int16
instance Futhark.Data.PutValue GHC.Int.Int32
instance Futhark.Data.PutValue GHC.Int.Int64
instance Futhark.Data.PutValue GHC.Word.Word8
instance Futhark.Data.PutValue GHC.Word.Word16
instance Futhark.Data.PutValue GHC.Word.Word32
instance Futhark.Data.PutValue GHC.Word.Word64
instance Futhark.Data.PutValue [Futhark.Data.Value]
instance Futhark.Data.PutValue Data.Text.Internal.Text
instance Futhark.Data.PutValue Data.ByteString.Internal.ByteString
instance Futhark.Data.GetValue t => Futhark.Data.GetValue [t]
instance Futhark.Data.GetValue GHC.Types.Bool
instance Futhark.Data.GetValue GHC.Int.Int8
instance Futhark.Data.GetValue GHC.Int.Int16
instance Futhark.Data.GetValue GHC.Int.Int32
instance Futhark.Data.GetValue GHC.Int.Int64
instance Futhark.Data.GetValue GHC.Word.Word8
instance Futhark.Data.GetValue GHC.Word.Word16
instance Futhark.Data.GetValue GHC.Word.Word32
instance Futhark.Data.GetValue GHC.Word.Word64
instance Data.Binary.Class.Binary Futhark.Data.Value


-- | Facilities for comparing values for equality. While <a>Eq</a>
--   instances are defined, these are not useful when NaNs are involved,
--   and do not *explain* the differences.
module Futhark.Data.Compare

-- | Compare two Futhark values for equality.
compareValues :: Tolerance -> Value -> Value -> [Mismatch]

-- | As <a>compareValues</a>, but compares several values. The two lists
--   must have the same length.
compareSeveralValues :: Tolerance -> [Value] -> [Value] -> [Mismatch]

-- | The maximum relative tolerance used for comparing floating-point
--   results. 0.002 (0.2%) is a fine default if you have no particular
--   opinion.
newtype Tolerance
Tolerance :: Double -> Tolerance

-- | Two values differ in some way. The <a>Show</a> instance produces a
--   human-readable explanation.
data Mismatch
instance GHC.Show.Show Futhark.Data.Compare.Tolerance
instance GHC.Classes.Ord Futhark.Data.Compare.Tolerance
instance GHC.Classes.Eq Futhark.Data.Compare.Tolerance
instance GHC.Show.Show Futhark.Data.Compare.Mismatch


-- | Megaparsec-based parser for <a>Value</a>s in the textual value format.
--   The difference between this and the reader defined in
--   <a>Futhark.Data.Reader</a> is that we don't try to handle both the
--   textual and binary format - only the former. On the other hand, this
--   parser has (much) better error messages and can be easily used by
--   other parsers (like the ones for FutharkScript or test blocks).
module Futhark.Data.Parser

-- | Parse the name of a primitive type. Does *not* consume any trailing
--   whitespace, nor does it permit any internal whitespace.
parsePrimType :: Parsec Void Text PrimType

-- | Parse a type. Does *not* consume any trailing whitespace, nor does it
--   permit any internal whitespace.
parseType :: Parsec Void Text ValueType

-- | Parse a primitive value. Does *not* consume any trailing whitespace,
--   nor does it permit any internal whitespace.
parsePrimValue :: Parsec Void Text Value

-- | Parse a value, given a post-lexeme parser for whitespace.
parseValue :: Parsec Void Text () -> Parsec Void Text Value


-- | The value reader can handle a delightful mix of binary and textual
--   input. It is the most general way of reading values, but it is less
--   efficient than using the <a>Get</a> instance if you know that the data
--   will be in the binary format.
module Futhark.Data.Reader

-- | Parse Futhark values from the given bytestring.
readValues :: ByteString -> Maybe [Value]