Error States & Result Types - Learning Module

Loading content...

0/246

Option/Maybe Type Pattern

When Nothing is Something

Tony Hoare, inventor of the null reference, called it his "billion-dollar mistake." The problem isn't that we sometimes need to represent the absence of a value — it's that null can appear anywhere without warning, causing unexpected crashes at the worst possible times.

The Option type (also called Maybe, Optional, or nullable types) is the principled solution. It explicitly represents that a value might not exist, forcing code to acknowledge and handle that possibility. Unlike null, which silently lurks in any reference type, Option makes absence visible in the type system.

This page provides a comprehensive exploration of Option types: their relationship to Result types, the complete API surface, idiomatic usage patterns, and their role in modern language design.

What You Will Learn

By the end of this page, you will understand: when to use Option vs Result; the complete Option API (map, flatMap, filter, etc.); how to chain operations on optional values elegantly; the relationship between Option and null-safety; patterns for working with collections of Options; and how Option types integrate with modern language features.

Understanding Option Types

An Option type is a container that either holds exactly one value (Some/Just) or holds nothing (None/Nothing). It's semantically distinct from Result:

Result<T, E> — Operation succeeded with T, or failed with error E
Option<T> — Value T exists, or there's simply nothing (no value, not an error)

The key insight: absence of value is not the same as failure. Looking up a key in a dictionary might return nothing — that's not an error, it's just an empty result. An Option captures this semantic perfectly.

option_type_definitions
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
// Rust's Option type (from std::option)
pub enum Option<T> {
    Some(T),  // Contains a value
    None,     // No value
}
 
// Usage examples
fn find_user_by_email(email: &str) -> Option<User> {
    // Returns Some(user) if found, None if not
    users.iter().find(|u| u.email == email).cloned()
}
 
fn main() {
    let maybe_user = find_user_by_email("alice@example.com");
    
    // Pattern matching forces handling both cases
    match maybe_user {
        Some(user) => println!("Found: {}", user.name),
        None => println!("User not found"),
    }
    
    // if let for when you only care about Some
    if let Some(user) = find_user_by_email("bob@example.com") {
        send_notification(&user);
    }
}

Option vs Nullable Types

Modern languages like Kotlin and Swift use nullable types (T?) which are essentially Options with syntax support. The key is that nullability is explicit in the type — you can't accidentally pass null where a non-null value is expected. TypeScript with strictNullChecks achieves similar safety.

Option vs Result — When to Use Which

Option and Result serve different semantic purposes. Choosing the right one communicates intent and enables appropriate handling:

Use Option when:

Absence is a normal, expected outcome (not an error)
There's only one way for there to be "nothing"
The caller doesn't need to know why there's no value

Use Result when:

Absence represents a failure that should be explained
There are multiple different error conditions
The caller needs context to handle the failure appropriately

Option vs Result: Semantic Comparison
Scenario	Option<T>	Result<T, E>	Recommended
Look up user by ID	User might not exist	Could be DB error, not found, connection issue	Result — distinguishes not found from DB failure
Get first element of list	List might be empty	—	Option — empty list isn't an error
Parse integer from string	—	Input might not be a valid integer	Result — caller needs to know why parsing failed
Find element matching predicate	No matching element	—	Option — no match is a valid outcome
Read configuration value	Value might not be set	File missing, parse error, permission denied	Result — multiple failure modes need distinction
Get parent of tree node	Root has no parent	—	Option — root having no parent is expected
HTTP request	—	Network error, timeout, status code errors	Result — rich failure information needed
Cache lookup	Cache miss	—	Option — miss is expected, not an error

option_vs_result_examples
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
// Option: when absence is expected, not an error
fn find_in_cache(&self, key: &str) -> Option<&CacheEntry> {
    self.entries.get(key)  // Cache miss is normal
}
 
fn first(&self) -> Option<&T> {
    self.items.get(0)  // Empty collection is valid
}
 
fn find_matching(&self, predicate: impl Fn(&T) -> bool) -> Option<&T> {
    self.items.iter().find(|x| predicate(x))  // No match is fine
}
 
