Header Reference: <optional>

The main type, operations, and usage patterns around std::optional and optional-style APIs.

How to use this reference page

Use reference pages to confirm names, categories, nearby facilities, and the constraints that matter before writing or reviewing code.

Scan the top of the page first to identify the primary types, functions, or algorithm families involved.

Use the nearby-page links when your question is really about a companion header, related algorithm family, or broader subsystem.

Validate tricky behavior with a small compileable example before relying on memory for details like invalidation, ordering, allocation, or lifetime rules.

What header pages are for

Header reference pages are meant to answer a practical question quickly: what this header provides, when to reach for it, and which usage rules are easiest to get wrong.

Start here when you already know roughly which header you need but want a fast operational summary.

Use the example section below as a minimal pattern, then adapt it to your real container, ownership, text, or concurrency workflow.

Jump to broader index pages when you need exhaustive coverage rather than a header-focused summary.

Header Reference: `<optional>`

Main type

std::optional<T>

What it provides

a value that may or may not be present
explicit absence via std::nullopt
helper access operations such as has_value(), value(), and value_or()

When to use it

when absence is normal and there is no detailed error payload
when you want a lightweight alternative to sentinel values

When not to use it

when you need a structured error reason: prefer std::expected
when multiple alternative result shapes are valid: prefer std::variant

Small worked example

#include <optional>
#include <string_view>

std::optional<int> parse_count(std::string_view text) {
	if (text.empty()) {
		return std::nullopt;
	}
	return 3;
}

This is the right optional shape: either a meaningful value is present or it is not. There is no richer failure payload, and callers can branch on presence directly.

Selection guide

use std::optional<T> when absence is ordinary and no detailed error reason is needed
use value_or() for simple fallback behavior and has_value() or if (opt) for branching
switch to std::expected<T, E> when callers need to know why the value is absent

Nearby pages

What to verify before relying on this header

Whether the type models ownership, borrowing, type erasure, value transport, or a compile-time constraint.

Which operations are constant time versus potentially allocating, dispatching, or instantiating more template machinery than expected.

How the facility composes with nearby headers like ``, ``, ``, or ``.

Header Reference: <optional>

How to use this reference page

What header pages are for

Header Reference: <optional>

Main type

What it provides

When to use it

When not to use it

Small worked example

Selection guide

Nearby pages

Minimal example

What to verify before relying on this header

Header Reference: `<optional>`