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


-- | Read and write IDX data that is used in e.g. the MNIST database.
--   
--   This package provides functionality to read and write data in the IDX
--   binary format. This format is relevant for machine learning
--   applications, like the MNIST handwritten digit database.
@package mnist-idx
@version 0.1.2.8


-- | An internal package, the API contained here should not be used and is
--   subject to possibly breaking changes. Use these functions and types at
--   your own risk.
--   
--   The safe interface is in <a>IDX</a>
module Data.IDX.Internal

-- | A type to describe the content, according to IDX spec
data IDXContentType
[IDXUnsignedByte] :: IDXContentType
[IDXSignedByte] :: IDXContentType
[IDXShort] :: IDXContentType
[IDXInt] :: IDXContentType
[IDXFloat] :: IDXContentType
[IDXDouble] :: IDXContentType

-- | Datatype for storing IDXData. Internally data is always stored either
--   as <a>Int</a> or <a>Double</a> unboxed vectors. However when binary
--   serialization is used, the data is serialized according to the
--   <a>IDXContentType</a>.
data IDXData
IDXInts :: IDXContentType -> (Vector Int) -> (Vector Int) -> IDXData
IDXDoubles :: IDXContentType -> (Vector Int) -> (Vector Double) -> IDXData

-- | A data type that holds <a>Int</a> labels for a set of <a>IDXData</a>
newtype IDXLabels
IDXLabels :: (Vector Int) -> IDXLabels

-- | Return the what type the data is stored in
idxType :: IDXData -> IDXContentType

-- | Return an unboxed Vector of Int dimensions
idxDimensions :: IDXData -> Vector Int

-- | Return wether the data in this IDXData value is stored as integral
--   values
isIDXIntegral :: IDXData -> Bool

-- | Return wether the data in this IDXData value is stored as double
--   values
isIDXReal :: IDXData -> Bool

-- | Return contained ints, if no ints are contained, convert content to
--   ints by using <a>round</a>. Data is stored like in a C-array, i.e. the
--   last index changes first.
idxIntContent :: IDXData -> Vector Int

-- | Return contained doubles, if no doubles are contained convert the
--   content to double by using <a>fromIntegral</a>. Data is stored like in
--   a C-array, i.e. the last index changes first.
idxDoubleContent :: IDXData -> Vector Double

-- | Helper function to read a (possibly big) vector of binary values as
--   chunks. Strictly evaluates each chunk and then concatenates the
--   chunks, does not leak space.
readContent :: (Unbox a) => (Int -> Get (Vector a)) -> Int -> Int -> Get (Vector a)
getInt8 :: Get Int8
getInt16 :: Get Int16
getInt32 :: Get Int32
getFloat :: Get Float
getDouble :: Get Double

-- | Helper function for parsing integer data from the IDX content. Returns
--   a full IDX result.
buildIntResult :: Integral a => Int -> IDXContentType -> Vector Int -> Get a -> Get IDXData

-- | Helper function for parsing real number data from the IDX content.
buildDoubleResult :: Real a => Int -> IDXContentType -> Vector Int -> Get a -> Get IDXData

-- | Put values that are saved as Int
putIntegral :: IDXContentType -> Int -> Put

-- | Put real values that are saved as Double
putReal :: IDXContentType -> Double -> Put
instance GHC.Show.Show Data.IDX.Internal.IDXData
instance GHC.Show.Show Data.IDX.Internal.IDXContentType
instance Data.Binary.Class.Binary Data.IDX.Internal.IDXLabels
instance Data.Binary.Class.Binary Data.IDX.Internal.IDXData
instance Data.Binary.Class.Binary Data.IDX.Internal.IDXContentType


-- | A package for reading and writing data in the IDX format. This data
--   format is used for machine-learning data sets like the MNIST database
--   of handwritten digits (<a>http://yann.lecun.com/exdb/mnist/</a>)
module Data.IDX

-- | Datatype for storing IDXData. Internally data is always stored either
--   as <a>Int</a> or <a>Double</a> unboxed vectors. However when binary
--   serialization is used, the data is serialized according to the
--   <a>IDXContentType</a>.
data IDXData

-- | A data type that holds <a>Int</a> labels for a set of <a>IDXData</a>
data IDXLabels

-- | A type to describe the content, according to IDX spec
data IDXContentType
[IDXUnsignedByte] :: IDXContentType
[IDXSignedByte] :: IDXContentType
[IDXShort] :: IDXContentType
[IDXInt] :: IDXContentType
[IDXFloat] :: IDXContentType
[IDXDouble] :: IDXContentType

-- | Return the what type the data is stored in
idxType :: IDXData -> IDXContentType

-- | Return an unboxed Vector of Int dimensions
idxDimensions :: IDXData -> Vector Int

-- | Return wether the data in this IDXData value is stored as double
--   values
isIDXReal :: IDXData -> Bool

-- | Return wether the data in this IDXData value is stored as integral
--   values
isIDXIntegral :: IDXData -> Bool

-- | Return contained doubles, if no doubles are contained convert the
--   content to double by using <a>fromIntegral</a>. Data is stored like in
--   a C-array, i.e. the last index changes first.
idxDoubleContent :: IDXData -> Vector Double

-- | Return contained ints, if no ints are contained, convert content to
--   ints by using <a>round</a>. Data is stored like in a C-array, i.e. the
--   last index changes first.
idxIntContent :: IDXData -> Vector Int

-- | Partition a dataset and label each subpartition, return int values
labeledIntData :: IDXLabels -> IDXData -> Maybe [(Int, Vector Int)]

-- | Partition a dataset and label each subpartition, return double values
labeledDoubleData :: IDXLabels -> IDXData -> Maybe [(Int, Vector Double)]
encodeIDXLabels :: IDXLabels -> ByteString
decodeIDXLabels :: ByteString -> Maybe IDXLabels

-- | Read data from a file, return <a>Nothing</a> if something doesn't work
encodeIDXLabelsFile :: IDXLabels -> FilePath -> IO ()

-- | Read labels from a file, return <a>Nothing</a> if something doesn't
--   work
decodeIDXLabelsFile :: FilePath -> IO (Maybe IDXLabels)
encodeIDX :: IDXData -> ByteString
decodeIDX :: ByteString -> Maybe IDXData
encodeIDXFile :: IDXData -> FilePath -> IO ()
decodeIDXFile :: FilePath -> IO (Maybe IDXData)