// Result: when absence is a failure requiring explanation
fn load_user(&self, id: UserId) -> Result<User, LoadUserError> {
    // We need to distinguish: not found vs db error vs permission error
    let row = self.db.query_one(/* ... */)
        .map_err(|e| match e {
            DbError::NotFound => LoadUserError::NotFound(id),
            DbError::Connection(c) => LoadUserError::Database(c),
            DbError::Permission => LoadUserError::Unauthorized,
        })?;
    
    Ok(User::from_row(row))
}
 
fn parse_config(&self, path: &Path) -> Result<Config, ConfigError> {
    // Multiple failure modes that caller must handle differently
    let contents = fs::read_to_string(path)
        .map_err(|e| ConfigError::IoError(path.to_owned(), e))?;
    
    let config: Config = serde_json::from_str(&contents)
        .map_err(|e| ConfigError::ParseError(e))?;
    
    self.validate(&config)?;
    
    Ok(config)
}
 
// Converting between Option and Result
fn get_required_config(&self, key: &str) -> Result<String, ConfigError> {
    self.get_optional_config(key)  // Returns Option<String>
        .ok_or_else(|| ConfigError::MissingKey(key.to_string()))
}
 
fn try_get_user(&self, id: UserId) -> Option<User> {
    self.load_user(id).ok()  // Discard error info, just get Option
}

Don't Lose Information

Converting Result to Option loses error information. Only do this when you genuinely don't care why an operation failed. If you find yourself frequently converting Result→Option, consider whether your original operation should return Option instead, or whether you're inappropriately discarding errors.

The Option API Surface

Like Result, Option types come with a rich API for transformation, combination, and extraction. Many operations mirror Result, but there are Option-specific operations too.

option_transformation
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
// map() - transform the inner value if present
let x: Option<i32> = Some(5);
let doubled: Option<i32> = x.map(|n| n * 2);  // Some(10)
 
let y: Option<i32> = None;
let still_none: Option<i32> = y.map(|n| n * 2);  // None
 
// map_or() - transform with default
let value: i32 = Some(5).map_or(0, |n| n * 2);  // 10
let default: i32 = None.map_or(0, |n: i32| n * 2);  // 0
 
// map_or_else() - transform with lazy default
let value: i32 = opt.map_or_else(
    || compute_default(),  // Only called if None
    |n| n * 2              // Only called if Some
);
 
// filter() - convert Some to None based on predicate
let x: Option<i32> = Some(5);
let filtered = x.filter(|n| *n > 3);  // Some(5)
let filtered2 = x.filter(|n| *n > 10);  // None
 
// inspect() - peek at value for side effects
opt.inspect(|v| println!("Value is: {}", v))
   .map(|v| v * 2);

Options in Collections

Working with collections of Option values (or operations that produce Options) requires special patterns. Common scenarios include:

Filtering out None values from a collection
Transforming elements where some might fail
Collecting results where any None should fail the whole operation
Finding the first Some in a collection

options_in_collections
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
// Filtering Nones with filter_map
let strings = vec!["1", "two", "3", "four", "5"];
let numbers: Vec<i32> = strings
    .iter()
    .filter_map(|s| s.parse::<i32>().ok())  // Parse, keep only successful
    .collect();
// numbers = [1, 3, 5]
 
// Same with .flatten() after map
let numbers: Vec<i32> = strings
    .iter()
    .map(|s| s.parse::<i32>().ok())  // Iterator<Item = Option<i32>>
    .flatten()                         // Iterator<Item = i32>
    .collect();
 
// Collecting where ANY None fails the whole thing
let strings = vec!["1", "2", "3"];
let all_numbers: Option<Vec<i32>> = strings
    .iter()
    .map(|s| s.parse::<i32>().ok())
    .collect();  // Returns None if any parse fails
// all_numbers = Some([1, 2, 3])
 
let strings = vec!["1", "oops", "3"];
let all_numbers: Option<Vec<i32>> = strings
    .iter()
    .map(|s| s.parse::<i32>().ok())
    .collect();
// all_numbers = None (because "oops" failed)
 
// Finding first Some
let attempts = vec![
    try_server_a(),  // Option<Connection>
    try_server_b(),
    try_server_c(),
];
let connection: Option<Connection> = attempts.into_iter().flatten().next();
 
// Or lazily (short-circuits on first success)
let connection = try_server_a()
    .or_else(|| try_server_b())
    .or_else(|| try_server_c());
 
