---

---

        ....                               ...                               .                  s    
    .x~X88888Hx.                       .x888888hx    :   x=~                @88>    oec :      :8    
   H8X 888888888h.      .u    .       d88888888888hxx   88x.   .e.   .e.    %8P    @88888     .88    
  8888:`*888888888:   .d88B :@8c     8" ... `"*8888%`  '8888X.x888:.x888     .     8"*88%    :888ooo 
  88888:        `%8  ="8888f8888r   !  "   ` .xnxx.     `8888  888X '888k  .@88u   8b.     -*8888888 
. `88888          ?>   4888>'88"    X X   .H8888888%:    X888  888X  888X ''888E` u888888>   8888    
`. ?888%           X   4888> '      X 'hn8888888*"   >   X888  888X  888X   888E   8888R     8888    
  ~*??.            >   4888>        X: `*88888%`     !   X888  888X  888X   888E   8888P     8888    
 .x88888h.        <   .d888L .+     '8h.. ``     ..x8>  .X888  888X. 888~   888E   *888>    .8888Lu= 
:"""8888888x..  .x    ^"8888*"       `88888888888888f   `%88%``"*888Y"      888&   4888     ^%888*   
`    `*888888888"        "Y"          '%8888888888*"      `~     `"         R888"  '888       'Y"    
        ""***""                          ^"****""`                           ""     88R              
                                                                                    88>              
                                                                                    48               
                                                                                    '8               

Overview

Or is a lightweight Swift package for handling Optional values with clear, predictable defaults.

Instead of repeating nil checks and fallback operators throughout your code, Or provides a small set of focused helpers such as .orEmpty, .orZero, .orTrue, and .orFalse. This reduces boilerplate, keeps call sites readable, and makes fallback intent obvious during code review.

Or is designed for fast adoption, consistent team usage, and practical day-to-day development in reactive, declarative, and traditional Swift codebases.

Features

• 🚀 Developer-friendly Optional defaults with a small, intuitive API
• 🎯 Type-safe extensions for common Swift types
• 🧪 Drop-in adoption with minimal refactoring
• 🛠️ Compiler-friendly inlining annotations on key accessors
• 📝 Comprehensive test coverage for reliability
• 🛟 Flexible fallback handling via .or(value) and Or.this(optional:default:)

Supported Types

String Types

• String and Substring via StringProtocol
• Property: .orEmpty - Returns empty string for nil values

Boolean Type

• Bool type support
• Properties: .orTrue and .orFalse - Returns respective boolean defaults

Numeric Types

All Numeric protocol conforming types:

• Int, Int8, Int16, Int32, Int64, Int128
• UInt, UInt8, UInt16, UInt32, UInt64, UInt128
• Double, Float, Float16, Float80
• Property: .orZero - Returns .zero for nil values

Collection Types

• Array, Set, Dictionary
• Property: .orEmpty - Returns appropriate empty collection for nil values

Custom Types

• Generic .or(_:) method for any type
• Static Or.this(optional:default:) method for explicit handling

Requirements

• Swift Tools 5.10

Installation

Swift Package Manager

Add OrSwift to your project by adding the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/gchriswill/OrSwift.git", from: "1.0.1")
]

Or add it through Xcode:

1. Go to File → Add Package Dependencies
2. Enter the repository URL: https://github.com/gchriswill/OrSwift.git
3. Click Add Package

Usage

Import the Library

import Or

Basic Usage Examples

String Handling

let optionalName: String? = nil
let displayName = optionalName.orEmpty  // Returns ""

let optionalTitle: String? = "Hello World"
let title = optionalTitle.orEmpty       // Returns "Hello World"

Boolean Handling

let optionalFlag: Bool? = nil
let isEnabled = optionalFlag.orTrue     // Returns true
let isDisabled = optionalFlag.orFalse   // Returns false

Numeric Handling

let optionalCount: Int? = nil
let count = optionalCount.orZero        // Returns 0

let optionalPrice: Double? = nil
let price = optionalPrice.orZero        // Returns 0.0

Collection Handling

let optionalArray: [String]? = nil
let items = optionalArray.orEmpty       // Returns []

let optionalDict: [String: Int]? = nil
let dict = optionalDict.orEmpty         // Returns [:]

let optionalSet: Set<String>? = nil
let set = optionalSet.orEmpty           // Returns Set<String>()

Custom Types with Generic Methods

struct User {
    let name: String
}

let optionalUser: User? = nil
let defaultUser = User(name: "Guest")

// Using the .or() method
let user = optionalUser.or(defaultUser)

// Using the static Or.this() method
let user2 = Or.this(optional: optionalUser, default: defaultUser)

Advanced Usage

Chaining Operations

let optionalNames: [String]? = nil
let firstNameLength = optionalNames?.first.orEmpty.count
// Returns 0 (first element → nil empty string → count of 0)

In Reactive/Declarative Contexts

// SwiftUI example
struct ContentView: View {
    @State private var optionalText: String? = nil
    
    var body: some View {
        Text(optionalText.orEmpty)
            .foregroundColor(optionalText != nil ? .primary : .secondary)
    }
}

// Combine example
publisher
    .map { $0.optionalValue.orZero }
    .sink { value in
        print("Received: \(value)")
    }

Reference

Constants

OrNameArt

Very cool ASCII art banner string exported by the package.

public let OrNameArt: String

Types

Or

Utility namespace type that exposes: Or.this(optional:default:)

public final class Or: Thisable

Protocols

Orable

Returns the wrapped value when present, otherwise the provided fallback.

public protocol Orable {
    func or<T>(_ value: T) -> T
}

Thisable

Returns the optional value when present, otherwise the provided default.

public protocol Thisable {
    static func this<T>(optional: T?, default defaultValue: T) -> T
}

Extensions

Optional where Wrapped: StringProtocol

• var orEmpty: Wrapped { get }

Optional where Wrapped == Bool

• var orTrue: Wrapped { get }
• var orFalse: Wrapped { get }

Optional where Wrapped: Numeric

• var orZero: Wrapped { get }

Optional where Wrapped: Collection

• var orEmpty: Wrapped { get }

Contributing

Contributions are welcome!
Please feel free to submit a Pull Request with your changes including matching unit-testing coverage and technical documentation.
For major changes, please open an issue first to discuss what you would like to change.

License

This project is available under the MIT license. See the LICENSE file for more info.

Attributions

• ASCII Art from https://patorjk.com/software/taag/#p=display&f=Fraktur&t=Or%20Swift%0A