Clippy lint · Pedantic · checked with Clippy 0.1.99

clippy::ref_option: Warns when a function signature uses &Option<T> instead of Option<&T>

What it meansWarns when a function signature uses &Option<T> instead of Option<&T>. It is in the pedantic group and off by default.

Does it matter?

More flexibility, better memory optimization, and more idiomatic Rust code. &Option<T> in a function signature breaks encapsulation because the caller must own T and move it into an Option to call with it. When returned, the owner must internally store it as Option<T> in order to return it. At a lower level, &Option<T> points to memory with the presence bit flag plus the T value, whereas Option<&T> is usually optimized to a single pointer, so it may be more optimal. See this YouTube video by Logan Smith for an in-depth explanation of why this is important.

Stricter lints with some false positives. Off by default; opt in with clippy::pedantic.

How to fix it

Clippy does not fix this one automatically. Change the code by hand:

Flagged

// caller uses  foo(&opt)
fn foo(a: &Option<String>) {}
fn bar(&self) -> &Option<String> { &None }

Write this instead

// caller should use  `foo1(opt.as_ref())`
fn foo1(a: Option<&String>) {}
// better yet, use string slice  `foo2(opt.as_deref())`
fn foo2(a: Option<&str>) {}
fn bar(&self) -> Option<&String> { None }

Turn it off, or on

It is off by default. To use it, set it to warn or deny:

Whole crate (Cargo.toml)

[lints.clippy]
ref_option = "warn"

In code

#![warn(clippy::ref_option)]

One run

cargo clippy -- -W clippy::ref-option

The [lints] table needs Rust 1.74 or newer. In a workspace, put it under [workspace.lints.clippy] and add [lints] workspace = true to each member.

Settings in clippy.toml

avoid-breaking-exported-api: Suppress lints whenever the suggested change would cause breakage for other crates.

Pedanticgroup

allowdefault level

nofixed by cargo clippy --fix

1.83.0added in Rust

Clippy's own documentation

What it does

Warns when a function signature uses &Option<T> instead of Option<&T>.

Why is this bad?

More flexibility, better memory optimization, and more idiomatic Rust code.

&Option<T> in a function signature breaks encapsulation because the caller must own T and move it into an Option to call with it. When returned, the owner must internally store it as Option<T> in order to return it. At a lower level, &Option<T> points to memory with the presence bit flag plus the T value, whereas Option<&T> is usually optimized to a single pointer, so it may be more optimal.

See this YouTube video by Logan Smith for an in-depth explanation of why this is important.

Known problems

This lint recommends changing the function signatures, but it cannot automatically change the function calls or the function implementations.

Example

// caller uses  foo(&opt)
fn foo(a: &Option<String>) {}
fn bar(&self) -> &Option<String> { &None }

Use instead:

// caller should use  `foo1(opt.as_ref())`
fn foo1(a: Option<&String>) {}
// better yet, use string slice  `foo2(opt.as_deref())`
fn foo2(a: Option<&str>) {}
fn bar(&self) -> Option<&String> { None }

Configuration

avoid-breaking-exported-api: Suppress lints whenever the suggested change would cause breakage for other crates.

(default: true)

From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.

Up next

Also worth your time

Did this answer your question?