-
Notifications
You must be signed in to change notification settings - Fork 1
/
combine-generated-interface.swift
9479 lines (8071 loc) · 513 KB
/
combine-generated-interface.swift
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
import Darwin
import _Concurrency
import _StringProcessing
/// A type-erasing cancellable object that executes a provided closure when canceled.
///
/// Subscriber implementations can use this type to provide a “cancellation token” that makes it possible for a caller to cancel a publisher, but not to use the ``Subscription`` object to request items.
///
/// An ``AnyCancellable`` instance automatically calls ``Cancellable/cancel()`` when deinitialized.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
final public class AnyCancellable : Cancellable, Hashable {
/// Initializes the cancellable object with the given cancel-time closure.
///
/// - Parameter cancel: A closure that the `cancel()` method executes.
public init(_ cancel: @escaping () -> Void)
public init<C>(_ canceller: C) where C : Cancellable
/// Cancel the activity.
///
/// When implementing ``Cancellable`` in support of a custom publisher, implement `cancel()` to request that your publisher stop calling its downstream subscribers. Combine doesn't require that the publisher stop immediately, but the `cancel()` call should take effect quickly. Canceling should also eliminate any strong references it currently holds.
///
/// After you receive one call to `cancel()`, subsequent calls shouldn't do anything. Additionally, your implementation must be thread-safe, and it shouldn't block the caller.
///
/// > Tip: Keep in mind that your `cancel()` may execute concurrently with another call to `cancel()` --- including the scenario where an ``AnyCancellable`` is deallocating --- or to ``Subscription/request(_:)``.
final public func cancel()
/// Hashes the essential components of this value by feeding them into the
/// given hasher.
///
/// Implement this method to conform to the `Hashable` protocol. The
/// components used for hashing must be the same as the components compared
/// in your type's `==` operator implementation. Call `hasher.combine(_:)`
/// with each of these components.
///
/// - Important: Never call `finalize()` on `hasher`. Doing so may become a
/// compile-time error in the future.
///
/// - Parameter hasher: The hasher to use when combining the components
/// of this instance.
final public func hash(into hasher: inout Hasher)
/// Returns a Boolean value that indicates whether two instances are equal, as determined by comparing whether their references point to the same instance.
/// - Parameters:
/// - lhs: An `AnyCancellable` instance to compare.
/// - rhs: Another `AnyCancellable` instance to compare.
/// - Returns: A Boolean value that indicates whether two instances are equal, as determined by comparing whether their references point to the same instance.
public static func == (lhs: AnyCancellable, rhs: AnyCancellable) -> Bool
/// The hash value.
///
/// Hash values are not guaranteed to be equal across different executions of
/// your program. Do not save hash values to use during a future execution.
///
/// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
/// conform to `Hashable`, implement the `hash(into:)` requirement instead.
final public var hashValue: Int { get }
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension AnyCancellable {
/// Stores this type-erasing cancellable instance in the specified collection.
///
/// - Parameter collection: The collection in which to store this ``AnyCancellable``.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
final public func store<C>(in collection: inout C) where C : RangeReplaceableCollection, C.Element == AnyCancellable
/// Stores this type-erasing cancellable instance in the specified set.
///
/// - Parameter set: The set in which to store this ``AnyCancellable``.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
final public func store(in set: inout Set<AnyCancellable>)
}
/// A publisher that performs type erasure by wrapping another publisher.
///
/// ``AnyPublisher`` is a concrete implementation of ``Publisher`` that has no significant properties of its own, and passes through elements and completion values from its upstream publisher.
///
/// Use ``AnyPublisher`` to wrap a publisher whose type has details you don’t want to expose across API boundaries, such as different modules. Wrapping a ``Subject`` with ``AnyPublisher`` also prevents callers from accessing its ``Subject/send(_:)`` method. When you use type erasure this way, you can change the underlying publisher implementation over time without affecting existing clients.
///
/// You can use Combine’s ``Publisher/eraseToAnyPublisher()`` operator to wrap a publisher with ``AnyPublisher``.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@frozen public struct AnyPublisher<Output, Failure> : CustomStringConvertible, CustomPlaygroundDisplayConvertible where Failure : Error {
/// A textual representation of this instance.
///
/// Calling this property directly is discouraged. Instead, convert an
/// instance of any type to a string by using the `String(describing:)`
/// initializer. This initializer works with any type, and uses the custom
/// `description` property for types that conform to
/// `CustomStringConvertible`:
///
/// struct Point: CustomStringConvertible {
/// let x: Int, y: Int
///
/// var description: String {
/// return "(\(x), \(y))"
/// }
/// }
///
/// let p = Point(x: 21, y: 30)
/// let s = String(describing: p)
/// print(s)
/// // Prints "(21, 30)"
///
/// The conversion of `p` to a string in the assignment to `s` uses the
/// `Point` type's `description` property.
public var description: String { get }
/// A custom playground description for this instance.
public var playgroundDescription: Any { get }
/// Creates a type-erasing publisher to wrap the provided publisher.
///
/// - Parameter publisher: A publisher to wrap with a type-eraser.
@inlinable public init<P>(_ publisher: P) where Output == P.Output, Failure == P.Failure, P : Publisher
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension AnyPublisher : Publisher {
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
@inlinable public func receive<S>(subscriber: S) where Output == S.Input, Failure == S.Failure, S : Subscriber
}
/// A type-erasing subscriber.
///
/// Use an ``AnySubscriber`` to wrap an existing subscriber whose details you don’t want to expose. You can also use ``AnySubscriber`` to create a custom subscriber by providing closures for the methods defined in ``Subscriber``, rather than implementing ``Subscriber`` directly.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@frozen public struct AnySubscriber<Input, Failure> : Subscriber, CustomStringConvertible, CustomReflectable, CustomPlaygroundDisplayConvertible where Failure : Error {
/// A unique identifier for identifying publisher streams.
public let combineIdentifier: CombineIdentifier
/// A textual representation of this instance.
///
/// Calling this property directly is discouraged. Instead, convert an
/// instance of any type to a string by using the `String(describing:)`
/// initializer. This initializer works with any type, and uses the custom
/// `description` property for types that conform to
/// `CustomStringConvertible`:
///
/// struct Point: CustomStringConvertible {
/// let x: Int, y: Int
///
/// var description: String {
/// return "(\(x), \(y))"
/// }
/// }
///
/// let p = Point(x: 21, y: 30)
/// let s = String(describing: p)
/// print(s)
/// // Prints "(21, 30)"
///
/// The conversion of `p` to a string in the assignment to `s` uses the
/// `Point` type's `description` property.
public var description: String { get }
/// The custom mirror for this instance.
///
/// If this type has value semantics, the mirror should be unaffected by
/// subsequent mutations of the instance.
public var customMirror: Mirror { get }
/// A custom playground description for this instance.
public var playgroundDescription: Any { get }
/// Creates a type-erasing subscriber to wrap an existing subscriber.
///
/// - Parameter s: The subscriber to type-erase.
@inlinable public init<S>(_ s: S) where Input == S.Input, Failure == S.Failure, S : Subscriber
public init<S>(_ s: S) where Input == S.Output, Failure == S.Failure, S : Subject
/// Creates a type-erasing subscriber that executes the provided closures.
///
/// - Parameters:
/// - receiveSubscription: A closure to execute when the subscriber receives the initial subscription from the publisher.
/// - receiveValue: A closure to execute when the subscriber receives a value from the publisher.
/// - receiveCompletion: A closure to execute when the subscriber receives a completion callback from the publisher.
@inlinable public init(receiveSubscription: ((Subscription) -> Void)? = nil, receiveValue: ((Input) -> Subscribers.Demand)? = nil, receiveCompletion: ((Subscribers.Completion<Failure>) -> Void)? = nil)
/// Tells the subscriber that it has successfully subscribed to the publisher and may request items.
///
/// Use the received ``Subscription`` to request items from the publisher.
/// - Parameter subscription: A subscription that represents the connection between publisher and subscriber.
@inlinable public func receive(subscription: Subscription)
/// Tells the subscriber that the publisher has produced an element.
///
/// - Parameter input: The published element.
/// - Returns: A `Subscribers.Demand` instance indicating how many more elements the subscriber expects to receive.
@inlinable public func receive(_ value: Input) -> Subscribers.Demand
/// Tells the subscriber that the publisher has completed publishing, either normally or with an error.
///
/// - Parameter completion: A ``Subscribers/Completion`` case indicating whether publishing completed normally or with an error.
@inlinable public func receive(completion: Subscribers.Completion<Failure>)
}
/// A publisher that exposes its elements as an asynchronous sequence.
///
/// `AsyncPublisher` conforms to <doc://com.apple.documentation/documentation/Swift/AsyncSequence>, which allows callers to receive values with the `for`-`await`-`in` syntax, rather than attaching a ``Subscriber``.
///
/// Use the ``Combine/Publisher/values-1dm9r`` property of the ``Combine/Publisher`` protocol to wrap an existing publisher with an instance of this type.
@available(macOS 12.0, iOS 15.0, tvOS 15.0, watchOS 8.0, *)
public struct AsyncPublisher<P> : AsyncSequence where P : Publisher, P.Failure == Never {
/// The type of element produced by this asynchronous sequence.
public typealias Element = P.Output
/// The iterator that produces elements of the asynchronous publisher sequence.
public struct Iterator : AsyncIteratorProtocol {
/// Produces the next element in the prefix sequence.
///
/// - Returns: The next published element, or nil if the publisher finishes normally.
public mutating func next() async -> P.Output?
public typealias Element = P.Output
}
/// Creates a publisher that exposes elements received from an upstream publisher as an asynchronous sequence.
///
/// - Parameter publisher: An upstream publisher. The asynchronous publisher converts elements received from this publisher into an asynchronous sequence.
public init(_ publisher: P)
/// Creates the asynchronous iterator that produces elements of this asynchronous sequence.
///
/// - Returns: An instance of the `AsyncIterator` type used to produce elements of the asynchronous sequence.
public func makeAsyncIterator() -> AsyncPublisher<P>.Iterator
/// The type of asynchronous iterator that produces elements of this
/// asynchronous sequence.
public typealias AsyncIterator = AsyncPublisher<P>.Iterator
}
/// A publisher that exposes its elements as a throwing asynchronous sequence.
///
/// `AsyncThrowingPublisher` conforms to <doc://com.apple.documentation/documentation/Swift/AsyncSequence>, which allows callers to receive values with the `for`-`await`-`in` syntax, rather than attaching a ``Subscriber``. If the upstream publisher terminates with an error, `AsyncThrowingPublisher` throws the error to the awaiting caller.
///
/// Use the ``Combine/Publisher/values-v7nz`` property of the ``Combine/Publisher`` protocol to wrap an existing publisher with an instance of this type.
@available(macOS 12.0, iOS 15.0, tvOS 15.0, watchOS 8.0, *)
public struct AsyncThrowingPublisher<P> : AsyncSequence where P : Publisher {
/// The type of element produced by this asynchronous sequence.
public typealias Element = P.Output
/// The iterator that produces elements of the asynchronous publisher sequence.
public struct Iterator : AsyncIteratorProtocol {
/// Produces the next element in the prefix sequence.
///
/// - Returns: The next published element, or nil if the publisher finishes normally. If the publisher terminates with an error, the call point receives the error as a `throw`.
public mutating func next() async throws -> P.Output?
public typealias Element = P.Output
}
/// Creates a publisher that exposes elements received from an upstream publisher as a throwing asynchronous sequence.
/// - Parameter publisher: An upstream publisher. The asynchronous publisher converts elements received from this publisher into an asynchronous sequence.
public init(_ publisher: P)
/// Creates the asynchronous iterator that produces elements of this asynchronous sequence.
///
/// - Returns: An instance of the `AsyncIterator` type used to produce elements of the asynchronous sequence.
public func makeAsyncIterator() -> AsyncThrowingPublisher<P>.Iterator
/// The type of asynchronous iterator that produces elements of this
/// asynchronous sequence.
public typealias AsyncIterator = AsyncThrowingPublisher<P>.Iterator
}
/// A protocol indicating that an activity or action supports cancellation.
///
/// Calling ``Cancellable/cancel()`` frees up any allocated resources. It also stops side effects such as timers, network access, or disk I/O.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public protocol Cancellable {
/// Cancel the activity.
///
/// When implementing ``Cancellable`` in support of a custom publisher, implement `cancel()` to request that your publisher stop calling its downstream subscribers. Combine doesn't require that the publisher stop immediately, but the `cancel()` call should take effect quickly. Canceling should also eliminate any strong references it currently holds.
///
/// After you receive one call to `cancel()`, subsequent calls shouldn't do anything. Additionally, your implementation must be thread-safe, and it shouldn't block the caller.
///
/// > Tip: Keep in mind that your `cancel()` may execute concurrently with another call to `cancel()` --- including the scenario where an ``AnyCancellable`` is deallocating --- or to ``Subscription/request(_:)``.
func cancel()
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Cancellable {
/// Stores this cancellable instance in the specified collection.
///
/// - Parameter collection: The collection in which to store this ``Cancellable``.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public func store<C>(in collection: inout C) where C : RangeReplaceableCollection, C.Element == AnyCancellable
/// Stores this cancellable instance in the specified set.
///
/// - Parameter set: The set in which to store this ``Cancellable``.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public func store(in set: inout Set<AnyCancellable>)
}
/// A unique identifier for identifying publisher streams.
///
/// To conform to ``CustomCombineIdentifierConvertible`` in a
/// ``Subscription`` or ``Subject`` that you implement as a structure, create an instance of ``CombineIdentifier`` as follows:
///
/// let combineIdentifier = CombineIdentifier()
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct CombineIdentifier : Hashable, CustomStringConvertible {
/// Creates a unique Combine identifier.
public init()
/// Creates a Combine identifier, using the bit pattern of the provided object.
public init(_ obj: AnyObject)
/// A textual representation of this instance.
public var description: String { get }
/// Hashes the essential components of this value by feeding them into the
/// given hasher.
///
/// Implement this method to conform to the `Hashable` protocol. The
/// components used for hashing must be the same as the components compared
/// in your type's `==` operator implementation. Call `hasher.combine(_:)`
/// with each of these components.
///
/// - Important: Never call `finalize()` on `hasher`. Doing so may become a
/// compile-time error in the future.
///
/// - Parameter hasher: The hasher to use when combining the components
/// of this instance.
public func hash(into hasher: inout Hasher)
/// Returns a Boolean value indicating whether two values are equal.
///
/// Equality is the inverse of inequality. For any values `a` and `b`,
/// `a == b` implies that `a != b` is `false`.
///
/// - Parameters:
/// - lhs: A value to compare.
/// - rhs: Another value to compare.
public static func == (a: CombineIdentifier, b: CombineIdentifier) -> Bool
/// The hash value.
///
/// Hash values are not guaranteed to be equal across different executions of
/// your program. Do not save hash values to use during a future execution.
///
/// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
/// conform to `Hashable`, implement the `hash(into:)` requirement instead.
public var hashValue: Int { get }
}
/// A publisher that provides an explicit means of connecting and canceling publication.
///
/// Use a ``ConnectablePublisher`` when you need to perform additional configuration or setup prior to producing any elements.
///
/// This publisher doesn’t produce any elements until you call its ``ConnectablePublisher/connect()`` method.
///
/// Use ``Publisher/makeConnectable()`` to create a ``ConnectablePublisher`` from any publisher whose failure type is <doc://com.apple.documentation/documentation/Swift/Never>.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public protocol ConnectablePublisher<Output, Failure> : Publisher {
/// Connects to the publisher, allowing it to produce elements, and returns an instance with which to cancel publishing.
///
/// - Returns: A ``Cancellable`` instance that you use to cancel publishing.
func connect() -> Cancellable
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension ConnectablePublisher {
/// Automates the process of connecting or disconnecting from this connectable publisher.
///
/// Use ``ConnectablePublisher/autoconnect()`` to simplify working with ``ConnectablePublisher`` instances, such as <doc://com.apple.documentation/documentation/Foundation/Timer/TimerPublisher> in the Foundation framework.
///
/// In the following example, the <doc://com.apple.documentation/documentation/Foundation/Timer/3329589-publish> operator creates a <doc://com.apple.documentation/documentation/Foundation/Timer/TimerPublisher>, which is a ``ConnectablePublisher``. As a result, subscribers don’t receive any values until after a call to ``ConnectablePublisher/connect()``.
/// For convenience when working with a single subscriber, the ``ConnectablePublisher/autoconnect()`` operator performs the ``ConnectablePublisher/connect()`` call when attached to by the subscriber.
///
/// cancellable = Timer.publish(every: 1, on: .main, in: .default)
/// .autoconnect()
/// .sink { date in
/// print ("Date now: \(date)")
/// }
/// - Returns: A publisher which automatically connects to its upstream connectable publisher.
public func autoconnect() -> Publishers.Autoconnect<Self>
}
/// A subject that wraps a single value and publishes a new element whenever the value changes.
///
/// Unlike ``PassthroughSubject``, ``CurrentValueSubject`` maintains a buffer of the most recently published element.
///
/// Calling ``CurrentValueSubject/send(_:)`` on a ``CurrentValueSubject`` also updates the current value, making it equivalent to updating the ``CurrentValueSubject/value`` directly.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
final public class CurrentValueSubject<Output, Failure> : Subject where Failure : Error {
/// The value wrapped by this subject, published as a new element whenever it changes.
final public var value: Output
/// Creates a current value subject with the given initial value.
///
/// - Parameter value: The initial value to publish.
public init(_ value: Output)
/// Sends a subscription to the subscriber.
///
/// This call provides the ``Subject`` an opportunity to establish demand for any new upstream subscriptions.
///
/// - Parameter subscription: The subscription instance through which the subscriber can request elements.
final public func send(subscription: Subscription)
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
final public func receive<S>(subscriber: S) where Output == S.Input, Failure == S.Failure, S : Subscriber
/// Sends a value to the subscriber.
///
/// - Parameter value: The value to send.
final public func send(_ input: Output)
/// Sends a completion signal to the subscriber.
///
/// - Parameter completion: A `Completion` instance which indicates whether publishing has finished normally or failed with an error.
final public func send(completion: Subscribers.Completion<Failure>)
}
/// A protocol for uniquely identifying publisher streams.
///
/// If you create a custom ``Subscription`` or ``Subscriber`` type, implement this protocol so that development tools can uniquely identify publisher chains in your app.
/// If your type is a class, Combine provides an implementation of ``CustomCombineIdentifierConvertible/combineIdentifier-1frze`` for you.
/// If your type is a structure, set up the identifier as follows:
///
/// let combineIdentifier = CombineIdentifier()
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public protocol CustomCombineIdentifierConvertible {
/// A unique identifier for identifying publisher streams.
var combineIdentifier: CombineIdentifier { get }
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension CustomCombineIdentifierConvertible where Self : AnyObject {
/// A unique identifier for identifying publisher streams.
public var combineIdentifier: CombineIdentifier { get }
}
/// A publisher that awaits subscription before running the supplied closure to create a publisher for the new subscriber.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct Deferred<DeferredPublisher> : Publisher where DeferredPublisher : Publisher {
/// The kind of values published by this publisher.
public typealias Output = DeferredPublisher.Output
/// The kind of errors this publisher might publish.
public typealias Failure = DeferredPublisher.Failure
/// The closure to execute when this deferred publisher receives a subscription.
///
/// The publisher returned by this closure immediately receives the incoming subscription.
public let createPublisher: () -> DeferredPublisher
/// Creates a deferred publisher.
///
/// - Parameter createPublisher: The closure to execute when calling `subscribe(_:)`.
public init(createPublisher: @escaping () -> DeferredPublisher)
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
public func receive<S>(subscriber: S) where S : Subscriber, DeferredPublisher.Failure == S.Failure, DeferredPublisher.Output == S.Input
}
/// A publisher that never publishes any values, and optionally finishes immediately.
///
/// You can create a ”Never” publisher — one which never sends values and never finishes or fails — with the initializer `Empty(completeImmediately: false)`.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct Empty<Output, Failure> : Publisher, Equatable where Failure : Error {
/// Creates an empty publisher.
///
/// - Parameter completeImmediately: A Boolean value that indicates whether the publisher should immediately finish.
public init(completeImmediately: Bool = true)
/// Creates an empty publisher with the given completion behavior and output and failure types.
///
/// Use this initializer to connect the empty publisher to subscribers or other publishers that have specific output and failure types.
///
/// - Parameters:
/// - completeImmediately: A Boolean value that indicates whether the publisher should immediately finish.
/// - outputType: The output type exposed by this publisher.
/// - failureType: The failure type exposed by this publisher.
public init(completeImmediately: Bool = true, outputType: Output.Type, failureType: Failure.Type)
/// A Boolean value that indicates whether the publisher immediately sends a completion.
///
/// If `true`, the publisher finishes immediately after sending a subscription to the subscriber. If `false`, it never completes.
public let completeImmediately: Bool
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
public func receive<S>(subscriber: S) where Output == S.Input, Failure == S.Failure, S : Subscriber
/// Returns a Boolean value that indicates whether two publishers are equivalent.
/// - Parameters:
/// - lhs: An `Empty` instance to compare.
/// - rhs: Another `Empty` instance to compare.
/// - Returns: `true` if the two publishers have equal `completeImmediately` properties; otherwise `false`.
public static func == (lhs: Empty<Output, Failure>, rhs: Empty<Output, Failure>) -> Bool
}
/// A publisher that immediately terminates with the specified error.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct Fail<Output, Failure> : Publisher where Failure : Error {
/// Creates a publisher that immediately terminates with the specified failure.
///
/// - Parameter error: The failure to send when terminating the publisher.
public init(error: Failure)
/// Creates publisher with the given output type, that immediately terminates with the specified failure.
///
/// Use this initializer to create a `Fail` publisher that can work with subscribers or publishers that expect a given output type.
///
/// - Parameters:
/// - outputType: The output type exposed by this publisher.
/// - failure: The failure to send when terminating the publisher.
public init(outputType: Output.Type, failure: Failure)
/// The failure to send when terminating the publisher.
public let error: Failure
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
public func receive<S>(subscriber: S) where Output == S.Input, Failure == S.Failure, S : Subscriber
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Fail : Equatable where Failure : Equatable {
/// Returns a Boolean value that indicates whether two publishers are equivalent.
/// - Parameters:
/// - lhs: A `Fail` publisher to compare for equality.
/// - rhs: Another `Fail` publisher to compare for equality.
/// - Returns: `true` if the publishers have equal `error` properties; otherwise `false`.
public static func == (lhs: Fail<Output, Failure>, rhs: Fail<Output, Failure>) -> Bool
}
/// A publisher that eventually produces a single value and then finishes or fails.
///
/// Use a future to perform some work and then asynchronously publish a single element. You initialize the future with a closure that takes a ``Combine/Future/Promise``; the closure calls the promise with a <doc://com.apple.documentation/documentation/Swift/Result> that indicates either success or failure. In the success case, the future's downstream subscriber receives the element prior to the publishing stream finishing normally. If the result is an error, publishing terminates with that error.
///
/// The following example shows a method that uses a future to asynchronously publish a random number after a brief delay:
///
/// func generateAsyncRandomNumberFromFuture() -> Future <Int, Never> {
/// return Future() { promise in
/// DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
/// let number = Int.random(in: 1...10)
/// promise(Result.success(number))
/// }
/// }
/// }
///
/// To receive the published value, you use any Combine subscriber, such as a ``Combine/Subscribers/Sink``, like this:
///
/// cancellable = generateAsyncRandomNumberFromFuture()
/// .sink { number in print("Got random number \(number).") }
///
/// ### Integrating with Swift Concurrency
///
/// To integrate with the `async`-`await` syntax in Swift 5.5, `Future` can provide its value to an awaiting caller. This is particularly useful because unlike other types that conform to ``Publisher`` and potentially publish many elements, a `Future` only publishes one element (or fails). By using the ``Combine/Future/value-9iwjz`` property, the above call point looks like this:
///
/// let number = await generateAsyncRandomNumberFromFuture().value
/// print("Got random number \(number).")
///
/// ### Alternatives to Futures
///
/// The `async`-`await` syntax in Swift can also replace the use of a future entirely, for the case where you want to perform some operation after an asynchronous task completes.
///
/// You do this with the function <doc://com.apple.documentation/documentation/Swift/3814988-withCheckedContinuation> and its throwing equivalent, <doc://com.apple.documentation/documentation/Swift/3814989-withCheckedThrowingContinuation>. The following example performs the same asynchronous random number generation as the `Future` example above, but as an `async` method:
///
/// func generateAsyncRandomNumberFromContinuation() async -> Int {
/// return await withCheckedContinuation { continuation in
/// DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
/// let number = Int.random(in: 1...10)
/// continuation.resume(returning: number)
/// }
/// }
/// }
///
/// The call point for this method doesn't use a closure like the future's sink subscriber does; it simply awaits and assigns the result:
///
/// let asyncRandom = await generateAsyncRandomNumberFromContinuation()
///
/// For more information on continuations, see the <doc://com.apple.documentation/documentation/swift/swift_standard_library/concurrency> topic in the Swift standard library.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
final public class Future<Output, Failure> : Publisher where Failure : Error {
/// A type that represents a closure to invoke in the future, when an element or error is available.
///
/// The promise closure receives one parameter: a `Result` that contains either a single element published by a ``Future``, or an error.
public typealias Promise = (Result<Output, Failure>) -> Void
/// Creates a publisher that invokes a promise closure when the publisher emits an element.
///
/// - Parameter attemptToFulfill: A ``Future/Promise`` that the publisher invokes when the publisher emits an element or terminates with an error.
public init(_ attemptToFulfill: @escaping (@escaping Future<Output, Failure>.Promise) -> Void)
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
final public func receive<S>(subscriber: S) where Output == S.Input, Failure == S.Failure, S : Subscriber
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Future where Failure == Never {
/// The published value of the future, delivered asynchronously.
///
/// This property subscribes to the `Future` and delivers the value asynchronously when the `Future` publishes it. Use this property when you want to use the `async`-`await` syntax with a `Future`.
@available(macOS 12.0, iOS 15.0, tvOS 15.0, watchOS 8.0, *)
final public var value: Output { get async }
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Future {
/// The published value of the future or an error, delivered asynchronously.
///
/// This property subscribes to the `Future` and delivers the value asynchronously when the `Future` publishes it. If the `Future` terminates with an error, the awaiting caller receives the error instead. Use this property when you want to the `async`-`await` syntax with a `Future` whose ``Publisher/Failure`` type is not <doc://com.apple.documentation/documentation/Swift/Never>.
@available(macOS 12.0, iOS 15.0, tvOS 15.0, watchOS 8.0, *)
final public var value: Output { get async throws }
}
/// A scheduler for performing synchronous actions.
///
/// You can only use this scheduler for immediate actions. If you attempt to schedule actions after a specific date, this scheduler ignores the date and performs them immediately.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct ImmediateScheduler : Scheduler {
/// The time type used by the immediate scheduler.
public struct SchedulerTimeType : Strideable {
/// Returns the distance to another immediate scheduler time; this distance is always `0` in the context of an immediate scheduler.
///
/// - Parameter other: The other scheduler time.
/// - Returns: `0`, as a `Stride`.
public func distance(to other: ImmediateScheduler.SchedulerTimeType) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Advances the time by the specified amount; this is meaningless in the context of an immediate scheduler.
///
/// - Parameter n: The amount to advance by. The `ImmediateScheduler` ignores this value.
/// - Returns: An empty `SchedulerTimeType`.
public func advanced(by n: ImmediateScheduler.SchedulerTimeType.Stride) -> ImmediateScheduler.SchedulerTimeType
/// The increment by which the immediate scheduler counts time.
public struct Stride : ExpressibleByFloatLiteral, Comparable, SignedNumeric, Codable, SchedulerTimeIntervalConvertible {
/// The type used when evaluating floating-point literals.
public typealias FloatLiteralType = Double
/// The type used when evaluating integer literals.
public typealias IntegerLiteralType = Int
/// The type used for expressing the stride’s magnitude.
public typealias Magnitude = Int
/// The value of this time interval in seconds.
public var magnitude: Int
/// Creates an immediate scheduler time interval from the given time interval.
public init(_ value: Int)
/// Creates an immediate scheduler time interval from an integer seconds value.
public init(integerLiteral value: Int)
/// Creates an immediate scheduler time interval from a floating-point seconds value.
public init(floatLiteral value: Double)
/// Creates an immediate scheduler time interval from a binary integer type.
///
/// If `exactly` can’t convert to an `Int`, the resulting time interval is `nil`.
public init?<T>(exactly source: T) where T : BinaryInteger
/// Returns a Boolean value indicating whether the value of the first
/// argument is less than that of the second argument.
///
/// This function is the only requirement of the `Comparable` protocol. The
/// remainder of the relational operator functions are implemented by the
/// standard library for any type that conforms to `Comparable`.
///
/// - Parameters:
/// - lhs: A value to compare.
/// - rhs: Another value to compare.
public static func < (lhs: ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride) -> Bool
/// Multiplies two values and produces their product.
///
/// The multiplication operator (`*`) calculates the product of its two
/// arguments. For example:
///
/// 2 * 3 // 6
/// 100 * 21 // 2100
/// -10 * 15 // -150
/// 3.5 * 2.25 // 7.875
///
/// You cannot use `*` with arguments of different types. To multiply values
/// of different types, convert one of the values to the other value's type.
///
/// let x: Int8 = 21
/// let y: Int = 1000000
/// Int(x) * y // 21000000
///
/// - Parameters:
/// - lhs: The first value to multiply.
/// - rhs: The second value to multiply.
public static func * (lhs: ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Adds two values and produces their sum.
///
/// The addition operator (`+`) calculates the sum of its two arguments. For
/// example:
///
/// 1 + 2 // 3
/// -10 + 15 // 5
/// -15 + -5 // -20
/// 21.5 + 3.25 // 24.75
///
/// You cannot use `+` with arguments of different types. To add values of
/// different types, convert one of the values to the other value's type.
///
/// let x: Int8 = 21
/// let y: Int = 1000000
/// Int(x) + y // 1000021
///
/// - Parameters:
/// - lhs: The first value to add.
/// - rhs: The second value to add.
public static func + (lhs: ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Subtracts one value from another and produces their difference.
///
/// The subtraction operator (`-`) calculates the difference of its two
/// arguments. For example:
///
/// 8 - 3 // 5
/// -10 - 5 // -15
/// 100 - -5 // 105
/// 10.5 - 100.0 // -89.5
///
/// You cannot use `-` with arguments of different types. To subtract values
/// of different types, convert one of the values to the other value's type.
///
/// let x: UInt8 = 21
/// let y: UInt = 1000000
/// y - UInt(x) // 999979
///
/// - Parameters:
/// - lhs: A numeric value.
/// - rhs: The value to subtract from `lhs`.
public static func - (lhs: ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Subtracts the second value from the first and stores the difference in the
/// left-hand-side variable.
///
/// - Parameters:
/// - lhs: A numeric value.
/// - rhs: The value to subtract from `lhs`.
public static func -= (lhs: inout ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride)
/// Multiplies two values and stores the result in the left-hand-side
/// variable.
///
/// - Parameters:
/// - lhs: The first value to multiply.
/// - rhs: The second value to multiply.
public static func *= (lhs: inout ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride)
/// Adds two values and stores the result in the left-hand-side variable.
///
/// - Parameters:
/// - lhs: The first value to add.
/// - rhs: The second value to add.
public static func += (lhs: inout ImmediateScheduler.SchedulerTimeType.Stride, rhs: ImmediateScheduler.SchedulerTimeType.Stride)
/// Converts the specified number of seconds into an instance of this scheduler time type.
public static func seconds(_ s: Int) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Converts the specified number of seconds, as a floating-point value, into an instance of this scheduler time type.
public static func seconds(_ s: Double) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Converts the specified number of milliseconds into an instance of this scheduler time type.
public static func milliseconds(_ ms: Int) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Converts the specified number of microseconds into an instance of this scheduler time type.
public static func microseconds(_ us: Int) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Converts the specified number of nanoseconds into an instance of this scheduler time type.
public static func nanoseconds(_ ns: Int) -> ImmediateScheduler.SchedulerTimeType.Stride
/// Returns a Boolean value indicating whether two values are equal.
///
/// Equality is the inverse of inequality. For any values `a` and `b`,
/// `a == b` implies that `a != b` is `false`.
///
/// - Parameters:
/// - lhs: A value to compare.
/// - rhs: Another value to compare.
public static func == (a: ImmediateScheduler.SchedulerTimeType.Stride, b: ImmediateScheduler.SchedulerTimeType.Stride) -> Bool
/// Encodes this value into the given encoder.
///
/// If the value fails to encode anything, `encoder` will encode an empty
/// keyed container in its place.
///
/// This function throws an error if any values are invalid for the given
/// encoder's format.
///
/// - Parameter encoder: The encoder to write data to.
public func encode(to encoder: Encoder) throws
/// Creates a new instance by decoding from the given decoder.
///
/// This initializer throws an error if reading from the decoder fails, or
/// if the data read is corrupted or otherwise invalid.
///
/// - Parameter decoder: The decoder to read data from.
public init(from decoder: Decoder) throws
}
}
/// A type that defines options accepted by the immediate scheduler.
public typealias SchedulerOptions = Never
/// The shared instance of the immediate scheduler.
///
/// You cannot create instances of the immediate scheduler yourself. Use only the shared instance.
public static let shared: ImmediateScheduler
/// Performs the action at the next possible opportunity.
public func schedule(options: ImmediateScheduler.SchedulerOptions?, _ action: @escaping () -> Void)
/// The immediate scheduler’s definition of the current moment in time.
public var now: ImmediateScheduler.SchedulerTimeType { get }
/// The minimum tolerance allowed by the immediate scheduler.
public var minimumTolerance: ImmediateScheduler.SchedulerTimeType.Stride { get }
/// Performs the action at some time after the specified date.
///
/// The immediate scheduler ignores `date` and performs the action immediately.
public func schedule(after date: ImmediateScheduler.SchedulerTimeType, tolerance: ImmediateScheduler.SchedulerTimeType.Stride, options: ImmediateScheduler.SchedulerOptions?, _ action: @escaping () -> Void)
/// Performs the action at some time after the specified date, at the specified frequency, optionally taking into account tolerance if possible.
///
/// The immediate scheduler ignores `date` and performs the action immediately.
public func schedule(after date: ImmediateScheduler.SchedulerTimeType, interval: ImmediateScheduler.SchedulerTimeType.Stride, tolerance: ImmediateScheduler.SchedulerTimeType.Stride, options: ImmediateScheduler.SchedulerOptions?, _ action: @escaping () -> Void) -> Cancellable
}
/// A publisher that emits an output to each subscriber just once, and then finishes.
///
/// You can use a ``Just`` publisher to start a chain of publishers. A ``Just`` publisher is also useful when replacing a value with ``Publishers/Catch``.
///
/// In contrast with <doc://com.apple.documentation/documentation/Swift/Result/Publisher>, a ``Just`` publisher can’t fail with an error. And unlike <doc://com.apple.documentation/documentation/Swift/Optional/Publisher>, a ``Just`` publisher always produces a value.
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public struct Just<Output> : Publisher {
/// The kind of errors this publisher might publish.
///
/// Use `Never` if this `Publisher` does not publish errors.
public typealias Failure = Never
/// The one element that the publisher emits.
public let output: Output
/// Initializes a publisher that emits the specified output just once.
///
/// - Parameter output: The one element that the publisher emits.
public init(_ output: Output)
/// Attaches the specified subscriber to this publisher.
///
/// Implementations of ``Publisher`` must implement this method.
///
/// The provided implementation of ``Publisher/subscribe(_:)-4u8kn``calls this method.
///
/// - Parameter subscriber: The subscriber to attach to this ``Publisher``, after which it can receive values.
public func receive<S>(subscriber: S) where Output == S.Input, S : Subscriber, S.Failure == Never
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Just : Equatable where Output : Equatable {
/// Returns a Boolean value that indicates whether two publishers are equivalent.
/// - Parameters:
/// - lhs: A `Just` publisher to compare for equality.
/// - rhs: Another `Just` publisher to compare for equality.
/// - Returns: `true` if the publishers have equal `output` properties; otherwise `false`.
public static func == (lhs: Just<Output>, rhs: Just<Output>) -> Bool
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Just where Output : Comparable {
public func min() -> Just<Output>
public func max() -> Just<Output>
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Just where Output : Equatable {
public func contains(_ output: Output) -> Just<Bool>
public func removeDuplicates() -> Just<Output>
}
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
extension Just {
public func allSatisfy(_ predicate: (Output) -> Bool) -> Just<Bool>
public func tryAllSatisfy(_ predicate: (Output) throws -> Bool) -> Result<Bool, Error>.Publisher
public func collect() -> Just<[Output]>
public func compactMap<T>(_ transform: (Output) -> T?) -> Optional<T>.Publisher
public func min(by areInIncreasingOrder: (Output, Output) -> Bool) -> Just<Output>
public func max(by areInIncreasingOrder: (Output, Output) -> Bool) -> Just<Output>
public func prepend(_ elements: Output...) -> Publishers.Sequence<[Output], Just<Output>.Failure>
public func prepend<S>(_ elements: S) -> Publishers.Sequence<[Output], Just<Output>.Failure> where Output == S.Element, S : Sequence
public func append(_ elements: Output...) -> Publishers.Sequence<[Output], Just<Output>.Failure>
public func append<S>(_ elements: S) -> Publishers.Sequence<[Output], Just<Output>.Failure> where Output == S.Element, S : Sequence
public func contains(where predicate: (Output) -> Bool) -> Just<Bool>
public func tryContains(where predicate: (Output) throws -> Bool) -> Result<Bool, Error>.Publisher
public func count() -> Just<Int>
public func dropFirst(_ count: Int = 1) -> Optional<Output>.Publisher
public func drop(while predicate: (Output) -> Bool) -> Optional<Output>.Publisher
public func first() -> Just<Output>
public func first(where predicate: (Output) -> Bool) -> Optional<Output>.Publisher
public func last() -> Just<Output>
public func last(where predicate: (Output) -> Bool) -> Optional<Output>.Publisher
public func filter(_ isIncluded: (Output) -> Bool) -> Optional<Output>.Publisher
public func ignoreOutput() -> Empty<Output, Just<Output>.Failure>
public func map<T>(_ transform: (Output) -> T) -> Just<T>