# Rust Patterns

Prescriptive patterns for writing idiomatic Rust, extracted from the
standard library source at [rust-lang/rust](https://github.com/rust-lang/rust).

## Source

All patterns are extracted from the `library/` directory (the standard
library implementation) at commit
[`f53b654`](https://github.com/rust-lang/rust/tree/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6)
(325,000 commits, 8,021 contributors).

## Pattern Files

| File | Patterns | Lines | Key Topics |
|------|----------|-------|------------|
| [error-handling.md](patterns/error-handling.md) | 10 | 702 | Result, ?, Error trait, From, panic! |
| [traits.md](patterns/traits.md) | 10 | 699 | Small traits, derive, From/Into, Iterator, Deref |
| [ownership.md](patterns/ownership.md) | 10 | 677 | Borrowing, Clone/Copy, Cow, Arc, Drop, lifetimes |
| [documentation.md](patterns/documentation.md) | 10 | 723 | Doc comments, # Safety, # Examples, doc tests |
| [concurrency.md](patterns/concurrency.md) | 10 | 723 | Send/Sync, Mutex, atomics, channels, scoped threads |
| [testing.md](patterns/testing.md) | 10 | 664 | cfg(test), assert_eq!, should_panic, property tests |
| [unsafe-patterns.md](patterns/unsafe-patterns.md) | 10 | 624 | // SAFETY:, unsafe fn, MaybeUninit, FFI |
| [api-design.md](patterns/api-design.md) | 10 | 596 | Naming, #[non_exhaustive], newtype, typestate |
| [module-organization.md](patterns/module-organization.md) | 10 | 514 | File structure, pub use, prelude, workspaces |
| [macros.md](patterns/macros.md) | 10 | 519 | macro_rules!, derive, attribute macros, hygiene |

**Total: 100 patterns across 10 files, 6,441 lines.**

## Discovery Data (from library/)

| Category | Metric | Count |
|----------|--------|-------|
| Error Handling | `?` operator usages | 4,702 |
| Error Handling | `Result<>` types | 4,059 |
| Error Handling | `From<>` impls | 508 |
| Traits | Public traits | 241 |
| Traits | Trait implementations | 4,387 |
| Traits | Iterator impls | 895 |
| Ownership | `&mut` references | 7,909 |
| Ownership | Rc/Arc usages | 798 |
| Ownership | Cow<> usages | 197 |
| Documentation | Doc comments (///) | 133,741 |
| Documentation | # Examples sections | 3,912 |
| Documentation | # Safety sections | 2,864 |
| Concurrency | Atomic types | 783 |
| Concurrency | Send/Sync markers | 274 |
| Testing | #[test] functions | 4,136 |
| Testing | Assert macros | 16,728 |
| Unsafe | Unsafe blocks | 31,244 |
| Unsafe | // SAFETY: comments | 2,463 |
| API Design | pub fn | 18,430 |
| API Design | pub(crate) | 919 |
| Macros | macro_rules! | 607 |
| Macros | #[derive(...)] | 1,116 |

## Each Pattern Includes

- **Source hyperlink** — permalink to the exact source location
- **Before/After code** — concrete transformation showing improvement
- **When to Use** — trigger conditions (when this pattern applies)
- **When NOT to Use** — over-application warning with code example
- **Decision tree** — at the end of each file for quick reference

## How to Use This Repo

1. **Learning Rust**: Read patterns in order of importance:
   error-handling → ownership → traits → concurrency
2. **Code review**: Reference specific patterns when reviewing Rust PRs
3. **Teaching**: Use before/after pairs as exercises
4. **Writing new code**: Check the decision tree before choosing an approach

## Related Repos

- [rodin/go-patterns](https://gitea.weiker.me/rodin/go-patterns) — Go patterns from stdlib
- [rodin/elixir-patterns](https://gitea.weiker.me/rodin/elixir-patterns) — Elixir patterns from stdlib
- [rodin/codebase-analysis](https://gitea.weiker.me/rodin/codebase-analysis) — The skill that produces these repos

## License

This repository contains analysis and patterns derived from
rust-lang/rust (MIT/Apache-2.0 dual licensed).