Documentation

RandomGen is an interface to pure pseudo-random number generators.

StdGen is the standard RandomGen instance provided by this library.

Since: random-1.0.0

The class of types for which random values can be generated. Most instances of Random will produce values that are uniformly distributed on the full range, but for those types without a well-defined "full range" some sensible default subrange will be selected.

Random exists primarily for backwards compatibility with version 1.1 of this library. In new code, use the better specified Uniform and UniformRange instead.

Since: random-1.0.0

A single possible event occurrence, that is, a value that may or may not occur. Events are used to represent values that are not produced continuously, such as mouse clicks (only produced when the mouse is clicked, as opposed to mouse positions, which are always defined).

The loop operator expresses computations in which an output value is fed back as input, although the computation occurs only once. It underlies the rec value recursion construct in arrow notation. loop should satisfy the following laws:

extension

loop (arr f) = arr (\ b -> fst (fix (\ (c,d) -> f (b,d))))

left tightening

loop (first h >>> f) = h >>> loop f

right tightening

loop (f >>> first h) = loop f >>> h

sliding

loop (f >>> arr (id *** k)) = loop (arr (id *** k) >>> f)

vanishing

loop (loop f) = loop (arr unassoc >>> f >>> arr assoc)

superposing

second (loop f) = loop (arr assoc >>> second f >>> arr unassoc)

where

assoc ((a,b),c) = (a,(b,c))
unassoc (a,(b,c)) = ((a,b),c)

The ArrowApply class is equivalent to Monad: any monad gives rise to a Kleisli arrow, and any instance of ArrowApply defines a monad.

Some arrows allow application of arrow inputs to other inputs. Instances should satisfy the following laws:

• first (arr (\x -> arr (\y -> (x,y)))) >>> app = id

• first (arr (g >>>)) >>> app = second g >>> app

• first (arr (>>> h)) >>> app = app >>> h

Such arrows are equivalent to monads (see ArrowMonad).

Choice, for arrows that support it. This class underlies the if and case constructs in arrow notation.

Instances should satisfy the following laws:

• left (arr f) = arr (left f)

• left (f >>> g) = left f >>> left g

• f >>> arr Left = arr Left >>> left f

• left f >>> arr (id +++ g) = arr (id +++ g) >>> left f

• left (left f) >>> arr assocsum = arr assocsum >>> left f

where

assocsum (Left (Left x)) = Left x
assocsum (Left (Right y)) = Right (Left y)
assocsum (Right z) = Right (Right z)

The other combinators have sensible default definitions, which may be overridden for efficiency.

A monoid on arrows.

Kleisli arrows of a monad.

The basic arrow class.

Instances should satisfy the following laws:

• arr id = id

• arr (f >>> g) = arr f >>> arr g

• first (arr f) = arr (first f)

• first (f >>> g) = first f >>> first g

• first f >>> arr fst = arr fst >>> f

• first f >>> arr (id *** g) = arr (id *** g) >>> first f

• first (first f) >>> arr assoc = arr assoc >>> first f

where

assoc ((a,b),c) = (a,(b,c))

The other combinators have sensible default definitions, which may be overridden for efficiency.

Stepwise, side-effectful MSFs without implicit knowledge of time.

MSFs should be applied to streams or executed indefinitely or until they terminate. See reactimate and reactimateB for details. In general, calling the value constructor MSF or the function unMSF is discouraged.

A sink is an MSF that consumes inputs, while producing no output. It can consume the values with side effects.

A stream is an MSF that produces outputs, while ignoring the input. It can obtain the values from a monadic context.

A reference to reactimate's state, maintained across samples.

Vector space type relation.

A vector space is a set (type) closed under addition and multiplication by a scalar. The type of the scalar is the field of the vector space, and it is said that v is a vector space over a.

The encoding uses a type class |VectorSpace| v a, where v represents the type of the vectors and a represents the types of the scalars.

A task is a partially SF that may terminate with a result.

Time is used both for time intervals (duration), and time w.r.t. some agreed reference point in time.

DTime is the time type for lengths of sample intervals. Conceptually, DTime = R+ = { x in R | x > 0 }. Don't assume Time and DTime have the same representation.

Information on the progress of time.

Alternative name for localTime.

Transform initial output value.

Applies a transformation f only to the first output value at time zero.

Given an initial value in an accumulator, it returns a signal function that processes an event carrying transformation functions. Every time an Event is received, the function inside it is applied to the accumulator, whose new value is outputted in an Event.

Left-to-right composition

Count the occurrences of input events.

>>> embed count (deltaEncode 1 [Event 'a', NoEvent, Event 'b'])
[Event 1,NoEvent,Event 2]

Right-to-left composition

Duplicate an input.

Spatial parallel composition of a signal function collection parameterized on the routing function.

The identity arrow, which plays the role of return in arrow notation.

Precomposition with a pure function.

Postcomposition with a pure function.

Precomposition with a pure function (right-to-left variant).

Postcomposition with a pure function (right-to-left variant).

Any instance of ArrowApply can be made into an instance of ArrowChoice by defining left = leftApp.

Outputs every input sample, with a given message prefix, using an auxiliary printing function.

Generate outputs using a step-wise generation function and an initial value.

Unbiased event merge: simultaneous occurrence is an error.

Generic lifting of a morphism to the level of MSFs.

Natural transformation to the level of MSFs.

Mathematical background: The type a -> m (b, c) is a functor in c, and MSF m a b is its greatest fixpoint, i.e. it is isomorphic to the type a -> m (b, MSF m a b), by definition. The types m, a and b are parameters of the functor. Taking a fixpoint is functorial itself, meaning that a morphism (a natural transformation) of two such functors gives a morphism (an ordinary function) of their fixpoints.

This is in a sense the most general "abstract" lifting function, i.e. the most general one that only changes input, output and side effect types, and doesn't influence control flow. Other handling functions like exception handling or ListT broadcasting necessarily change control flow.

Well-formed looped connection of an output component as a future input.

Lifts a monadic computation into a Stream.

Apply a monadic transformation to every element of the input stream.

Generalisation of arr from Arrow to monadic functions.

Monadic lifting from one monad into another

Lift innermost monadic actions in monad stack (generalisation of liftIO).

Lift the first MSF into the monad of the second.

Lift the second MSF into the monad of the first.

Lift inner monadic actions in monad stacks.

Apply trans-monadic actions (in an arbitrary way).

This is just a convenience function when you have a function to move across monads, because the signature of morphGS is a bit complex.

Apply an MSF to every input. Freezes temporarily if the input is Nothing, and continues as soon as a Just is received.

Applies a function to produce an additional side effect and passes the input unchanged.

Produces an additional side effect and passes the input unchanged.

Initialized delay operator.

Creates an SF that delays the input signal, introducing an infinitesimal delay (one sample), using the given argument to fill in the initial output at time zero.

Preprends a fixed output to an MSF. The first input is completely ignored.

Buffers and returns the elements in FIFO order, returning Nothing whenever the buffer is empty.

Sums the inputs, starting from zero.

Sums the inputs, starting from an initial vector.

Accumulate the inputs, starting from mempty.

Accumulate the inputs, starting from an initial monoid value.

Applies a function to the input and an accumulator, outputting the updated accumulator. Equal to f s0 -> feedback s0 $ arr (uncurry f >>> dup).

Applies a transfer function to the input and an accumulator, returning the updated accumulator and output.

Event source with repeated occurrences with interval q.

Note: If the interval is too short w.r.t. the sampling intervals, the result will be that events occur at every sample. However, no more than one event results from any sampling interval, thus avoiding an "event backlog" should sampling become more frequent at some later point in time.

Outputs every input sample, with a given message prefix, using an auxiliary printing function, when a condition is met.

Outputs every input sample, with a given message prefix, when a condition is met, and waits for some input / enter to continue.

Initialize a top-level reaction handle.

Process a single input sample.

Suppress all but the first event.

Basic switch.

By default, the first signal function is applied. Whenever the second value in the pair actually is an event, the value carried by the event is used to obtain a new signal function to be applied *at that time and at future times*. Until that happens, the first value in the pair is produced in the output signal.

Important note: at the time of switching, the second signal function is applied immediately. If that second SF can also switch at time zero, then a double (nested) switch might take place. If the second SF refers to the first one, the switch might take place infinitely many times and never be resolved.

Remember: The continuation is evaluated strictly at the time of switching!

Switch with delayed observation.

By default, the first signal function is applied.

Whenever the second value in the pair actually is an event, the value carried by the event is used to obtain a new signal function to be applied *at future times*.

Until that happens, the first value in the pair is produced in the output signal.

Important note: at the time of switching, the second signal function is used immediately, but the current input is fed by it (even though the actual output signal value at time 0 is discarded).

If that second SF can also switch at time zero, then a double (nested) switch might take place. If the second SF refers to the first one, the switch might take place infinitely many times and never be resolved.

Remember: The continuation is evaluated strictly at the time of switching!

Convert an Event into a Maybe value.

Both types are isomorphic, where a value containing an event is mapped to a Just, and NoEvent is mapped to Nothing. There is, however, a semantic difference: a signal carrying a Maybe may change constantly, but, for a signal carrying an Event, there should be a bounded frequency such that sampling the signal faster does not render more event occurrences.

Lift a binary function onto an arrow.

Lift a 3-ary function onto an arrow.

Lift a 4-ary function onto an arrow.

Lift a 5-ary function onto an arrow.

Identity: identity = arr id

Using identity is preferred over lifting id, since the arrow combinators know how to optimise certain networks based on the transformations being applied.

Identity: constant b = arr (const b)

Using constant is preferred over lifting const, since the arrow combinators know how to optimise certain networks based on the transformations being applied.

Initialization operator (cf. Lustre/Lucid Synchrone).

The output at time zero is the first argument, and from that point on it behaves like the signal function passed as second argument.

Output pre-insert operator.

Insert a sample in the output, and from that point on, behave like the given sf.

Input initialization operator.

The input at time zero is the first argument, and from that point on it behaves like the signal function passed as second argument.

Transform initial input value.

Applies a transformation f only to the first input value at time zero.

Override initial value of input signal.

Runs a signal function only when a given predicate is satisfied, otherwise runs the other signal function.

This is similar to ArrowChoice, except that this resets the SFs after each transition.

For example, the following integrates the incoming input numbers, using one integral if the numbers are even, and another if the input numbers are odd. Note how, every time we "switch", the old value of the integral is discarded.

>>> embed (provided (even . round) integral integral) (deltaEncode 1 [1, 1, 1, 2, 2, 2, 1, 1, 1, 2, 2, 2 :: Double])
[0.0,1.0,2.0,0.0,2.0,4.0,0.0,1.0,2.0,0.0,2.0,4.0]

Given a value in an accumulator (b), a predicate signal function (sfC), and a second signal function (sf), pause will produce the accumulator b if sfC input is True, and will transform the signal using sf otherwise. It acts as a pause with an accumulator for the moments when the transformation is paused.

A rising edge detector. Useful for things like detecting key presses. It is initialised as up, meaning that events occurring at time 0 will not be detected.

Event source with a single occurrence at time 0. The value of the event is obtained by sampling the input at that time.

Uninitialized delay operator.

The output has an infinitesimal delay (1 sample), and the value at time zero is undefined.

Lucid-Synchrone-like initialized delay (read "followed by").

Initialized delay combinator, introducing an infinitesimal delay (one sample) in given SF, using the given argument to fill in the initial output at time zero.

The difference with iPre is that fby takes an SF as argument.

Delay a signal by a fixed time t, using the second parameter to fill in the initial t seconds.

Generic version of sscan, in which the auxiliary function produces an internal accumulator and an "held" output.

Applies a function point-wise, using the last known Just output to form the output, and next input accumulator. If the output is Nothing, the last known accumulators are used. This creates a well-formed loop based on a pure, auxiliary function.

Make the NoEvent constructor available. Useful e.g. for initialization, ((-->) & friends), and it's easily available anyway (e.g. mergeEvents []).

Suppress any event in the first component of a pair.

Suppress any event in the second component of a pair.

An event-based version of the maybe function.

Extract the value from an event. Fails if there is no event.

Tests whether the input represents an actual event.

Negation of isEvent.

Tags an (occurring) event with a value ("replacing" the old value).

Applicative-based definition: tag = ($>)

Tags an (occurring) event with a value ("replacing" the old value). Same as tag with the arguments swapped.

Applicative-based definition: tagWith = (<$)

Attaches an extra value to the value of an occurring event.

Left-biased event merge (always prefer left event, if present).

Right-biased event merge (always prefer right event, if present).

Event merge parameterized by a conflict resolution function.

Applicative-based definition: mergeBy f le re = (f $ le * re) | le | re

A generic event merge-map utility that maps event occurrences, merging the results. The first three arguments are mapping functions, the third of which will only be used when both events are present. Therefore, mergeBy = mapMerge id id.

Applicative-based definition: mapMerge lf rf lrf le re = (f $ le * re) | (lf $ le) | (rf $ re)

Merge a list of events; foremost event has priority.

Foldable-based definition: mergeEvents :: Foldable t => t (Event a) -> Event a mergeEvents = asum

Collect simultaneous event occurrences; no event if none.

Join (conjunction) of two events. Only produces an event if both events exist.

Applicative-based definition: joinE = liftA2 (,)

Split event carrying pairs into two events.

Filter out events that don't satisfy some predicate.

Combined event mapping and filtering. Note: since Event is a Functor, see fmap for a simpler version of this function with no filtering.

Enable/disable event occurrences based on an external condition.

Convert a maybe value into a event (Event is isomorphic to Maybe).

Event source that never occurs.

Event source with a single occurrence at time 0. The value of the event is given by the function argument.

Event source with a single occurrence at or as soon after (local) time q as possible.

Event source with consecutive occurrences at the given intervals. Should more than one event be scheduled to occur in any sampling interval, only the first will in fact occur to avoid an event backlog.

Event source with consecutive occurrences at the given intervals. Should more than one event be scheduled to occur in any sampling interval, the output list will contain all events produced during that interval.

Delay for events. (Consider it a triggered after, hence basic.)

Delay an event by a given delta and catenate events that occur so closely so as to be inseparable.

A rising edge detector that can be initialized as up (True, meaning that events occurring at time 0 will not be detected) or down (False, meaning that events occurring at time 0 will be detected).

Like edge, but parameterized on the tag value.

Edge detector particularized for detecting transitions on a Maybe signal from Nothing to Just.

Edge detector parameterized on the edge detection function and initial state, i.e., the previous input sample. The first argument to the edge detection function is the previous sample, the second the current one.

Suppression of initial (at local time 0) event.

Suppress all but the first n events.

Suppress first n events.

Event source with a single occurrence at or as soon after (local) time tEv as possible. The value of the event is obtained by sampling the input a that time.

Sample a signal at regular intervals.

Window sampling.

First argument is the window length wl, second is the sampling interval t. The output list should contain (min (truncate (T/t) wl)) samples, where T is the time the signal function has been running. This requires some care in case of sparse sampling. In case of sparse sampling, the current input value is assumed to have been present at all points where sampling was missed.

Makes an event source recurring by restarting it as soon as it has an occurrence.

Apply the first SF until it produces an event, and, afterwards, switch to the second SF. This is just a convenience function, used to write what sometimes is more understandable switch-based code.

Accumulator parameterized by the accumulation function.

Zero-order hold.

Converts a discrete-time signal into a continuous-time signal, by holding the last value until it changes in the input signal. The given parameter may be used for time zero, and until the first event occurs in the input signal, so hold is always well-initialized.

>>> embed (hold 1) (deltaEncode 0.1 [NoEvent, NoEvent, Event 2, NoEvent, Event 3, NoEvent])
[1,1,2,2,3,3]

Zero-order hold with a delay.

Converts a discrete-time signal into a continuous-time signal, by holding the last value until it changes in the input signal. The given parameter is used for time zero (until the first event occurs in the input signal), so dHold shifts the discrete input by an infinitesimal delay.

>>> embed (dHold 1) (deltaEncode 0.1 [NoEvent, NoEvent, Event 2, NoEvent, Event 3, NoEvent])
[1,1,1,2,2,3]

Tracks input signal when available, holding the last value when the input is Nothing.

This behaves similarly to hold, but there is a conceptual difference, as it takes a signal of input Maybe a (for some a) and not Event.

>>> embed (trackAndHold 1) (deltaEncode 0.1 [Nothing, Nothing, Just 2, Nothing, Just 3, Nothing])
[1,1,2,2,3,3]

Tracks input signal when available, holding the last value when the input is Nothing, with a delay.

This behaves similarly to hold, but there is a conceptual difference, as it takes a signal of input Maybe a (for some a) and not Event.

>>> embed (dTrackAndHold 1) (deltaEncode 0.1 [Nothing, Nothing, Just 2, Nothing, Just 3, Nothing])
[1,1,1,2,2,3]

Zero-order hold accumulator (always produces the last outputted value until an event arrives).

Zero-order hold accumulator with delayed initialization (always produces the last outputted value until an event arrives, but the very initial output is always the given accumulator).

Zero-order hold accumulator parameterized by the accumulation function.

Zero-order hold accumulator parameterized by the accumulation function with delayed initialization (initial output sample is always the given accumulator).

Accumulator parameterized by the accumulator function with filtering, possibly discarding some of the input events based on whether the second component of the result of applying the accumulation function is Nothing or Just x for some x.

Integration using the rectangle rule.

"Immediate" integration (using the function's value at the current time).

Trapezoid integral (using the average between the value at the last time and the value at the current time).

Integrate the first input signal and add the discrete accumulation (sum) of the second, discrete, input signal.

A very crude version of a derivative. It simply divides the value difference by the time difference. Use at your own risk.

Integrate using an auxiliary function that takes the current and the last input, the time between those samples, and the last output, and returns a new output.

Loop with an initial value for the signal being fed back.

Loop by integrating the second value in the pair and feeding the result back. Because the integral at time 0 is zero, this is always well defined.

Noise (random signal) with default range for type in question; based on "randoms".

Noise (random signal) with specified range; based on "randomRs".

Stochastic event source with events occurring on average once every tAvg seconds. However, no more than one event results from any one sampling interval in the case of relatively sparse sampling, thus avoiding an "event backlog" should sampling become more frequent at some later point in time.

Applies a function point-wise, using the last output as next input. This creates a well-formed loop based on a pure, auxiliary function.

Synchronous embedding. The embedded signal function is run on the supplied input and time stream at a given (but variable) ratio >= 0 to the outer time flow. When the ratio is 0, the embedded signal function is paused.

Spaces a list of samples by a fixed time delta, avoiding unnecessary samples when the input has not changed since the last sample.

deltaEncode parameterized by the equality test.