// Transpose: Option<Vec<T>> <-> Vec<Option<T>>
let options: Vec<Option<i32>> = vec![Some(1), Some(2), Some(3)];
let transposed: Option<Vec<i32>> = options.into_iter().collect();
// Some([1, 2, 3])

The Power of Iterator Adapters

In Rust, Option implements IntoIterator — Some(x) becomes a single-element iterator, None becomes an empty iterator. This means you can use .flatten() to filter Nones, and .collect::<Option<Vec<_>>>() to fail on any None. These patterns compose beautifully without explicit loops.

Null-Safety in Modern Languages

Modern languages have embraced null-safety as a core feature, integrating Option-like semantics directly into the type system. This eliminates null pointer exceptions at compile time rather than runtime.

Key approaches:

Nullable types (Kotlin, Swift, C#) — Types are non-null by default; T? explicitly allows null
Strict null checks (TypeScript) — strictNullChecks flag makes null/undefined trackable
No null reference (Rust) — There is no null; use Option<T> explicitly
Optional type (Java 8+) — Library-level Optional<T> for return values

Null-Safety Features by Language
Feature	Kotlin	Swift	TypeScript	Rust	Java
Non-null default	✅	✅	✅ (strict mode)	✅ (no null)	❌
Nullable syntax	T?	T?	T \| null	Option<T>	Optional<T>
Safe navigation	?.	?.	?.	N/A (use match)	.map()
Null coalescing	?:	??	??	.unwrap_or()	.orElse()
Smart casts	✅	✅	✅	Match arms	❌
Compile-time safety	Full	Full	Full	Full	Partial

null_safety_comparison
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
// Kotlin: Types are non-null by default
fun processUser(user: User) {  // user cannot be null
    println(user.name)  // Always safe
}
 
// Nullable types use ?
fun findUser(id: Long): User? {  // Might return null
    return database.findById(id)
}
 
// Compiler enforces null handling
fun greetUser(id: Long) {
    val user: User? = findUser(id)
    
    // This won't compile:
    // println(user.name)  // Error: user might be null
    
    // These work:
    println(user?.name)           // Prints null or name
    println(user?.name ?: "Guest")  // Prints name or "Guest"
    
    if (user != null) {
        println(user.name)  // Smart cast: compiler knows user is non-null here
    }
    
    user?.let { 
        println(it.name)  // user is non-null inside let block
    }
}
 
// Platform types (from Java interop) are uncertain
fun handleJavaReturn() {
    val result: String = javaMethod()  // Might crash if Java returns null!
    val safe: String? = javaMethod()   // Treat as nullable to be safe
}

Common Pitfalls and Anti-patterns

Even with Option types, there are patterns that undermine their benefits. Learning to recognize and avoid these pitfalls is essential for effective use.

Anti-patterns to Avoid

•Blind unwrapping — Using unwrap() or ! without knowing the value is present
•Option of Option — Option<Option<T>> usually indicates modeling confusion
•Option for errors — Using None to mean 'failed' when you should use Result
•Sentinel values via Option — Using Some(sentinel) instead of proper modeling
•Immediately unwrapping — Getting an Option just to unwrap it immediately
•Ignoring None — Silently dropping None cases without explicit handling

Better Alternatives

•Pattern match or use combinators — Use map, and_then, unwrap_or to handle None
•Flatten or redesign — Use .flatten() or reconsider the data model
•Use Result — If None means failure, Result<T, E> is more appropriate
•Use enums — Custom enums can express states more precisely than Option
•Compose earlier — Use combinators to work with the Option throughout
•Make handling explicit — Use match, if-let, or combinators for visible handling

option_antipatterns
Rust
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
// ❌ Anti-pattern: Blind unwrap
fn get_config_value(key: &str) -> String {
    config.get(key).unwrap()  // Will panic if key missing!
}
 
// ✅ Better: Handle the None case
fn get_config_value(key: &str) -> String {
    config.get(key)
        .cloned()
        .unwrap_or_else(|| format!("default_for_{}", key))
}
 
// ❌ Anti-pattern: Option<Option<T>>
struct User {
    // What does None mean? No preference? Or preference is "no favorite"?
    favorite_color: Option<Option<Color>>,
}
 
// ✅ Better: Model the states explicitly
enum ColorPreference {
    Unknown,      // We don't know their preference
    NoFavorite,   // They explicitly have no favorite
    Favorite(Color),  // They have a favorite
}
 
// ❌ Anti-pattern: Using None as error
fn parse_number(s: &str) -> Option<i32> {
    s.parse().ok()  // Loses all error information
}
 
// ✅ Better: Use Result when failure has meaning
fn parse_number(s: &str) -> Result<i32, ParseError> {
    s.parse().map_err(|_| ParseError::InvalidNumber(s.to_string()))
}
 
// ❌ Anti-pattern: Immediately unwrapping
let user = find_user(id);
if user.is_some() {
    let u = user.unwrap();  // Wasteful check + unwrap
    process(u);
}
 
// ✅ Better: Use pattern matching
if let Some(user) = find_user(id) {
    process(user);
}

The Option<Option<T>> Smell

If you find yourself with Option<Option<T>>, stop and reconsider your data model. Usually this means you're conflating two different concepts of 'nothing'. Create an enum that explicitly models all the states instead.

Options as First-Class Values

One of the most powerful aspects of Option types is that they're just values. Unlike null references that require special handling, Options can be:

Stored in data structures
Passed as function arguments
Returned from functions
Composed with other Options
Used as keys (if hashable) or values in maps

This enables patterns impossible with null references:

first_class_options
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
// Options in data structures
struct SearchQuery {
    term: String,
    category: Option<Category>,      // Optional filter
    min_price: Option<Money>,
    max_price: Option<Money>,
    sort_by: Option<SortField>,
}
 
impl SearchQuery {
    fn apply_filters(&self, items: Vec<Item>) -> Vec<Item> {
        items.into_iter()
            .filter(|item| {
                self.category
                    .as_ref()
                    .map_or(true, |cat| item.category == *cat)
            })
            .filter(|item| {
                self.min_price
                    .as_ref()
                    .map_or(true, |min| item.price >= *min)
            })
            .filter(|item| {
                self.max_price
                    .as_ref()
                    .map_or(true, |max| item.price <= *max)
            })
            .collect()
    }
}
 
// Options as function parameters for optional behavior
fn connect(
    host: &str, 
    port: u16, 
    timeout: Option<Duration>,   // Optional timeout
    certificate: Option<&Path>,  // Optional client cert
) -> Result<Connection, Error> {
    let mut builder = ConnectionBuilder::new(host, port);
    
    if let Some(t) = timeout {
        builder = builder.timeout(t);
    }
    
    if let Some(cert) = certificate {
        builder = builder.with_cert(cert)?;
    }
    
    builder.connect()
}
 
// Option zip — combine two Options
let name: Option<String> = Some("Alice".to_string());
let age: Option<u32> = Some(30);
 
let combined: Option<(String, u32)> = name.zip(age);
// Some(("Alice", 30))
 
// If either is None, result is None
let name: Option<String> = Some("Bob".to_string());
let age: Option<u32> = None;
let combined = name.zip(age);  // None

Summary: Mastering Option Types

Option types are the principled solution to the "billion-dollar mistake" of null references. By making absence explicit in the type system, they eliminate entire categories of runtime errors while enabling clean, composable code.

Key Takeaways

•Option represents potential absence, not failure — Use Option when 'nothing' is a valid, expected outcome, not an error condition.
•Option vs Result is semantic — Option: absence without explanation. Result: failure with explanation. Choose based on what the caller needs.
•Rich API enables composition — map, flatMap/and_then, filter, unwrap_or, and other combinators allow elegant transformation chains.
•Options compose with collections — filter_map, flatten, and collect enable powerful patterns with collections of optional values.
•Modern languages embrace null-safety — Nullable types (T?), strict null checks, and safe navigation operators bring Option semantics into language syntax.
•Avoid Option anti-patterns — Don't blind-unwrap, don't use Option<Option<T>>, and don't use None to mean an error occurred.
•Options are first-class values — Store them, pass them, return them, and compose them just like any other value.

What's next:

We've now covered both Result and Option types — the two fundamental building blocks of value-based error handling. The final piece is knowing when to use result types versus exceptions, and how to design APIs that choose the right approach. That's the focus of our concluding page.

Option Types Mastered

You now understand Option types as the type-safe replacement for nullable references. You can work with Options fluently using combinators, compose them with collections, leverage null-safety features in your language of choice, and avoid common pitfalls that undermine their benefits.