pencil-box 0.1.5

A versatile Rust utility library, inspired by JavaScript's Lodash, providing common helper functions for collections, strings, numbers, and more, with no external dependencies.
Documentation

Pencil-Box

A simple and efficient Rust utility for:

  • 📦 Splitting slices into fixed-size chunks with chunk

  • 🔁 Removing duplicate elements from vectors with uniq and uniq_performant

  • 🗑️ Removing "empty" elements from vectors with compact

📦 Installation

Add this to your Cargo.toml:

[dependencies]
pencil-box = "0.1.4"

Replace "0.1.4" with the latest version from crates.io

🚀 Usage

✂️ Chunking Slices

use pencil_box::chunk;

fn main() {
    let data = vec![1, 2, 3, 4, 5];
    let result = chunk(&data, 2).unwrap();
    assert_eq!(result, vec![vec![1, 2], vec![3, 4], vec![5]]);
}

chunk Function Behavior

pub fn chunk<T: Clone>(array: &[T], chunk_size: usize) -> Result<Vec<Vec<T>>, &'static str>

  • ✅ Returns an error if chunk_size == 0

  • ✅ Returns an empty vector if the input slice is empty

  • ✅ Returns a single chunk if chunk_size >= array.len()

  • ✅ Returns multiple chunks of up to chunk_size elements otherwise

Each chunk is cloned into an owned Vec<T>.

🧹 Deduplicating Vectors

use pencil_box::{uniq, uniq_performant};

fn main() {
    let mut items = vec![1, 2, 2, 3, 1];
    uniq(&mut items); // or uniq_performant(&mut items);
    assert_eq!(items, vec![1, 2, 3]);
}

uniq Function Behavior

pub fn uniq<T: Eq + Hash + Clone>(values: &mut Vec<T>)

  • ✅ Uses the standard HashSet to remove duplicates in-place

  • ✅ Retains the first occurrence of each element

  • ✅ Preserves relative ordering

  • 🔁 Best for general-purpose use

uniq_performant Function Behavior

pub fn uniq_performant<T: Eq + Hash + Clone>(values: &mut Vec<T>)

  • 🚀 Uses AHashSet for faster hashing and performance

  • ✅ Retains the first occurrence of each element

  • ✅ Preserves relative ordering

  • ⚡ Ideal for high-throughput or performance-critical use cases

🗑️ Compacting Vectors

use pencil_box::compact; // Assuming compact is part of pencil_box

fn main() {
    let mut numbers = vec![1, 0, 2, 0, 3];
    compact(&mut numbers);
    assert_eq!(numbers, vec![1, 2, 3]);

    let mut strings = vec!["hello".to_string(), "".to_string(), "world".to_string()];
    compact(&mut strings);
    assert_eq!(strings, vec!["hello".to_string(), "world".to_string()]);
}

compact Function Behavior

pub fn compact<T: IsEmpty>(values: &mut Vec<T>)

  • 🗑️ Removes elements from a mutable vector that are considered "empty"

  • ✅ Modifies the vector in-place

  • ✅ Relies on the IsEmpty trait to determine emptiness

  • Supported types for IsEmpty include String, &str, Vec<T>, bool, all integer types (i8, u8, etc.), all float types (f32, f64), and Option<T>.

  • ⚡ Efficient: Uses Vec::retain() for in-place removal.

🔒 Safety

  • 100% safe Rust (#![forbid(unsafe_code)])

  • No unsafe blocks used

  • Pure functional logic

📄 License

🤝 Contributing

Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request.

🌐 Links