[commit: packages/deepseq] master: Extend documentation of `force` with usage examples (beecf97)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/deepseq

On branch  : master
Link       : http://git.haskell.org/packages/deepseq.git/commitdiff/beecf972eb35257396299818559d710c847e056a

>---------------------------------------------------------------

commit beecf972eb35257396299818559d710c847e056a
Author: Herbert Valerio Riedel <hvr at gnu.org>
Date:   Sun Mar 8 12:00:47 2015 +0100

    Extend documentation of `force` with usage examples


>---------------------------------------------------------------

beecf972eb35257396299818559d710c847e056a
 Control/DeepSeq.hs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Control/DeepSeq.hs b/Control/DeepSeq.hs
index 43edc0b..c39906e 100644
--- a/Control/DeepSeq.hs
+++ b/Control/DeepSeq.hs
@@ -159,6 +159,26 @@ f $!! x = x `deepseq` f x
 -- itself is demanded, so essentially it turns shallow evaluation into
 -- deep evaluation.
 --
+-- 'force' can be conveniently used in combination with @ViewPatterns@:
+--
+-- > {-# LANGUAGE BangPatterns, ViewPatterns #-}
+-- > import Control.DeepSeq
+-- >
+-- > someFun :: ComplexData -> SomeResult
+-- > someFun (force -> !arg) = {- 'arg' will be fully evaluated -}
+--
+-- Another useful application is to combine 'force' with
+-- 'Control.Exception.evaluate' in order to force deep evaluation
+-- relative to other 'IO' operations:
+--
+-- > import Control.Exception (evaluate)
+-- > import Control.DeepSeq
+-- >
+-- > main = do
+-- >   result <- evaluate $ force $ pureComputation
+-- >   {- 'result' will be fully evaluated at this point -}
+-- >   return ()
+--
 -- /Since: 1.2.0.0/
 force :: (NFData a) => a -> a
 force x = x `deepseq` x