ST package:rio

The strict ST monad. The ST monad allows for destructive updates, but is escapable (unlike IO). A computation of type ST s a returns a value of type a, and execute in "thread" s. The s parameter is either

• an uninstantiated type variable (inside invocations of runST), or
• RealWorld (inside invocations of stToIO).

It serves to keep the internal states of different invocations of runST separate from each other and from invocations of stToIO. The >>= and >> operations are strict in the state (though not in values stored in the state). For example,

runST (writeSTRef _|_ v >>= f) = _|_

Type synonym for the strict flavour of ByteString.

The member functions of this class facilitate writing values of primitive types to raw memory (which may have been allocated with the above mentioned routines) and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types. Memory addresses are represented as values of type Ptr a, for some a which is an instance of class Storable. The type argument to Ptr helps provide some valuable type safety in FFI code (you can't mix pointers of different types without an explicit cast), while helping the Haskell type system figure out which marshalling method is needed for a given pointer. All marshalling between Haskell and a foreign language ultimately boils down to translating Haskell data structures into the binary representation of a corresponding data structure of the foreign language and vice versa. To code this marshalling in Haskell, it is necessary to manipulate primitive data types stored in unstructured memory blocks. The class Storable facilitates this manipulation on all types for which it is instantiated, which are the standard basic types of Haskell, the fixed size Int types (Int8, Int16, Int32, Int64), the fixed size Word types (Word8, Word16, Word32, Word64), StablePtr, all types from Foreign.C.Types, as well as Ptr.

String is an alias for a list of characters. String constants in Haskell are values of type String. That means if you write a string literal like "hello world", it will have the type [Char], which is the same as String. Note: You can ask the compiler to automatically infer different types with the -XOverloadedStrings language extension, for example "hello world" :: Text. See IsString for more information. Because String is just a list of characters, you can use normal list functions to do basic string manipulation. See Data.List for operations on lists.

Performance considerations

[Char] is a relatively memory-inefficient type. It is a linked list of boxed word-size characters, internally it looks something like:

╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭─────┬───┬──╮  ╭────╮
│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ (:) │   │ ─┼─>│ [] │
╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰─────┴─┼─┴──╯  ╰────╯
v               v               v
'a'             'b'             'c'

The String "abc" will use 5*3+1 = 16 (in general 5n+1) words of space in memory. Furthermore, operations like (++) (string concatenation) are O(n) (in the left argument). For historical reasons, the base library uses String in a lot of places for the conceptual simplicity, but library code dealing with user-data should use the text package for Unicode text, or the the bytestring package for binary data.

A specification for how to create one of the three standard child streams, stdin, stdout and stderr. A StreamSpec can be thought of as containing

1. A type safe version of StdStream from System.Process. This determines whether the stream should be inherited from the parent process, piped to or from a Handle, etc.
2. A means of accessing the stream as a value of type a
3. A cleanup action which will be run on the stream once the process terminates

To create a StreamSpec see the section Stream specs.

Whether a stream is an input stream or output stream. Note that this is from the perspective of the child process, so that a child's standard input stream is an STInput, even though the parent process will be writing to it.

Provides reexports of MonadState and related helpers.

A state monad parameterized by the type s of the state to carry. The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

A state transformer monad parameterized by:

• s - The state.
• m - The inner monad.

The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

Storable Vector. Import as:

import qualified RIO.Vector.Storable as VS

This module does not export any partial or unsafe functions. For those, see RIO.Vector.Storable.Partial and RIO.Vector.Storable.Unsafe

O(n) The stripPrefix function takes two ByteStrings and returns Just the remainder of the second iff the first is its prefix, and otherwise Nothing.

O(n) The stripSuffix function takes two ByteStrings and returns Just the remainder of the second iff the first is its suffix, and otherwise Nothing.

Drop the given extension from a FilePath, and the "." preceding it. Returns Nothing if the FilePath does not have the given extension, or Just and the part before the extension if it does. This function can be more predictable than dropExtensions, especially if the filename might itself contain . characters.

stripExtension "hs.o" "foo.x.hs.o" == Just "foo.x"
stripExtension "hi.o" "foo.x.hs.o" == Nothing
dropExtension x == fromJust (stripExtension (takeExtension x) x)
dropExtensions x == fromJust (stripExtension (takeExtensions x) x)
stripExtension ".c.d" "a.b.c.d"  == Just "a.b"
stripExtension ".c.d" "a.b..c.d" == Just "a.b."
stripExtension "baz"  "foo.bar"  == Nothing
stripExtension "bar"  "foobar"   == Nothing
stripExtension ""     x          == Just x

The stripPrefix function drops the given prefix from a list. It returns Nothing if the list did not start with the prefix given, or Just the list after the prefix, if it does.

Examples

>>> stripPrefix "foo" "foobar"
Just "bar"

>>> stripPrefix "foo" "foo"
Just ""

>>> stripPrefix "foo" "barfoo"
Nothing

>>> stripPrefix "foo" "barfoobaz"
Nothing

Remove the suffix from the given list, if present

Launch a process based on the given ProcessConfig. You should ensure that you call stopProcess on the result. It's usually better to use one of the functions in this module which ensures stopProcess is called, such as withProcessWait.

Close a process and release any resources acquired. This will ensure terminateProcess is called, wait for the process to actually exit, and then close out resources allocated for the streams. In the event of any cleanup exceptions being thrown this will throw an exception.

Embed a simple state action into the monad.

O(n) Remove leading and trailing white space from a string. Equivalent to:

dropAround isSpace

O(n) Remove trailing white space from a string. Equivalent to:

dropWhileEnd isSpace

O(n) Return the suffix of the second string if its prefix matches the entire first string. Examples:

>>> stripPrefix "foo" "foobar"
Just "bar"

>>> stripPrefix ""    "baz"
Just "baz"

>>> stripPrefix "foo" "quux"
Nothing

This is particularly useful with the ViewPatterns extension to GHC, as follows:

{-# LANGUAGE ViewPatterns #-}
import Data.Text as T

fnordLength :: Text -> Int
fnordLength (stripPrefix "fnord" -> Just suf) = T.length suf
fnordLength _                                 = -1