mirror of
https://github.com/composewell/streamly.git
synced 2024-10-27 12:12:05 +03:00
Update documentation
This commit is contained in:
parent
f6ffd35db8
commit
bdb59e7262
@ -22,19 +22,8 @@
|
|||||||
-- better performance compared to @[a]@. Standard list, string and list
|
-- better performance compared to @[a]@. Standard list, string and list
|
||||||
-- comprehension syntax can be used with the 'List' type by enabling
|
-- comprehension syntax can be used with the 'List' type by enabling
|
||||||
-- 'OverloadedLists', 'OverloadedStrings' and 'MonadComprehensions' GHC
|
-- 'OverloadedLists', 'OverloadedStrings' and 'MonadComprehensions' GHC
|
||||||
-- extensions. If you want to replace streamly lists with standard lists, all
|
-- extensions. There would be a slight difference in the 'Show' and 'Read'
|
||||||
-- you need to do is import these definitions:
|
-- strings of streamly list as compared to regular lists.
|
||||||
--
|
|
||||||
-- @
|
|
||||||
-- type List = []
|
|
||||||
-- pattern Nil <- [] where Nil = []
|
|
||||||
-- pattern Cons x xs = x : xs
|
|
||||||
-- infixr 5 `Cons`
|
|
||||||
-- {-\# COMPLETE Cons, Nil #-}
|
|
||||||
-- @
|
|
||||||
--
|
|
||||||
-- Other than that there would be a slight difference in the 'Show' and
|
|
||||||
-- 'Read' strings.
|
|
||||||
--
|
--
|
||||||
-- Conversion to stream types is free, any stream combinator can be used on
|
-- Conversion to stream types is free, any stream combinator can be used on
|
||||||
-- lists by converting them to streams. However, for convenience, this module
|
-- lists by converting them to streams. However, for convenience, this module
|
||||||
@ -45,9 +34,23 @@
|
|||||||
-- List $ S.map (+ 1) $ toSerial (1 \`Cons\` Nil)
|
-- List $ S.map (+ 1) $ toSerial (1 \`Cons\` Nil)
|
||||||
-- @
|
-- @
|
||||||
--
|
--
|
||||||
-- 'Data.Foldable.toList' from 'Foldable' and 'GHC.Exts.toList' and
|
-- To convert a 'List' to regular lists, you can use any of the following:
|
||||||
-- 'GHC.Exts.fromList' from 'IsList' can also be used to convert to and from
|
--
|
||||||
-- standard lists.
|
-- * @toList . toSerial@ and @toSerial . fromList@
|
||||||
|
-- * 'Data.Foldable.toList' from "Data.Foldable"
|
||||||
|
-- * 'GHC.Exts.toList' and 'GHC.Exts.fromList' from 'IsList' in "GHC.Exts"
|
||||||
|
--
|
||||||
|
-- If you have made use of 'Nil' and 'Cons' constructors in the code and you
|
||||||
|
-- want to replace streamly lists with standard lists, all you need to do is
|
||||||
|
-- import these definitions:
|
||||||
|
--
|
||||||
|
-- @
|
||||||
|
-- type List = []
|
||||||
|
-- pattern Nil <- [] where Nil = []
|
||||||
|
-- pattern Cons x xs = x : xs
|
||||||
|
-- infixr 5 `Cons`
|
||||||
|
-- {-\# COMPLETE Cons, Nil #-}
|
||||||
|
-- @
|
||||||
--
|
--
|
||||||
-- See <src/docs/streamly-vs-lists.md> for more details and
|
-- See <src/docs/streamly-vs-lists.md> for more details and
|
||||||
-- <src/test/PureStreams.hs> for comprehensive usage examples.
|
-- <src/test/PureStreams.hs> for comprehensive usage examples.
|
||||||
@ -61,6 +64,8 @@ module Streamly.List
|
|||||||
, pattern Nil
|
, pattern Nil
|
||||||
, pattern Cons
|
, pattern Cons
|
||||||
#endif
|
#endif
|
||||||
|
-- XXX we may want to use rebindable syntax for variants instead of using
|
||||||
|
-- different types (applicative do and apWith).
|
||||||
, ZipList (..)
|
, ZipList (..)
|
||||||
, fromZipList
|
, fromZipList
|
||||||
, toZipList
|
, toZipList
|
||||||
@ -84,9 +89,16 @@ import qualified Streamly.Streams.StreamK as K
|
|||||||
-- using a stream type the programmer needs to specify the Monad otherwise the
|
-- using a stream type the programmer needs to specify the Monad otherwise the
|
||||||
-- type remains ambiguous.
|
-- type remains ambiguous.
|
||||||
--
|
--
|
||||||
|
-- XXX once we separate consM from IsStream or remove the MonadIO and
|
||||||
|
-- MonadBaseControlIO dependency from it, then we can make this an instance of
|
||||||
|
-- IsStream and use the regular polymorphic functions on Lists as well. Once
|
||||||
|
-- that happens we can change the Show and Read instances as well to use "1 >:
|
||||||
|
-- 2 >: nil" etc. or should we use a separate constructor indicating the "List"
|
||||||
|
-- type ":>" for better inference?
|
||||||
|
--
|
||||||
-- | @List a@ is a replacement for @[a]@.
|
-- | @List a@ is a replacement for @[a]@.
|
||||||
--
|
--
|
||||||
-- @since 0.5.3
|
-- @since 0.6.0
|
||||||
newtype List a = List { toSerial :: SerialT Identity a }
|
newtype List a = List { toSerial :: SerialT Identity a }
|
||||||
deriving (Show, Read, Eq, Ord, NFData, NFData1
|
deriving (Show, Read, Eq, Ord, NFData, NFData1
|
||||||
, Semigroup, Monoid, Functor, Foldable
|
, Semigroup, Monoid, Functor, Foldable
|
||||||
@ -108,10 +120,16 @@ instance IsList (List a) where
|
|||||||
-- Patterns
|
-- Patterns
|
||||||
------------------------------------------------------------------------------
|
------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
-- Note: When using the OverloadedLists extension we should be able to pattern
|
||||||
|
-- match using the regular list contructors. OverloadedLists uses 'toList' to
|
||||||
|
-- perform the pattern match, it should not be too bad as it works lazily in
|
||||||
|
-- the Identity monad. We need these patterns only when not using that
|
||||||
|
-- extension.
|
||||||
|
--
|
||||||
-- | An empty list constructor and pattern that matches an empty 'List'.
|
-- | An empty list constructor and pattern that matches an empty 'List'.
|
||||||
-- Corresponds to '[]' for Haskell lists.
|
-- Corresponds to '[]' for Haskell lists.
|
||||||
--
|
--
|
||||||
-- @since 0.5.3
|
-- @since 0.6.0
|
||||||
pattern Nil :: List a
|
pattern Nil :: List a
|
||||||
pattern Nil <- (runIdentity . K.null . toSerial -> True) where
|
pattern Nil <- (runIdentity . K.null . toSerial -> True) where
|
||||||
Nil = List K.nil
|
Nil = List K.nil
|
||||||
@ -121,7 +139,7 @@ infixr 5 `Cons`
|
|||||||
-- | A list constructor and pattern that deconstructs a 'List' into its head
|
-- | A list constructor and pattern that deconstructs a 'List' into its head
|
||||||
-- and tail. Corresponds to ':' for Haskell lists.
|
-- and tail. Corresponds to ':' for Haskell lists.
|
||||||
--
|
--
|
||||||
-- @since 0.5.3
|
-- @since 0.6.0
|
||||||
pattern Cons :: a -> List a -> List a
|
pattern Cons :: a -> List a -> List a
|
||||||
pattern Cons x xs <-
|
pattern Cons x xs <-
|
||||||
(fmap (second List) . runIdentity . K.uncons . toSerial
|
(fmap (second List) . runIdentity . K.uncons . toSerial
|
||||||
@ -139,7 +157,7 @@ pattern Cons x xs <-
|
|||||||
-- | Just like 'List' except that it has a zipping 'Applicative' instance
|
-- | Just like 'List' except that it has a zipping 'Applicative' instance
|
||||||
-- and no 'Monad' instance.
|
-- and no 'Monad' instance.
|
||||||
--
|
--
|
||||||
-- @since 0.5.3
|
-- @since 0.6.0
|
||||||
newtype ZipList a = ZipList { toZipSerial :: ZipSerialM Identity a }
|
newtype ZipList a = ZipList { toZipSerial :: ZipSerialM Identity a }
|
||||||
deriving (Show, Read, Eq, Ord, NFData, NFData1
|
deriving (Show, Read, Eq, Ord, NFData, NFData1
|
||||||
, Semigroup, Monoid, Functor, Foldable
|
, Semigroup, Monoid, Functor, Foldable
|
||||||
@ -159,12 +177,12 @@ instance IsList (ZipList a) where
|
|||||||
|
|
||||||
-- | Convert a 'ZipList' to a regular 'List'
|
-- | Convert a 'ZipList' to a regular 'List'
|
||||||
--
|
--
|
||||||
-- @since 0.5.3
|
-- @since 0.6.0
|
||||||
fromZipList :: ZipList a -> List a
|
fromZipList :: ZipList a -> List a
|
||||||
fromZipList = List . K.adapt . toZipSerial
|
fromZipList = List . K.adapt . toZipSerial
|
||||||
|
|
||||||
-- | Convert a regular 'List' to a 'ZipList'
|
-- | Convert a regular 'List' to a 'ZipList'
|
||||||
--
|
--
|
||||||
-- @since 0.5.3
|
-- @since 0.6.0
|
||||||
toZipList :: List a -> ZipList a
|
toZipList :: List a -> ZipList a
|
||||||
toZipList = ZipList . K.adapt . toSerial
|
toZipList = ZipList . K.adapt . toSerial
|
||||||
|
Loading…
Reference in New Issue
Block a user