rust

Files (1)

• SKILL.md

SKILL.md (first lines)

# Rust Language Idioms

Work _with_ the language, not against it. Embrace ownership, the borrow checker, and the type system.

---

## Core Values

- **Safety:** Lean on the compiler's guarantees. Avoid `unsafe` unless absolutely necessary.
- **Memory Efficiency:** Zero-cost abstractions. Avoid unnecessary allocations.
- **Ergonomics:** APIs should be intuitive and hard to misuse.

---

## API Design

### Naming Conventions

| Prefix  | Semantics                    | Cost      | Example                       |
| :------ | :--------------------------- | :-------- | :---------------------------- |
| `as_`   | Borrowed view, no allocation | Cheap     | `as_ref()`, `as_slice()`      |
| `to_`   | Creates new owned value      | Expensive | `to_string()`, `to_vec()`     |
| `into_` | Consumes self, transforms    | Cheap     | `into_iter()`, `into_inner()` |

### Argument Flexibility

Accept generic bounds instead of concrete types:

```rust
// ❌ Inflexible
fn read_file(path: &PathBuf) -> Result<String>

// ✅ Accepts &str, String, PathBuf, &Path
fn read_file(path: impl AsRef<Path>) -> Result<String>
```

Common patterns:

- `impl AsRef<Path>` — for paths
- `impl AsRef<str>` — for string-like types
- `impl Into<String>` — when ownership is needed

### Constructors

- **Simple:** `T::new()` for basic instantiation
- **Configured:** `T::with_capacity(n)` for single-option variants
- **Complex:** Use the **Builder pattern** for 3+ optional fields

```rust
let config = ConfigBuilder::new()
    .port(8080)
    .timeout(Duration::from_secs(30))
    .build()?;
```

### Monomorphization Control

For widely-used generic functions, consider splitting:

```rust
// Public generic wrapper (thin)
pub fn process(path: impl AsRef<Path>) -> Result<()> {
    process_inner(path.as_ref())
}

// Private concrete implementation (bulk of logic)
fn process_inner(path: &Path) -> Result<()> {
    // ...
}
```

This reduces binary bloat and compile times.

---

## Error Handling

### The `?` Operator

Use `?` to propagate errors. It:

1. Unwraps `Ok(value)` or returns `Err(e)` early
2. Automatically converts via `From` trait

### Library vs. Application Errors

| Context          | Approach                  | Crate       |
| :--------------- | :------------------------ | :---------- |
| **Libraries**    | Custom enum error types   | `thiserror` |
| **Applications** | Boxed errors with context | `anyhow`    |

```rust
// Library: structured, matchable errors
#[derive(Debug, thiserror::Error)]
pub enum ParseError {
    #[error("invalid header at byte {0}")]
    InvalidHeader(usize),
    #[error("unexpected EOF")]
    UnexpectedEof,
}

// Application: rich context chains
fn main() -> anyhow::Result<()> {
    let config = load_config()
        .context("failed to load configuration")?;
    Ok(())
}
```

### Parse, Don't Validate

Encode invariants in the type system:

```rust
// ❌ Stringly-typed, requires repeated validation
fn send_email(to: &str) -> Result<()>

// ✅ Invalid states are unrepresentable
fn send_email(to: EmailAddress) -> Result<()>

From nrdxp/predicate, MIT.

More from nrdxp/predicate