### CocoaPods installation for RxOptional Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Add `RxOptional` to your Podfile to install the library using CocoaPods. Ensure you run `pod install` afterwards. ```ruby pod 'RxOptional' ``` -------------------------------- ### Driver and Signal Support Examples Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Illustrates RxOptional operator usage with Driver and Signal, which cannot error out. Examples include replacing nil text field values and filtering empty search queries. ```swift import RxSwift import RxCocoa import RxOptional let disposeBag = DisposeBag() // Binding an optional text field value to a label — nil replaced, never errors let usernameDriver: Driver = usernameTextField.rx.text.asDriver() usernameDriver .replaceNilWith("Anonymous") // Driver .drive(usernameLabel.rx.text) .disposed(by: disposeBag) // Filtering empty search queries before hitting an API let searchDriver: Driver = searchBar.rx.text.orEmpty.asDriver() searchDriver .filterEmpty() // suppress empty strings .distinctUntilChanged() .debounce(.milliseconds(300)) .drive(onNext: { query in print("Searching for:", query) }) .disposed(by: disposeBag) ``` -------------------------------- ### Carthage installation for RxOptional Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Add the RxOptional repository to your Cartfile and run `carthage update` to integrate the library using Carthage. ```bash github "RxSwiftCommunity/RxOptional" ~> 4.1.0 ``` ```bash $ carthage update ``` -------------------------------- ### RxOptional Installation with CocoaPods Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Install RxOptional using CocoaPods by adding 'RxOptional' to your Podfile. ```ruby # CocoaPods pod 'RxOptional' ``` -------------------------------- ### RxOptional Installation with Carthage Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Add RxOptional to your Cartfile for Carthage integration. ```shell # Cartfile github "RxSwiftCommunity/RxOptional" ~> 5.0 ``` -------------------------------- ### Swift Package Manager installation for RxOptional Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Include RxOptional as a dependency in your `Package.swift` file to use it with Swift Package Manager. ```swift import PackageDescription let package = Package( name: "ProjectName", dependencies: [ .Package(url: "https://github.com/RxSwiftCommunity/RxOptional") ] ) ``` -------------------------------- ### RxOptionalError Cases and Usage Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Demonstrates the two cases of RxOptionalError and how to catch them in a subscriber. Use errorOnNil to convert a nil Optional into an error. ```swift import RxOptional // Two cases: // .foundNilWhileUnwrappingOptional(Any.Type) // .emptyOccupiable(Any.Type) let nilError = RxOptionalError.foundNilWhileUnwrappingOptional(String?.self) print(nilError) // "Found nil while trying to unwrap type >" let emptyError = RxOptionalError.emptyOccupiable([Int].self) print(emptyError) // "Empty occupiable of type >" // Catching RxOptionalError in a subscriber: Observable .of("Hello", nil) .errorOnNil() .subscribe( onNext: { print($0) }, onError: { error in if case RxOptionalError.foundNilWhileUnwrappingOptional(let type) = error { print("Nil encountered for type: \(type)") } } ) ``` -------------------------------- ### Custom Occupiable Conformance Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Demonstrates how to make a custom type conform to the Occupiable protocol by implementing the isEmpty property. ```swift import RxOptional struct Queue: Occupiable { private var items: [T] = [] var isEmpty: Bool { items.isEmpty } // isNotEmpty is provided automatically by the protocol extension } ``` -------------------------------- ### errorOnEmpty(_:) Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Throws an error when an empty occupiable element is encountered. Defaults to RxOptionalError.emptyOccupiable. Not available on Driver or Signal. ```APIDOC ## errorOnEmpty(_:) ### Description Terminates the observable sequence with an error when an empty `Occupiable` element is encountered. By default, it throws `RxOptionalError.emptyOccupiable`. A custom error can be provided as an argument. ### Supported Sequences - `Observable` where `T` conforms to `Occupiable` ### Parameters - `error` (Error) - Optional: The custom error to throw when an empty element is encountered. Defaults to `RxOptionalError.emptyOccupiable`. ### Example (Default Error) ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable<[Int]> .of([1, 2], [], [3]) .errorOnEmpty() .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) // Output: // next: [1, 2] // error: Empty occupiable of type > ``` ### Example (Custom Error) ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() enum DataError: Error { case noResults } Observable<[String]> .of(["a"], []) .errorOnEmpty(DataError.noResults) .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) // Output: // next: ["a"] // error: noResults ``` ``` -------------------------------- ### Error on Empty Occupiable Element Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Throws an error when an empty occupiable element is encountered. Defaults to RxOptionalError.emptyOccupiable. Not available on Driver or Signal. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable<[Int]> .of([1, 2], [], [3]) .errorOnEmpty() .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) // Custom error: enum DataError: Error { case noResults } Observable<[String]> .of(["a"], []) .errorOnEmpty(DataError.noResults) .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) ``` -------------------------------- ### errorOnNil(_:) Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Throws an error when a nil element is encountered, completing the stream with a failure. Not available on Driver or Signal. ```APIDOC ## errorOnNil(_:) ### Description Throws an error when a `nil` element is encountered, completing the stream with a failure. Defaults to `RxOptionalError.foundNilWhileUnwrappingOptional`. **Not available on `Driver` or `Signal`** because those sequences cannot error out. ### Method `errorOnNil(error: Error = RxOptionalError.foundNilWhileUnwrappingOptional)` ### Parameters - **error** (Error) - Optional - The error to throw when a `nil` is encountered. Defaults to `RxOptionalError.foundNilWhileUnwrappingOptional`. ### Request Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of("One", nil, "Three") .errorOnNil() .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) // Output: // next: One // error: Found nil while trying to unwrap type > // Custom error example: enum AppError: Error { case missingValue } Observable .of("One", nil, "Three") .errorOnNil(AppError.missingValue) .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) // Output: // next: One // error: missingValue ``` ### Response #### Success Response An `Observable` that completes normally if no `nil` values are encountered. #### Error Response Terminates with the specified error if a `nil` value is found. #### Response Example ``` next: One error: Found nil while trying to unwrap type > ``` ``` -------------------------------- ### replaceNilWith(_:) Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Replaces every nil element with a provided default value and unwraps the stream to Observable. Available on Observable, Driver, and Signal. ```APIDOC ## replaceNilWith(_:) ### Description Replaces every `nil` element with a provided default value and unwraps the stream to `Observable`. Available on `Observable`, `Driver`, and `Signal`. ### Method `replaceNilWith(defaultValue: T)` ### Parameters - **defaultValue** (T) - Required - The value to substitute for `nil` elements. ### Request Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of(1, nil, 3, nil, 5) .replaceNilWith(0) .subscribe { print($0) } .disposed(by: disposeBag) ``` ### Response #### Success Response An `Observable` where all `nil` elements have been replaced with the specified default value. #### Response Example ``` next(1) next(0) next(3) next(0) next(5) completed ``` ``` -------------------------------- ### catchOnNil(_:) Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt When a nil element is encountered, the provided closure is called and its returned Observable is subscribed to in place of the nil. Available on Observable, Driver, and Signal. ```APIDOC ## catchOnNil(_:) ### Description When a `nil` element is encountered, the provided closure is called and its returned `Observable` is subscribed to in place of the nil. Available on `Observable`, `Driver`, and `Signal` (handler must be non-throwing on `Driver`/`Signal`). ### Method `catchOnNil(handler: @escaping () -> Observable)` ### Parameters - **handler** (() -> Observable) - Required - A closure that returns an `Observable` to be subscribed to when a `nil` element is encountered. ### Request Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() func fetchFallbackUser() -> Observable { return Observable.just("DefaultUser") } Observable .of("Alice", nil, "Carol") .catchOnNil { fetchFallbackUser() } .subscribe { print($0) } .disposed(by: disposeBag) ``` ### Response #### Success Response An `Observable` where `nil` elements are replaced by the sequence emitted by the `handler` closure. #### Response Example ``` next(Alice) next(DefaultUser) next(Carol) completed ``` ``` -------------------------------- ### Replace nil with a fallback Observable Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Employ `catchOnNil(_:)` to handle nil elements by subscribing to a provided fallback observable. This is useful for providing default values or alternative data sources when a primary observable emits nil. This operator is available on `Observable`, `Driver`, and `Signal`. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() // Fallback to a network request or cached value when nil is encountered func fetchFallbackUser() -> Observable { return Observable.just("DefaultUser") // e.g. network/cache call } Observable .of("Alice", nil, "Carol") .catchOnNil { fetchFallbackUser() } // Type is now Observable .subscribe { print($0) } .disposed(by: disposeBag) ``` -------------------------------- ### catchOnEmpty(_:) Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt When an empty occupiable element is encountered, calls the provided closure and splices the returned Observable into the stream. Available on Observable, Driver, and Signal. ```APIDOC ## catchOnEmpty(_:) ### Description Replaces empty `Occupiable` elements in an observable sequence with elements from another observable sequence. When an empty element is detected, the provided closure is executed, and the observable returned by the closure is subscribed to, effectively splicing its elements into the original stream. ### Supported Sequences - `Observable` where `T` conforms to `Occupiable` - `Driver` where `T` conforms to `Occupiable` - `Signal` where `T` conforms to `Occupiable` ### Parameters - `selector` ( () -> Observable ) - A closure that returns an `Observable` to use as a replacement when an empty element is encountered. ### Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() func fetchDefaultTags() -> Observable<[String]> { return Observable.just(["swift", "rxswift"]) } Observable<[String]> .of(["ios", "mobile"], [], ["macos"]) .catchOnEmpty { fetchDefaultTags() } .subscribe { print($0) } .disposed(by: disposeBag) // Output: // next(["ios", "mobile"]) // next(["swift", "rxswift"]) // next(["macos"]) // completed ``` ``` -------------------------------- ### filterNilKeepOptional() Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Filters out nil elements but keeps the remaining elements still wrapped in Optional. Useful for binding to observers expecting optional types. ```APIDOC ## filterNilKeepOptional() ### Description Filters out `nil` elements but keeps the remaining elements still wrapped in `Optional`. Useful when binding to a `UIBindingObserver` or `Binder` that expects an optional type. ### Method `filterNilKeepOptional()` ### Parameters None ### Request Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of("Alice", nil, "Bob") .filterNilKeepOptional() .subscribe { print($0) } .disposed(by: disposeBag) ``` ### Response #### Success Response An `Observable` with `nil` values removed, and non-nil values remaining as `Optional`. #### Response Example ``` next(Optional("Alice")) next(Optional("Bob")) completed ``` ``` -------------------------------- ### Catch nil optionals and return a new Observable Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md The `catchOnNil` operator allows you to handle nil values within an Observable sequence by returning a new Observable sequence. This is useful for providing alternative data when a nil is encountered. ```swift Observable .of("One", nil, "Three") .catchOnNil { return Observable.just("A String from a new Observable") } // Type is now Observable .subscribe { print($0) } ``` -------------------------------- ### Replace nil elements with a default value Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Utilize `replaceNilWith(_:)` to substitute any nil elements in an observable stream with a specified default value. The resulting stream will contain non-optional values. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of(1, nil, 3, nil, 5) .replaceNilWith(0) // Stream is now Observable .subscribe { print($0) } .disposed(by: disposeBag) ``` -------------------------------- ### Catch empty Occupiable types and return a new Observable Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Use `catchOnEmpty` to handle empty Occupiable types within an Observable sequence by providing an alternative Observable sequence. This allows for fallback behavior when empty collections or strings are encountered. ```swift Observable<[String]> .of(["Single Element"], [], ["Two", "Elements"]) .catchOnEmpty { return Observable<[String]>.just(["Not Empty"]) } .subscribe { print($0) } ``` -------------------------------- ### filterEmpty() Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Filters out any empty String, Array, Dictionary, Set, or custom Occupiable values from the stream. Available on Observable, Driver, and Signal. ```APIDOC ## filterEmpty() ### Description Filters out elements from an observable sequence that are considered 'empty'. This operator works with types conforming to the `Occupiable` protocol, such as `String`, `Array`, `Dictionary`, `Set`, and custom types that implement `isEmpty`. ### Supported Sequences - `Observable` where `T` conforms to `Occupiable` - `Driver` where `T` conforms to `Occupiable` - `Signal` where `T` conforms to `Occupiable` ### Example (Array) ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable<[String]> .of(["Alice"], [], ["Bob", "Carol"], []) .filterEmpty() .subscribe { print($0) } .disposed(by: disposeBag) // Output: // next(["Alice"]) // next(["Bob", "Carol"]) // completed ``` ### Example (String) ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of("hello", "", "world", "") .filterEmpty() .subscribe { print($0) } .disposed(by: disposeBag) // Output: // next(hello) // next(world) // completed ``` ``` -------------------------------- ### Catch on Empty Occupiable Element Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Replaces empty occupiable elements with a fallback Observable. When an empty element is encountered, it calls the provided closure and splices the returned Observable into the stream. Available on Observable, Driver, and Signal. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() func fetchDefaultTags() -> Observable<[String]> { return Observable.just(["swift", "rxswift"]) } Observable<[String]> .of(["ios", "mobile"], [], ["macos"]) .catchOnEmpty { fetchDefaultTags() } .subscribe { print($0) } .disposed(by: disposeBag) ``` -------------------------------- ### filterNil() Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Filters out any nil elements from an Observable and returns an Observable. This operator is available on Observable, Driver, and Signal. ```APIDOC ## filterNil() ### Description Filters out any `nil` elements from an `Observable` and returns an `Observable`. Available on `Observable`, `Driver`, and `Signal`. ### Method `filterNil()` ### Parameters None ### Request Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of("Alice", nil, "Bob", nil, "Carol") .filterNil() .subscribe { print($0) } .disposed(by: disposeBag) ``` ### Response #### Success Response An `Observable` with all `nil` elements removed. #### Response Example ``` next(Alice) next(Bob) next(Carol) completed ``` ``` -------------------------------- ### Terminate stream with an error on nil element Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Use `errorOnNil()` to halt the observable stream with an error whenever a nil element is encountered. This operator is not available for `Driver` or `Signal` types. You can provide a custom error or use the default `RxOptionalError.foundNilWhileUnwrappingOptional`. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of("One", nil, "Three") .errorOnNil() // Type is now Observable .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) ``` ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() // Custom error example: enum AppError: Error { case missingValue } Observable .of("One", nil, "Three") .errorOnNil(AppError.missingValue) .subscribe( onNext: { print("next:", $0) }, onError: { print("error:", $0) } ) .disposed(by: disposeBag) ``` -------------------------------- ### Error on nil optional in Observable Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Use `errorOnNil` to make an Observable sequence of optionals error out when it encounters a nil value. This operator is unavailable for `Driver` types as they cannot emit errors. It defaults to `RxOptionalError.foundNilWhileUnwrappingOptional`. ```swift Observable .of("One", nil, "Three") .errorOnNil() // Type is now Observable .subscribe { print($0) } ``` -------------------------------- ### Filter Empty Occupiable Elements Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Filters out empty String, Array, Dictionary, Set, or custom Occupiable values from a stream. Available on Observable, Driver, and Signal. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() // Array example Observable<[String]> .of(["Alice"], [], ["Bob", "Carol"], []) .filterEmpty() .subscribe { print($0) } .disposed(by: disposeBag) // String example Observable .of("hello", "", "world", "") .filterEmpty() .subscribe { print($0) } .disposed(by: disposeBag) ``` -------------------------------- ### Replace nil optionals with a default value Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md The `replaceNilWith` operator substitutes any nil values in an Observable sequence of optionals with a specified default value. The output Observable will contain only non-nil values. ```swift Observable .of("One", nil, "Three") .replaceNilWith("Two") // Type is now Observable .subscribe { print($0) } ``` -------------------------------- ### Filter nil elements while keeping Optional wrapper Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Employ `filterNilKeepOptional()` to remove nil values from an observable stream but retain the Optional wrapper for non-nil elements. This is particularly useful when binding to UI elements or binders that expect an optional type. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of("Alice", nil, "Bob") .filterNilKeepOptional() // Stream is Observable — nil removed, non-nil kept as Optional .subscribe { print($0) } .disposed(by: disposeBag) ``` -------------------------------- ### Error on empty Occupiable type in Observable Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md The `errorOnEmpty` operator causes an Observable sequence of Occupiable types to error out when it encounters an empty element. This is not available for `Driver` types. It defaults to `RxOptionalError.emptyOccupiable`. ```swift Observable<[String]> .of(["Single Element"], [], ["Two", "Elements"]) .errorOnEmpty() .subscribe { print($0) } ``` -------------------------------- ### distinctUntilChanged() Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Returns only distinct contiguous elements from an Observable, comparing wrapped values for equality. Available where T: Equatable. Available on Observable, Driver, and Signal. ```APIDOC ## distinctUntilChanged() ### Description Suppresses consecutive duplicate optionals in an observable sequence. It compares the wrapped values for equality, meaning `T` must conform to `Equatable`. ### Supported Sequences - `Observable` - `Driver` - `Signal` ### Example ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of(5, 6, 6, nil, nil, 3) .distinctUntilChanged() .subscribe { print($0) } .disposed(by: disposeBag) // Output: // next(Optional(5)) // next(Optional(6)) // next(nil) // next(Optional(3)) // completed ``` ``` -------------------------------- ### Distinct until changed for optional values Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Apply `distinctUntilChanged` to an Observable sequence of optionals to filter out consecutive duplicate values, including consecutive nils. Each unique value, including the first occurrence of nil after non-nil values, will be emitted. ```swift Observable .of(5, 6, 6, nil, nil, 3) .distinctUntilChanged() .subscribe { print($0) } ``` -------------------------------- ### Distinct Until Changed for Optionals Source: https://context7.com/rxswiftcommunity/rxoptional/llms.txt Suppresses consecutive duplicate optionals in a stream. Compares wrapped values for equality, requiring T to be Equatable. Works with Observable, Driver, and Signal. ```swift import RxSwift import RxOptional let disposeBag = DisposeBag() Observable .of(5, 6, 6, nil, nil, 3) .distinctUntilChanged() .subscribe { print($0) } .disposed(by: disposeBag) ``` -------------------------------- ### Filter out empty Occupiable types from Observable Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Use `filterEmpty` to remove elements from an Observable sequence that are empty 'Occupiable' types (like empty Strings, Arrays, Dictionaries, or Sets). The resulting Observable will only contain non-empty occupiable elements. ```swift Observable<[String]> .of(["Single Element"], [], ["Two", "Elements"]) .filterEmpty() .subscribe { print($0) } ``` -------------------------------- ### Filter out nil optionals from Observable Source: https://github.com/rxswiftcommunity/rxoptional/blob/main/README.md Use `filterNil` to remove all nil values from an Observable sequence of optionals. The resulting Observable will only contain non-nil values, with its type parameter updated accordingly. ```swift Observable .of("One", nil, "Three") .filterNil() // Type is now Observable .subscribe { print($0) } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.