heuristics 0.1.0

Rules of thumb to improve Rust code.
Documentation

Author's bio: 👋😀 Hi, I'm CryptoPatrick! I'm currently enrolled as an Undergraduate student in Mathematics, at Chalmers & the University of Gothenburg, Sweden. If you have any questions or need more info, then please join my Discord Channel: AiMath

🛎 Important Notices

  • Curated Knowledge: Compiled rules of thumb for choosing the right data structures, algorithms, and patterns
  • Searchable Database: Quickly find relevant heuristics by keywords, crates, or categories
  • Rust-Focused: Specific recommendations for Rust crates and standard library types

🤔 What is heuristics

heuristics is a comprehensive Rust library that provides a searchable collection of computer science and Rust development heuristics. It helps developers make informed decisions about data structures, algorithms, and architectural patterns by providing curated rules of thumb with concrete recommendations.

The library enables quick discovery of the right tool for the job, whether you need O(1) lookups, persistent storage, concurrent data structures, or specialized algorithms.

Use Cases

  • Architecture Decisions: Quickly find the right data structure or pattern for your use case
  • Performance Optimization: Discover performance-oriented alternatives to common patterns
  • Learning Resource: Understand when to use different Rust crates and standard library types
  • Code Review: Reference best practices and implementation patterns
  • Rapid Prototyping: Get up to speed quickly with recommended crates for specific scenarios

📷 Features

heuristics provides a fast, searchable database of development heuristics with rich metadata and multiple access patterns.

🔧 Core Functionality

  • Heuristic Loading: Parse and load heuristics from markdown format
  • Keyword Search: Find relevant heuristics by searching keywords
  • Category Browsing: Explore heuristics by category
  • Rich Metadata: Access titles, actions, crates, standard types, and keywords

🛠 Searchable Database

  • Inverted Index: Fast keyword lookup using inverted index
  • Relevance Ranking: Results ranked by number of keyword matches
  • Partial Matching: Finds results even with partial keyword matches
  • Case-Insensitive: Search works regardless of case

📊 Categorization

  • Organized Topics: Heuristics grouped into logical categories
  • Multiple Categories: Performance, concurrency, persistence, specialized data structures, and more
  • Easy Navigation: Browse all heuristics within a specific category
  • Category Listing: Get all available categories

🔤 Rust-Specific

  • Crate Recommendations: Specific Rust crates for each use case
  • Standard Library: Links to relevant std types (HashMap, Vec, etc.)
  • Code Examples: Practical examples in Rust
  • Best Practices: Rust-specific implementation patterns

🚙 How to Use

Installation

Add heuristics to your Cargo.toml:

[dependencies]
heuristics = "0.1"

Or install with cargo:

cargo add heuristics

Basic Example

use heuristics::load_heuristics;

fn main() {
    // Load the heuristics database
    let db = load_heuristics();

    // Search for heuristics
    let results = db.search(&["hashmap", "performance"]);
    for heuristic in results.iter().take(5) {
        println!("{}", heuristic.title);
        println!("Action: {}", heuristic.action);
        if !heuristic.crates.is_empty() {
            println!("Recommended crates: {}", heuristic.crates.join(", "));
        }
    }

    // Browse by category
    let categories = db.categories();
    println!("Available categories: {:?}", categories);

    // Get heuristics in a specific category
    let concurrent = db.by_category("Concurrency & Lock-Free Heuristics");
    for heuristic in concurrent {
        println!("• {}", heuristic.title);
    }

    // Get all heuristics
    println!("Total heuristics: {}", db.all().len());
}

Advanced Usage

use heuristics::*;

fn main() {
    let db = load_heuristics();

    // Search with multiple keywords for better ranking
    let results = db.search(&["concurrent", "lock-free", "atomic"]);

    for (i, h) in results.iter().enumerate() {
        println!("\n{}. {}", i + 1, h.title);
        println!("   Category: {}", h.category);
        println!("   Action: {}", h.action);

        // Show related crates
        if !h.crates.is_empty() {
            println!("   Crates:");
            for crate_name in &h.crates {
                println!("     - {}", crate_name);
            }
        }

        // Show standard library types
        if !h.std_types.is_empty() {
            println!("   Std types: {}", h.std_types.join(", "));
        }

        // Access full markdown content
        // println!("\n{}", h.content);
    }

    // Find heuristics for a specific technology
    let results = db.search(&["sled"]);
    if !results.is_empty() {
        println!("\nHeuristics mentioning 'sled':");
        for h in results {
            println!("  • {} ({})", h.title, h.category);
        }
    }
}

Command-Line Interface

The crate also includes a CLI tool:

# Install the binary
cargo install heuristics

# Search for heuristics
heuristics search hashmap lookup

# List all categories
heuristics categories

# Get heuristics in a category
heuristics category "General-Purpose Performance Heuristics"

🧪 Testing

The test suite includes comprehensive coverage of search, categorization, and data structure functionality.

# Run all tests
cargo test

# Run library tests only
cargo test --lib

# Run integration tests
cargo test --test tests

# Run with output
cargo test -- --nocapture

Test coverage includes:

  • Loading heuristics from base.md
  • Keyword search (basic, multi-keyword, case-insensitive)
  • Category listing and filtering
  • Data structure validation
  • Search ranking
  • Edge cases (no results, empty searches)

📚 Documentation

Comprehensive documentation is available at docs.rs/heuristics, including:

  • API reference for all public types and functions
  • Examples of searching and browsing heuristics
  • Heuristic data structure details
  • Performance considerations and indexing strategy

🖊 Author

CryptoPatrick

Keybase Verification: https://keybase.io/cryptopatrick/sigs/8epNh5h2FtIX1UNNmf8YQ-k33M8J-Md4LnAN

🐣 Support

Leave a ⭐ if you think this project is cool.

🗄 License

This project is licensed under MIT. See LICENSE for details.