Commit 8429d6b4 authored by Lennart Kolmodin's avatar Lennart Kolmodin
Browse files

Merge pull request #90 from phadej/since-0.8

Add since annotations
parents 8d643d14 53ea7cb2
......@@ -31,7 +31,7 @@
-- you are more interested in serializing and deserializing values than
-- in which format will be used, it is possible to derive 'Binary'
-- instances using the generic support. See 'GBinary'.
--
--
-- If you have specific requirements about the encoding format, you can use
-- the encoding and decoding primitives directly, see the modules
-- "Data.Binary.Get" and "Data.Binary.Put".
......@@ -180,6 +180,8 @@ decode = runGet get
-- 'Right' on success. In both cases the unconsumed input and the number of
-- consumed bytes is returned. In case of failure, a human-readable error
-- message will be returned as well.
--
-- /Since: 0.7.0.0/
decodeOrFail :: Binary a => L.ByteString
-> Either (L.ByteString, ByteOffset, String)
(L.ByteString, ByteOffset, a)
......@@ -204,6 +206,8 @@ encodeFile f v = L.writeFile f (encode v)
-- | Decode a value from a file. In case of errors, 'error' will
-- be called with the error message.
--
-- /Since: 0.7.0.0/
decodeFile :: Binary a => FilePath -> IO a
decodeFile f = do
result <- decodeFileOrFail f
......
......@@ -140,6 +140,8 @@ class Binary t where
#ifdef HAS_VOID
-- Void never gets written nor reconstructed since it's impossible to have a
-- value of that type
-- | /Since: 0.8.0.0/
instance Binary Void where
put = absurd
get = mzero
......@@ -274,6 +276,7 @@ roll = foldl' unstep 0 . reverse
-- Fixed-size type for a subset of Natural
type NaturalWord = Word64
-- | /Since: 0.7.3.0/
instance Binary Natural where
{-# INLINE put #-}
put n | n <= hi = do
......@@ -614,6 +617,7 @@ instance (Binary i, Ix i, Binary e, IArray UArray e) => Binary (UArray i e) wher
-- Fingerprints
#ifdef HAS_GHC_FINGERPRINT
-- | /Since: 0.7.6.0/
instance Binary Fingerprint where
put (Fingerprint x1 x2) = do
put x1
......@@ -627,7 +631,7 @@ instance Binary Fingerprint where
------------------------------------------------------------------------
-- Version
-- | /Since: binary-0.8/
-- | /Since: 0.8.0.0/
instance Binary Version where
get = Version <$> get <*> get
put (Version br tags) = put br >> put tags
......@@ -299,6 +299,8 @@ dropHeadChunk lbs =
-- success. In both cases any unconsumed input and the number of bytes
-- consumed is returned. In the case of failure, a human-readable
-- error message is included as well.
--
-- /Since: 0.6.4.0/
runGetOrFail :: Get a -> L.ByteString
-> Either (L.ByteString, ByteOffset, String) (L.ByteString, ByteOffset, a)
runGetOrFail g lbs0 = feedAll (runGetIncremental g) lbs0
......
......@@ -23,7 +23,7 @@ module Data.Binary.Get.Internal (
, withInputChunks
, Consume
, failOnEOF
, get
, put
, ensureN
......@@ -123,6 +123,7 @@ instance Applicative Get where
(<*>) = apG
{-# INLINE (<*>) #-}
-- | /Since: 0.7.1.0/
instance MonadPlus Get where
mzero = empty
mplus = (<|>)
......@@ -192,6 +193,8 @@ bytesRead = C $ \inp k -> BytesRead (fromIntegral $ B.length inp) (k inp)
-- If the given decoder fails, 'isolate' will also fail.
-- Offset from 'bytesRead' will be relative to the start of 'isolate', not the
-- absolute of the input.
--
-- /Since: 0.7.2.0/
isolate :: Int -- ^ The number of bytes that must be consumed
-> Get a -- ^ The decoder to isolate
-> Get a
......@@ -254,6 +257,7 @@ getBytes :: Int -> Get B.ByteString
getBytes = getByteString
{-# INLINE getBytes #-}
-- | /Since: 0.7.0.0/
instance Alternative Get where
empty = C $ \inp _ks -> Fail inp "Data.Binary.Get(Alternative).empty"
(<|>) f g = do
......@@ -272,7 +276,7 @@ instance Alternative Get where
#endif
-- | Run a decoder and keep track of all the input it consumes.
-- Once it's finished, return the final decoder (always 'Done' or 'Fail'),
-- Once it's finished, return the final decoder (always 'Done' or 'Fail'),
-- and unconsume all the the input the decoder required to run.
-- Any additional chunks which was required to run the decoder
-- will also be returned.
......@@ -298,6 +302,8 @@ pushFront bs = C $ \ inp ks -> ks (B.append bs inp) ()
-- | Run the given decoder, but without consuming its input. If the given
-- decoder fails, then so will this function.
--
-- /Since: 0.7.0.0/
lookAhead :: Get a -> Get a
lookAhead g = do
(decoder, bs) <- runAndKeepTrack g
......@@ -309,6 +315,8 @@ lookAhead g = do
-- | Run the given decoder, and only consume its input if it returns 'Just'.
-- If 'Nothing' is returned, the input will be unconsumed.
-- If the given decoder fails, then so will this function.
--
-- /Since: 0.7.0.0/
lookAheadM :: Get (Maybe a) -> Get (Maybe a)
lookAheadM g = do
let g' = maybe (Left ()) Right <$> g
......@@ -317,6 +325,8 @@ lookAheadM g = do
-- | Run the given decoder, and only consume its input if it returns 'Right'.
-- If 'Left' is returned, the input will be unconsumed.
-- If the given decoder fails, then so will this function.
--
-- /Since: 0.7.1.0/
lookAheadE :: Get (Either a b) -> Get (Either a b)
lookAheadE g = do
(decoder, bs) <- runAndKeepTrack g
......@@ -326,8 +336,10 @@ lookAheadE g = do
Fail inp s -> C $ \_ _ -> Fail inp s
_ -> error "Binary: impossible"
-- Label a decoder. If the decoder fails, the label will be appended on
-- | Label a decoder. If the decoder fails, the label will be appended on
-- a new line to the error message string.
--
-- /Since: 0.7.2.0/
label :: String -> Get a -> Get a
label msg decoder = C $ \inp ks ->
let r0 = runCont decoder inp (\inp' a -> Done inp' a)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment