Signal

public final class Signal<Value, Error> where Error : Error

A push-driven stream that sends Events over time, parameterized by the type of values being sent (Value) and the type of failure that can occur (Error). If no failures should be possible, NoError can be specified for Error.

An observer of a Signal will see the exact same sequence of events as all other observers. In other words, events will be sent to all observers at the same time.

Signals are generally used to represent event streams that are already “in progress,” like notifications, user input, etc. To represent streams that must first be started, see the SignalProducer type.

A Signal is kept alive until either of the following happens:

  1. its input observer receives a terminating event; or
  2. it has no active observers, and is not being retained.
  • Initialize a Signal that will immediately invoke the given generator, then forward events sent to the given observer.

    Note

    The disposable returned from the closure will be automatically disposed if a terminating event is sent to the observer. The Signal itself will remain alive until the observer is released.

    Declaration

    Swift

    public init(_ generator: (Observer, Lifetime) -> Void)

    Parameters

    generator

    A closure that accepts an implicitly created observer that will act as an event emitter for the signal.

  • Observe the Signal by sending any future events to the given observer.

    Note

    If the Signal has already terminated, the observer will immediately receive an interrupted event.

    Declaration

    Swift

    @discardableResult
    public func observe(_ observer: Observer) -> Disposable?

    Parameters

    observer

    An observer to forward the events to.

    Return Value

    A Disposable which can be used to disconnect the observer, or nil if the signal has already terminated.

  • Represents a signal event.

    Signals must conform to the grammar: value* (failed | completed | interrupted)?

    See more

    Declaration

    Swift

    public enum Event
  • Logs all events that the receiver sends. By default, it will print to the standard output.

    Declaration

    Swift

    public func logEvents(identifier: String = "", events: Set<LoggingEvent.Signal> = LoggingEvent.Signal.allEvents, fileName: String = #file, functionName: String = #function, lineNumber: Int = #line, logger: @escaping EventLogger = defaultEventLog) -> Signal<Value, Error>

    Parameters

    identifier

    a string to identify the Signal firing events.

    events

    Types of events to log.

    fileName

    Name of the file containing the code which fired the event.

    functionName

    Function where event was fired.

    lineNumber

    Line number where event was fired.

    logger

    Logger that logs the events.

    Return Value

    Signal that, when observed, logs the fired events.

  • Flattens the inner producers sent upon signal (into a single signal of values), according to the semantics of the given strategy.

    Note

    If signal or an active inner producer fails, the returned signal will forward that failure immediately.

    Warning

    interrupted events on inner producers will be treated like completed events on inner producers.

    Declaration

    Swift

    public func flatten(_ strategy: FlattenStrategy) -> Signal<Value.Value, Error>

    Parameters

    strategy

    Strategy used when flattening signals.

  • Flattens the inner producers sent upon signal (into a single signal of values), according to the semantics of the given strategy.

    Note

    If signal or an active inner producer fails, the returned signal will forward that failure immediately.

    Warning

    interrupted events on inner producers will be treated like completed events on inner producers.

    Declaration

    Swift

    public func flatten(_ strategy: FlattenStrategy) -> Signal<Value.Value, Value.Error>

    Parameters

    strategy

    Strategy used when flattening signals.

  • Flattens the inner producers sent upon signal (into a single signal of values), according to the semantics of the given strategy.

    Warning

    interrupted events on inner producers will be treated like completed events on inner producers.

    Declaration

    Swift

    public func flatten(_ strategy: FlattenStrategy) -> Signal<Value.Value, Value.Error>

    Parameters

    strategy

    Strategy used when flattening signals.

  • Flattens the inner producers sent upon signal (into a single signal of values), according to the semantics of the given strategy.

    Note

    If signal fails, the returned signal will forward that failure immediately.

    Warning

    interrupted events on inner producers will be treated like completed events on inner producers.

    Declaration

    Swift

    public func flatten(_ strategy: FlattenStrategy) -> Signal<Value.Value, Error>

    Parameters

    strategy

    Strategy used when flattening signals.

  • Flattens the sequence value sent by signal.

    Declaration

    Swift

    public func flatten() -> Signal<Value.Iterator.Element, Error>
  • Merges the given signals into a single Signal that will emit all values from each of them, and complete when all of them have completed.

    Declaration

    Swift

    public static func merge<Seq>(_ signals: Seq) -> Signal<Value, Error> where Seq : Sequence, Seq.Element == Signal<Value, Error>

    Parameters

    signals

    A sequence of signals to merge.

  • Merges the given signals into a single Signal that will emit all values from each of them, and complete when all of them have completed.

    Declaration

    Swift

    public static func merge(_ signals: Signal<Value, Error>...) -> Signal<Value, Error>

    Parameters

    signals

    A list of signals to merge.

  • Maps each event from signal to a new signal, then flattens the resulting producers (into a signal of values), according to the semantics of the given strategy.

    Warning

    If signal or any of the created producers fail, the returned signal will forward that failure immediately.

    Declaration

    Swift

    public func flatMap<U>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> SignalProducer<U, Error>) -> Signal<U, Error>

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting producers (into a signal of values), according to the semantics of the given strategy.

    Warning

    If signal or any of the created producers fail, the returned signal will forward that failure immediately.

    Declaration

    Swift

    public func flatMap<Inner: SignalProducerConvertible>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> Inner) -> Signal<Inner.Value, Error> where Inner.Error == Error

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting producers (into a signal of values), according to the semantics of the given strategy.

    Warning

    If signal fails, the returned signal will forward that failure immediately.

    Declaration

    Swift

    public func flatMap<U>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> SignalProducer<U, NoError>) -> Signal<U, Error>

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting producers (into a signal of values), according to the semantics of the given strategy.

    Warning

    If signal fails, the returned signal will forward that failure immediately.

    Declaration

    Swift

    public func flatMap<Inner: SignalProducerConvertible>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> Inner) -> Signal<Inner.Value, Error> where Inner.Error == NoError

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting signals (into a signal of values), according to the semantics of the given strategy.

    Warning

    If any of the created signals emit an error, the returned signal will forward that error immediately.

    Declaration

    Swift

    public func flatMap<U, F>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> SignalProducer<U, F>) -> Signal<U, F>

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting signals (into a signal of values), according to the semantics of the given strategy.

    Warning

    If any of the created signals emit an error, the returned signal will forward that error immediately.

    Declaration

    Swift

    public func flatMap<Inner: SignalProducerConvertible>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> Inner) -> Signal<Inner.Value, Inner.Error>

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting signals (into a signal of values), according to the semantics of the given strategy.

    Declaration

    Swift

    public func flatMap<U>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> SignalProducer<U, NoError>) -> Signal<U, NoError>

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Maps each event from signal to a new signal, then flattens the resulting signals (into a signal of values), according to the semantics of the given strategy.

    Declaration

    Swift

    public func flatMap<Inner: SignalProducerConvertible>(_ strategy: FlattenStrategy, _ transform: @escaping (Value) -> Inner) -> Signal<Inner.Value, NoError> where Inner.Error == NoError

    Parameters

    strategy

    Strategy used when flattening signals.

    transform

    A closure that takes a value emitted by self and returns a signal producer with transformed value.

  • Catches any failure that may occur on the input signal, mapping to a new producer that starts in its place.

    Declaration

    Swift

    public func flatMapError<F>(_ transform: @escaping (Error) -> SignalProducer<Value, F>) -> Signal<Value, F>

    Parameters

    transform

    A closure that accepts emitted error and returns a signal producer with a different type of error.

  • Catches any failure that may occur on the input signal, mapping to a new producer that starts in its place.

    Declaration

    Swift

    public func flatMapError<Inner: SignalProducerConvertible>(_ transform: @escaping (Error) -> Inner) -> Signal<Value, Inner.Error> where Inner.Value == Value

    Parameters

    transform

    A closure that accepts emitted error and returns a signal producer with a different type of error.

  • An Observer is a simple wrapper around a function which can receive Events (typically from a Signal).

    See more

    Declaration

    Swift

    public final class Observer
  • A Signal that never sends any events to its observers.

    Declaration

    Swift

    public static var never: Signal { get }
  • A Signal that completes immediately without emitting any value.

    Declaration

    Swift

    public static var empty: Signal { get }
  • Create a Signal that will be controlled by sending events to an input observer.

    Note

    The Signal will remain alive until a terminating event is sent to the input observer, or until it has no observers and there are no strong references to it.

    Declaration

    Swift

    public static func pipe(disposable: Disposable? = nil) -> (output: Signal, input: Observer)

    Parameters

    disposable

    An optional disposable to associate with the signal, and to be disposed of when the signal terminates.

    Return Value

    A 2-tuple of the output end of the pipe as Signal, and the input end of the pipe as Signal.Observer.

  • Declaration

    Swift

    public var signal: Signal<Value, Error> { get }
  • Observe self for all events being emitted.

    Note

    If self has terminated, the closure would be invoked with an interrupted event immediately.

    Declaration

    Swift

    @discardableResult
    public func observe(_ action: @escaping Signal<Value, Error>.Observer.Action) -> Disposable?

    Parameters

    action

    A closure to be invoked with every event from self.

    Return Value

    A disposable to detach action from self. nil if self has terminated.

  • Observe self for all values being emitted, and if any, the failure.

    Declaration

    Swift

    @discardableResult
    public func observeResult(_ action: @escaping (Result<Value, Error>) -> Void) -> Disposable?

    Parameters

    action

    A closure to be invoked with values from self, or the propagated error should any failed event is emitted.

    Return Value

    A disposable to detach action from self. nil if self has terminated.

  • Observe self for its completion.

    Declaration

    Swift

    @discardableResult
    public func observeCompleted(_ action: @escaping () -> Void) -> Disposable?

    Parameters

    action

    A closure to be invoked when a completed event is emitted.

    Return Value

    A disposable to detach action from self. nil if self has terminated.

  • Observe self for its failure.

    Declaration

    Swift

    @discardableResult
    public func observeFailed(_ action: @escaping (Error) -> Void) -> Disposable?

    Parameters

    action

    A closure to be invoked with the propagated error, should any failed event is emitted.

    Return Value

    A disposable to detach action from self. nil if self has terminated.

  • Observe self for its interruption.

    Note

    If self has terminated, the closure would be invoked immediately.

    Declaration

    Swift

    @discardableResult
    public func observeInterrupted(_ action: @escaping () -> Void) -> Disposable?

    Parameters

    action

    A closure to be invoked when an interrupted event is emitted.

    Return Value

    A disposable to detach action from self. nil if self has terminated.

  • Observe self for all values being emitted.

    Declaration

    Swift

    @discardableResult
    public func observeValues(_ action: @escaping (Value) -> Void) -> Disposable?

    Parameters

    action

    A closure to be invoked with values from self.

    Return Value

    A disposable to detach action from self. nil if self has terminated.

  • Map each value in the signal to a new value.

    Declaration

    Swift

    public func map<U>(_ transform: @escaping (Value) -> U) -> Signal<U, Error>

    Parameters

    transform

    A closure that accepts a value from the value event and returns a new value.

    Return Value

    A signal that will send new values.

  • Map each value in the signal to a new constant value.

    Declaration

    Swift

    public func map<U>(value: U) -> Signal<U, Error>

    Parameters

    value

    A new value.

    Return Value

    A signal that will send new values.

  • Map each value in the signal to a new value by applying a key path.

    Declaration

    Swift

    public func map<U>(_ keyPath: KeyPath<Value, U>) -> Signal<U, Error>

    Parameters

    keyPath

    A key path relative to the signal’s Value type.

    Return Value

    A signal that will send new values.

  • Map errors in the signal to a new error.

    Declaration

    Swift

    public func mapError<F>(_ transform: @escaping (Error) -> F) -> Signal<Value, F>

    Parameters

    transform

    A closure that accepts current error object and returns a new type of error object.

    Return Value

    A signal that will send new type of errors.

  • Maps each value in the signal to a new value, lazily evaluating the supplied transformation on the specified scheduler.

    Important

    Unlike map, there is not a 1-1 mapping between incoming values, and values sent on the returned signal. If scheduler has not yet scheduled transform for execution, then each new value will replace the last one as the parameter to transform once it is finally executed.

    Declaration

    Swift

    public func lazyMap<U>(on scheduler: Scheduler, transform: @escaping (Value) -> U) -> Signal<U, Error>

    Parameters

    transform

    The closure used to obtain the returned value from this signal’s underlying value.

    Return Value

    A signal that sends values obtained using transform as this signal sends values.

  • Preserve only values which pass the given closure.

    Declaration

    Swift

    public func filter(_ isIncluded: @escaping (Value) -> Bool) -> Signal<Value, Error>

    Parameters

    isIncluded

    A closure to determine whether a value from self should be included in the returned Signal.

    Return Value

    A signal that forwards the values passing the given closure.

  • Applies transform to values from signal and forwards values with non nil results unwrapped.

    Declaration

    Swift

    public func filterMap<U>(_ transform: @escaping (Value) -> U?) -> Signal<U, Error>

    Parameters

    transform

    A closure that accepts a value from the value event and returns a new optional value.

    Return Value

    A signal that will send new values, that are non nil after the transformation.

  • Unwrap non-nil values and forward them on the returned signal, nil values are dropped.

    Declaration

    Swift

    public func skipNil() -> Signal<Value.Wrapped, Error>

    Return Value

    A signal that sends only non-nil values.

  • Take up to n values from the signal and then complete.

    Precondition

    count must be non-negative number.

    Declaration

    Swift

    public func take(first count: Int) -> Signal<Value, Error>

    Parameters

    count

    A number of values to take from the signal.

    Return Value

    A signal that will yield the first count values from self

  • Collect all values sent by the signal then forward them as a single array and complete.

    Note

    When self completes without collecting any value, it will send an empty array of values.

    Declaration

    Swift

    public func collect() -> Signal<[Value], Error>

    Return Value

    A signal that will yield an array of values when self completes.

  • Collect at most count values from self, forward them as a single array and complete.

    Note

    When the count is reached the array is sent and the signal starts over yielding a new array of values.

    Note

    When self completes any remaining values will be sent, the last array may not have count values. Alternatively, if were not collected any values will sent an empty array of values.

    Precondition

    count should be greater than zero.

    Declaration

    Swift

    public func collect(count: Int) -> Signal<[Value], Error>
  • Collect values from self, and emit them if the predicate passes.

    When self completes any remaining values will be sent, regardless of the collected values matching shouldEmit or not.

    If self completes without having emitted any value, an empty array would be emitted, followed by the completion of the returned Signal.

    let (signal, observer) = Signal<Int, NoError>.pipe()
    
    signal
        .collect { values in values.reduce(0, combine: +) == 8 }
        .observeValues { print($0) }
    
    observer.send(value: 1)
    observer.send(value: 3)
    observer.send(value: 4)
    observer.send(value: 7)
    observer.send(value: 1)
    observer.send(value: 5)
    observer.send(value: 6)
    observer.sendCompleted()
    
    // Output:
    // [1, 3, 4]
    // [7, 1]
    // [5, 6]
    

    Declaration

    Swift

    public func collect(_ shouldEmit: @escaping (_ collectedValues: [Value]) -> Bool) -> Signal<[Value], Error>

    Parameters

    shouldEmit

    A closure to determine, when every time a new value is received, whether the collected values should be emitted. The new value is included in the collected values.

    Return Value

    A signal of arrays of values, as instructed by the shouldEmit closure.

  • Collect values from self, and emit them if the predicate passes.

    When self completes any remaining values will be sent, regardless of the collected values matching shouldEmit or not.

    If self completes without having emitted any value, an empty array would be emitted, followed by the completion of the returned Signal.

    let (signal, observer) = Signal<Int, NoError>.pipe()
    
    signal
        .collect { values, value in value == 7 }
        .observeValues { print($0) }
    
    observer.send(value: 1)
    observer.send(value: 1)
    observer.send(value: 7)
    observer.send(value: 7)
    observer.send(value: 5)
    observer.send(value: 6)
    observer.sendCompleted()
    
    // Output:
    // [1, 1]
    // [7]
    // [7, 5, 6]
    

    Declaration

    Swift

    public func collect(_ shouldEmit: @escaping (_ collected: [Value], _ latest: Value) -> Bool) -> Signal<[Value], Error>

    Parameters

    shouldEmit

    A closure to determine, when every time a new value is received, whether the collected values should be emitted. The new value is not included in the collected values, and is included when the next value is received.

    Return Value

    A signal of arrays of values, as instructed by the shouldEmit closure.

  • Forward the latest values on scheduler every interval.

    Note

    If self terminates while values are being accumulated, the behaviour will be determined by discardWhenCompleted. If true, the values will be discarded and the returned signal will terminate immediately. If false, that values will be delivered at the next interval.

    Declaration

    Swift

    public func collect(every interval: DispatchTimeInterval, on scheduler: DateScheduler, skipEmpty: Bool = false, discardWhenCompleted: Bool = true) -> Signal<[Value], Error>

    Parameters

    interval

    A repetition interval.

    scheduler

    A scheduler to send values on.

    skipEmpty

    Whether empty arrays should be sent if no values were accumulated during the interval.

    discardWhenCompleted

    A boolean to indicate if the latest unsent values should be discarded on completion.

    Return Value

    A signal that sends all values that are sent from self at interval seconds apart.

  • Forward all events onto the given scheduler, instead of whichever scheduler they originally arrived upon.

    Declaration

    Swift

    public func observe(on scheduler: Scheduler) -> Signal<Value, Error>

    Parameters

    scheduler

    A scheduler to deliver events on.

    Return Value

    A signal that will yield self values on provided scheduler.

  • Combine the latest value of the receiver with the latest value from the given signal.

    Note

    The returned signal will not send a value until both inputs have sent at least one value each.

    Note

    If either signal is interrupted, the returned signal will also be interrupted.

    Note

    The returned signal will not complete until both inputs complete.

    Declaration

    Swift

    public func combineLatest<U>(with other: Signal<U, Error>) -> Signal<(Value, U), Error>

    Parameters

    otherSignal

    A signal to combine self‘s value with.

    Return Value

    A signal that will yield a tuple containing values of self and given signal.

  • Merge the given signal into a single Signal that will emit all values from both of them, and complete when all of them have completed.

    Declaration

    Swift

    public func merge(with other: Signal<Value, Error>) -> Signal<Value, Error>

    Parameters

    other

    A signal to merge self‘s value with.

    Return Value

    A signal that sends all values of self and given signal.

  • Delay value and completed events by the given interval, forwarding them on the given scheduler.

    Note

    failed and interrupted events are always scheduled immediately.

    Precondition

    interval must be non-negative number.

    Declaration

    Swift

    public func delay(_ interval: TimeInterval, on scheduler: DateScheduler) -> Signal<Value, Error>

    Parameters

    interval

    Interval to delay value and completed events by.

    scheduler

    A scheduler to deliver delayed events on.

    Return Value

    A signal that will delay value and completed events and will yield them on given scheduler.

  • Skip first count number of values then act as usual.

    Precondition

    count must be non-negative number.

    Declaration

    Swift

    public func skip(first count: Int) -> Signal<Value, Error>

    Parameters

    count

    A number of values to skip.

    Return Value

    A signal that will skip the first count values, then forward everything afterward.

  • Treat all Events from self as plain values, allowing them to be manipulated just like any other value.

    In other words, this brings Events “into the monad”.

    Note

    When a Completed or Failed event is received, the resulting signal will send the Event itself and then complete. When an Interrupted event is received, the resulting signal will send the Event itself and then interrupt.

    Declaration

    Swift

    public func materialize() -> Signal<Event, NoError>

    Return Value

    A signal that sends events as its values.

  • Translate a signal of Event values into a signal of those events themselves.

    Declaration

    Swift

    public func dematerialize() -> Signal<Value.Value, Value.Error>

    Return Value

    A signal that sends values carried by self events.

  • Inject side effects to be performed upon the specified signal events.

    Declaration

    Swift

    public func on(
    	event: ((Event) -> Void)? = nil,
    	failed: ((Error) -> Void)? = nil,
    	completed: (() -> Void)? = nil,
    	interrupted: (() -> Void)? = nil,
    	terminated: (() -> Void)? = nil,
    	disposed: (() -> Void)? = nil,
    	value: ((Value) -> Void)? = nil
    ) -> Signal<Value, Error>

    Parameters

    event

    A closure that accepts an event and is invoked on every received event.

    failed

    A closure that accepts error object and is invoked for failed event.

    completed

    A closure that is invoked for completed event.

    interrupted

    A closure that is invoked for interrupted event.

    terminated

    A closure that is invoked for any terminating event.

    disposed

    A closure added as disposable when signal completes.

    value

    A closure that accepts a value from value event.

    Return Value

    A signal with attached side-effects for given event cases.

  • Forward the latest value from self with the value from sampler as a tuple, only whensampler sends a value event.

    Note

    If sampler fires before a value has been observed on self, nothing happens.

    Declaration

    Swift

    public func sample<T>(with sampler: Signal<T, NoError>) -> Signal<(Value, T), Error>

    Parameters

    sampler

    A signal that will trigger the delivery of value event from self.

    Return Value

    A signal that will send values from self and sampler, sampled (possibly multiple times) by sampler, then complete once both input signals have completed, or interrupt if either input signal is interrupted.

  • Forward the latest value from self whenever sampler sends a value event.

    Note

    If sampler fires before a value has been observed on self, nothing happens.

    Declaration

    Swift

    public func sample(on sampler: Signal<(), NoError>) -> Signal<Value, Error>

    Parameters

    sampler

    A signal that will trigger the delivery of value event from self.

    Return Value

    A signal that will send values from self, sampled (possibly multiple times) by sampler, then complete once both input signals have completed, or interrupt if either input signal is interrupted.

  • Forward the latest value from samplee with the value from self as a tuple, only when self sends a value event. This is like a flipped version of sample(with:), but samplee‘s terminal events are completely ignored.

    Note

    If self fires before a value has been observed on samplee, nothing happens.

    Declaration

    Swift

    public func withLatest<U>(from samplee: Signal<U, NoError>) -> Signal<(Value, U), Error>

    Parameters

    samplee

    A signal whose latest value is sampled by self.

    Return Value

    A signal that will send values from self and samplee, sampled (possibly multiple times) by self, then terminate once self has terminated. samplee‘s terminated events are ignored.

  • Forward the latest value from samplee with the value from self as a tuple, only when self sends a value event. This is like a flipped version of sample(with:), but samplee‘s terminal events are completely ignored.

    Note

    If self fires before a value has been observed on samplee, nothing happens.

    Declaration

    Swift

    public func withLatest<U>(from samplee: SignalProducer<U, NoError>) -> Signal<(Value, U), Error>

    Parameters

    samplee

    A producer whose latest value is sampled by self.

    Return Value

    A signal that will send values from self and samplee, sampled (possibly multiple times) by self, then terminate once self has terminated. samplee‘s terminated events are ignored.

  • Forward the latest value from samplee with the value from self as a tuple, only when self sends a value event. This is like a flipped version of sample(with:), but samplee‘s terminal events are completely ignored.

    Note

    If self fires before a value has been observed on samplee, nothing happens.

    Declaration

    Swift

    public func withLatest<Samplee>(from samplee: Samplee) -> Signal<(Value, Samplee.Value), Error> where Samplee : SignalProducerConvertible, Samplee.Error == NoError

    Parameters

    samplee

    A producer whose latest value is sampled by self.

    Return Value

    A signal that will send values from self and samplee, sampled (possibly multiple times) by self, then terminate once self has terminated. samplee‘s terminated events are ignored.

  • Forwards events from self until lifetime ends, at which point the returned signal will complete.

    Declaration

    Swift

    public func take(during lifetime: Lifetime) -> Signal<Value, Error>

    Parameters

    lifetime

    A lifetime whose ended signal will cause the returned signal to complete.

    Return Value

    A signal that will deliver events until lifetime ends.

  • Forward events from self until trigger sends a value or completed event, at which point the returned signal will complete.

    Declaration

    Swift

    public func take(until trigger: Signal<(), NoError>) -> Signal<Value, Error>

    Parameters

    trigger

    A signal whose value or completed events will stop the delivery of value events from self.

    Return Value

    A signal that will deliver events until trigger sends value or completed events.

  • Do not forward any values from self until trigger sends a value or completed event, at which point the returned signal behaves exactly like signal.

    Declaration

    Swift

    public func skip(until trigger: Signal<(), NoError>) -> Signal<Value, Error>

    Parameters

    trigger

    A signal whose value or completed events will start the deliver of events on self.

    Return Value

    A signal that will deliver events once the trigger sends value or completed events.

  • Forward events from self with history: values of the returned signal are a tuples whose first member is the previous value and whose second member is the current value. initial is supplied as the first member when self sends its first value.

    Declaration

    Swift

    public func combinePrevious(_ initial: Value) -> Signal<(Value, Value), Error>

    Parameters

    initial

    A value that will be combined with the first value sent by self.

    Return Value

    A signal that sends tuples that contain previous and current sent values of self.

  • Forward events from self with history: values of the returned signal are a tuples whose first member is the previous value and whose second member is the current value.

    The returned Signal would not emit any tuple until it has received at least two values.

    Declaration

    Swift

    public func combinePrevious() -> Signal<(Value, Value), Error>

    Return Value

    A signal that sends tuples that contain previous and current sent values of self.

  • Combine all values from self, and forward only the final accumulated result.

    See scan(_:_:) if the resulting producer needs to forward also the partial results.

    Declaration

    Swift

    public func reduce<U>(_ initialResult: U, _ nextPartialResult: @escaping (U, Value) -> U) -> Signal<U, Error>

    Parameters

    initialResult

    The value to use as the initial accumulating value.

    nextPartialResult

    A closure that combines the accumulating value and the latest value from self. The result would be used in the next call of nextPartialResult, or emit to the returned Signal when self completes.

    Return Value

    A signal that sends the final result as self completes.

  • Combine all values from self, and forward only the final accumulated result.

    See scan(into:_:) if the resulting producer needs to forward also the partial results.

    Declaration

    Swift

    public func reduce<U>(into initialResult: U, _ nextPartialResult: @escaping (inout U, Value) -> Void) -> Signal<U, Error>

    Parameters

    initialResult

    The value to use as the initial accumulating value.

    nextPartialResult

    A closure that combines the accumulating value and the latest value from self. The result would be used in the next call of nextPartialResult, or emit to the returned Signal when self completes.

    Return Value

    A signal that sends the final result as self completes.

  • Combine all values from self, and forward the partial results and the final result.

    See reduce(_:_:) if the resulting producer needs to forward only the final result.

    Declaration

    Swift

    public func scan<U>(_ initialResult: U, _ nextPartialResult: @escaping (U, Value) -> U) -> Signal<U, Error>

    Parameters

    initialResult

    The value to use as the initial accumulating value.

    nextPartialResult

    A closure that combines the accumulating value and the latest value from self. The result would be forwarded, and would be used in the next call of nextPartialResult.

    Return Value

    A signal that sends the partial results of the accumuation, and the final result as self completes.

  • Combine all values from self, and forward the partial results and the final result.

    See reduce(into:_:) if the resulting producer needs to forward only the final result.

    Declaration

    Swift

    public func scan<U>(into initialResult: U, _ nextPartialResult: @escaping (inout U, Value) -> Void) -> Signal<U, Error>

    Parameters

    initialResult

    The value to use as the initial accumulating value.

    nextPartialResult

    A closure that combines the accumulating value and the latest value from self. The result would be forwarded, and would be used in the next call of nextPartialResult.

    Return Value

    A signal that sends the partial results of the accumuation, and the final result as self completes.

  • Forward only values from self that are not equal to its immediately preceding value.

    Note

    The first value is always forwarded.

    Declaration

    Swift

    public func skipRepeats() -> Signal<Value, Error>

    Return Value

    A signal which conditionally forwards values from self.

  • Forward only values from self that are not considered equivalent to its immediately preceding value.

    Note

    The first value is always forwarded.

    Declaration

    Swift

    public func skipRepeats(_ isEquivalent: @escaping (Value, Value) -> Bool) -> Signal<Value, Error>

    Parameters

    isEquivalent

    A closure to determine whether two values are equivalent.

    Return Value

    A signal which conditionally forwards values from self.

  • Do not forward any value from self until shouldContinue returns false, at which point the returned signal starts to forward values from self, including the one leading to the toggling.

    Declaration

    Swift

    public func skip(while shouldContinue: @escaping (Value) -> Bool) -> Signal<Value, Error>

    Parameters

    shouldContinue

    A closure to determine whether the skipping should continue.

    Return Value

    A signal which conditionally forwards values from self.

  • Forward events from self until replacement begins sending events.

    Declaration

    Swift

    public func take(untilReplacement signal: Signal<Value, Error>) -> Signal<Value, Error>

    Parameters

    replacement

    A signal to wait to wait for values from and start sending them as a replacement to self‘s values.

    Return Value

    A signal which passes through value, failed, and interrupted events from self until replacement sends an event, at which point the returned signal will send that event and switch to passing through events from replacement instead, regardless of whether self has sent events already.

  • Wait until self completes and then forward the final count values on the returned signal.

    Declaration

    Swift

    public func take(last count: Int) -> Signal<Value, Error>

    Parameters

    count

    Number of last events to send after self completes.

    Return Value

    A signal that receives up to count values from self after self completes.

  • Forward any values from self until shouldContinue returns false, at which point the returned signal would complete.

    Declaration

    Swift

    public func take(while shouldContinue: @escaping (Value) -> Bool) -> Signal<Value, Error>

    Parameters

    shouldContinue

    A closure to determine whether the forwarding of values should continue.

    Return Value

    A signal which conditionally forwards values from self.

  • Zip elements of two signals into pairs. The elements of any Nth pair are the Nth elements of the two input signals.

    Declaration

    Swift

    public func zip<U>(with other: Signal<U, Error>) -> Signal<(Value, U), Error>

    Parameters

    otherSignal

    A signal to zip values with.

    Return Value

    A signal that sends tuples of self and otherSignal.

  • Forward the latest value on scheduler after at least interval seconds have passed since the returned signal last sent a value.

    If self always sends values more frequently than interval seconds, then the returned signal will send a value every interval seconds.

    To measure from when self last sent a value, see debounce.

    Seealso

    debounce

    Note

    If multiple values are received before the interval has elapsed, the latest value is the one that will be passed on.

    Note

    If self terminates while a value is being throttled, that value will be discarded and the returned signal will terminate immediately.

    Note

    If the device time changed backwards before previous date while a value is being throttled, and if there is a new value sent, the new value will be passed anyway.

    Precondition

    interval must be non-negative number.

    Declaration

    Swift

    public func throttle(_ interval: TimeInterval, on scheduler: DateScheduler) -> Signal<Value, Error>

    Parameters

    interval

    Number of seconds to wait between sent values.

    scheduler

    A scheduler to deliver events on.

    Return Value

    A signal that sends values at least interval seconds appart on a given scheduler.

  • Conditionally throttles values sent on the receiver whenever shouldThrottle is true, forwarding values on the given scheduler.

    Note

    While shouldThrottle remains false, values are forwarded on the given scheduler. If multiple values are received while shouldThrottle is true, the latest value is the one that will be passed on.

    Note

    If the input signal terminates while a value is being throttled, that value will be discarded and the returned signal will terminate immediately.

    Note

    If shouldThrottle completes before the receiver, and its last value is true, the returned signal will remain in the throttled state, emitting no further values until it terminates.

    Declaration

    Swift

    public func throttle<P: PropertyProtocol>(while shouldThrottle: P, on scheduler: Scheduler) -> Signal<Value, Error>
    	where P.Value == Bool

    Parameters

    shouldThrottle

    A boolean property that controls whether values should be throttled.

    scheduler

    A scheduler to deliver events on.

    Return Value

    A signal that sends values only while shouldThrottle is false.

  • Forward the latest value on scheduler after at least interval seconds have passed since self last sent a value.

    If self always sends values more frequently than interval seconds, then the returned signal will never send any values.

    To measure from when the returned signal last sent a value, see throttle.

    Seealso

    throttle

    Note

    If multiple values are received before the interval has elapsed, the latest value is the one that will be passed on.

    Note

    If self terminates while a value is being debounced, the behaviour will be determined by discardWhenCompleted. If true, that value will be discarded and the returned producer will terminate immediately. If false, that value will be delivered at the next debounce interval.

    Precondition

    interval must be non-negative number.

    Declaration

    Swift

    public func debounce(_ interval: TimeInterval, on scheduler: DateScheduler, discardWhenCompleted: Bool = true) -> Signal<Value, Error>

    Parameters

    interval

    A number of seconds to wait before sending a value.

    scheduler

    A scheduler to send values on.

    discardWhenCompleted

    A boolean to indicate if the latest value should be discarded on completion.

    Return Value

    A signal that sends values that are sent from self at least interval seconds apart.

  • Forward only those values from self that have unique identities across the set of all values that have been seen.

    Note

    This causes the identities to be retained to check for uniqueness.

    Declaration

    Swift

    public func uniqueValues<Identity: Hashable>(_ transform: @escaping (Value) -> Identity) -> Signal<Value, Error>

    Parameters

    transform

    A closure that accepts a value and returns identity value.

    Return Value

    A signal that sends unique values during its lifetime.

  • Forward only those values from self that are unique across the set of all values that have been seen.

    Note

    This causes the values to be retained to check for uniqueness. Providing a function that returns a unique value for each sent value can help you reduce the memory footprint.

    Declaration

    Swift

    public func uniqueValues() -> Signal<Value, Error>

    Return Value

    A signal that sends unique values during its lifetime.

  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>) -> Signal<(Value, B), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>) -> Signal<(Value, B, C), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>) -> Signal<(Value, B, C, D), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D, E>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>) -> Signal<(Value, B, C, D, E), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D, E, F>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>) -> Signal<(Value, B, C, D, E, F), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D, E, F, G>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>) -> Signal<(Value, B, C, D, E, F, G), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D, E, F, G, H>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>, _ h: Signal<H, Error>) -> Signal<(Value, B, C, D, E, F, G, H), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D, E, F, G, H, I>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>, _ h: Signal<H, Error>, _ i: Signal<I, Error>) -> Signal<(Value, B, C, D, E, F, G, H, I), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:).

    Declaration

    Swift

    public static func combineLatest<B, C, D, E, F, G, H, I, J>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>, _ h: Signal<H, Error>, _ i: Signal<I, Error>, _ j: Signal<J, Error>) -> Signal<(Value, B, C, D, E, F, G, H, I, J), Error>
  • Combines the values of all the given signals, in the manner described by combineLatest(with:). No events will be sent if the sequence is empty.

    Declaration

    Swift

    public static func combineLatest<S>(_ signals: S) -> Signal<[Value], Error> where S : Sequence, S.Element == Signal<Value, Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>) -> Signal<(Value, B), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>) -> Signal<(Value, B, C), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>) -> Signal<(Value, B, C, D), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D, E>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>) -> Signal<(Value, B, C, D, E), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D, E, F>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>) -> Signal<(Value, B, C, D, E, F), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D, E, F, G>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>) -> Signal<(Value, B, C, D, E, F, G), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D, E, F, G, H>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>, _ h: Signal<H, Error>) -> Signal<(Value, B, C, D, E, F, G, H), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D, E, F, G, H, I>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>, _ h: Signal<H, Error>, _ i: Signal<I, Error>) -> Signal<(Value, B, C, D, E, F, G, H, I), Error>
  • Zip the values of all the given signals, in the manner described by zip(with:).

    Declaration

    Swift

    public static func zip<B, C, D, E, F, G, H, I, J>(_ a: Signal<Value, Error>, _ b: Signal<B, Error>, _ c: Signal<C, Error>, _ d: Signal<D, Error>, _ e: Signal<E, Error>, _ f: Signal<F, Error>, _ g: Signal<G, Error>, _ h: Signal<H, Error>, _ i: Signal<I, Error>, _ j: Signal<J, Error>) -> Signal<(Value, B, C, D, E, F, G, H, I, J), Error>
  • Zips the values of all the given signals, in the manner described by zip(with:). No events will be sent if the sequence is empty.

    Declaration

    Swift

    public static func zip<S>(_ signals: S) -> Signal<[Value], Error> where S : Sequence, S.Element == Signal<Value, Error>
  • Forward events from self until interval. Then if signal isn’t completed yet, fails with error on scheduler.

    Note

    If the interval is 0, the timeout will be scheduled immediately. The signal must complete synchronously (or on a faster scheduler) to avoid the timeout.

    Precondition

    interval must be non-negative number.

    Declaration

    Swift

    public func timeout(after interval: TimeInterval, raising error: Error, on scheduler: DateScheduler) -> Signal<Value, Error>

    Parameters

    error

    Error to send with failed event if self is not completed when interval passes.

    interval

    Number of seconds to wait for self to complete.

    scheudler

    A scheduler to deliver error on.

    Return Value

    A signal that sends events for at most interval seconds, then, if not completed - sends error with failed event on scheduler.

  • Promote a signal that does not generate failures into one that can.

    Note

    This does not actually cause failures to be generated for the given signal, but makes it easier to combine with other signals that may fail; for example, with operators like combineLatestWith, zipWith, flatten, etc.

    Declaration

    Swift

    public func promoteError<F>(_: F.Type = F.self) -> Signal<Value, F>

    Return Value

    A signal that has an instantiatable ErrorType.

  • Promote a signal that does not generate failures into one that can.

    Note

    This does not actually cause failures to be generated for the given signal, but makes it easier to combine with other signals that may fail; for example, with operators like combineLatestWith, zipWith, flatten, etc.

    Declaration

    Swift

    public func promoteError(_: Error.Type = Error.self) -> Signal<Value, Error>

    Return Value

    A signal that has an instantiatable ErrorType.

  • Forward events from self until interval. Then if signal isn’t completed yet, fails with error on scheduler.

    Note

    If the interval is 0, the timeout will be scheduled immediately. The signal must complete synchronously (or on a faster scheduler) to avoid the timeout.

    Declaration

    Swift

    public func timeout<NewError>(
    	after interval: TimeInterval,
    	raising error: NewError,
    	on scheduler: DateScheduler
    ) -> Signal<Value, NewError>

    Parameters

    interval

    Number of seconds to wait for self to complete.

    error

    Error to send with failed event if self is not completed when interval passes.

    scheudler

    A scheduler to deliver error on.

    Return Value

    A signal that sends events for at most interval seconds, then, if not completed - sends error with failed event on scheduler.

  • Promote a signal that does not generate values, as indicated by Never, to be a signal of the given type of value.

    Note

    The promotion does not result in any value being generated.

    Declaration

    Swift

    public func promoteValue<U>(_: U.Type = U.self) -> Signal<U, Error>

    Return Value

    A signal that forwards all terminal events from self.

  • Promote a signal that does not generate values, as indicated by Never, to be a signal of the given type of value.

    Note

    The promotion does not result in any value being generated.

    Declaration

    Swift

    public func promoteValue(_: Value.Type = Value.self) -> Signal<Value, Error>

    Return Value

    A signal that forwards all terminal events from self.

  • Create a signal that computes a logical NOT in the latest values of self.

    Declaration

    Swift

    public func negate() -> Signal<Value, Error>

    Return Value

    A signal that emits the logical NOT results.

  • Create a signal that computes a logical AND between the latest values of self and signal.

    Declaration

    Swift

    public func and(_ signal: Signal<Value, Error>) -> Signal<Value, Error>

    Parameters

    signal

    Signal to be combined with self.

    Return Value

    A signal that emits the logical AND results.

  • Create a signal that computes a logical OR between the latest values of self and signal.

    Declaration

    Swift

    public func or(_ signal: Signal<Value, Error>) -> Signal<Value, Error>

    Parameters

    signal

    Signal to be combined with self.

    Return Value

    A signal that emits the logical OR results.

  • Apply an action to every value from self, and forward the value if the action succeeds. If the action fails with an error, the returned Signal would propagate the failure and terminate.

    Declaration

    Swift

    public func attempt(_ action: @escaping (Value) -> Result<(), Error>) -> Signal<Value, Error>

    Parameters

    action

    An action which yields a Result.

    Return Value

    A signal which forwards the values from self until the given action fails.

  • Apply a transform to every value from self, and forward the transformed value if the action succeeds. If the action fails with an error, the returned Signal would propagate the failure and terminate.

    Declaration

    Swift

    public func attemptMap<U>(_ transform: @escaping (Value) -> Result<U, Error>) -> Signal<U, Error>

    Parameters

    action

    A transform which yields a Result of the transformed value or the error.

    Return Value

    A signal which forwards the transformed values.

  • Apply a throwable action to every value from self, and forward the values if the action succeeds. If the action throws an error, the returned Signal would propagate the failure and terminate.

    Declaration

    Swift

    public func attempt(_ action: @escaping (Value) throws -> Void) -> Signal<Value, AnyError>

    Parameters

    action

    A throwable closure to perform an arbitrary action on the value.

    Return Value

    A signal which forwards the successful values of the given action.

  • Apply a throwable transform to every value from self, and forward the results if the action succeeds. If the transform throws an error, the returned Signal would propagate the failure and terminate.

    Declaration

    Swift

    public func attemptMap<U>(_ transform: @escaping (Value) throws -> U) -> Signal<U, AnyError>

    Parameters

    transform

    A throwable transform.

    Return Value

    A signal which forwards the successfully transformed values.

  • Apply a throwable action to every value from self, and forward the values if the action succeeds. If the action throws an error, the returned Signal would propagate the failure and terminate.

    Declaration

    Swift

    public func attempt(_ action: @escaping (Value) throws -> Void) -> Signal<Value, AnyError>

    Parameters

    action

    A throwable closure to perform an arbitrary action on the value.

    Return Value

    A signal which forwards the successful values of the given action.

  • Apply a throwable transform to every value from self, and forward the results if the action succeeds. If the transform throws an error, the returned Signal would propagate the failure and terminate.

    Declaration

    Swift

    public func attemptMap<U>(_ transform: @escaping (Value) throws -> U) -> Signal<U, AnyError>

    Parameters

    transform

    A throwable transform.

    Return Value

    A signal which forwards the successfully transformed values.