16 releases (stable)
3.1.0 | Sep 14, 2022 |
---|---|
2.1.0 | May 24, 2021 |
2.0.0 | Feb 10, 2019 |
1.2.2 | Sep 16, 2018 |
0.2.1 | Jul 30, 2018 |
#168 in Rust patterns
156,956 downloads per month
Used in 135 crates
(11 directly)
46KB
718 lines
joinery
A Rust library for generically joining iterables with a separator. Provides the tragically missing string join functionality to rust.
extern crate joinery;
use std::env;
// Or use joinery::prelude::*;
use joinery::Joinable;
fn main() {
// Join things!
println!("{}", ["Hello", "World!"].iter().join_with(", "));
// Join things of different types!
println!("{}", ["Hello", "World!"].iter().join_with(' '));
println!("{}", (0..10).join_with(' '));
}
Installation
Add joinery to your Cargo.toml
:
[dependencies]
joinery = "2.0.0"
Nightly-only features
joinery supports various nightly-only optimization features, such as iter::TrustedLen
. These features are enabled with the "nightly"
cargo feature:
[dependencies.joinery]
version = "2.0.0"
features = ["nightly"]
Note that, because nightly-only features are unstable, joinery can't make any stability guarentees about their continued presence or interface consistency between versions. While we'll do our best to preserve compatibility, we only guarentee semver compatibility for the non-nightly interface.
Overview
Joinery provides joins over iterators. Put simply, a join is a combination of an iterator and a separator. The join then conceptually represents all the elements of the iterator, with the separator between each one.
You can create a join with the join_with
method, which is defined for all IntoIterator
types via the Joinable
trait:
use joinery::prelude::*;
let content = vec![1, 2, 3, 4, 5];
let join = content.iter().join_with(", ");
Joins implement Display
, so they can be written to writers or converted into strings. Joins are stateless, so they can be reused, assuming that the underlying iterator is cloneable:
println!("Comma-separated numbers: {}", join);
let mut result = String::new();
write!(&mut result, "{}", join);
// Don't forget that `Display` gives you `ToString` for free!
let result2 = join.to_string();
Joins are also iterable. You can use .iter()
to iterate over references to the underlying iterator, or into_iter()
to convert the join into an iterator. Join iterators use an item type called JoinItem
, which distinguishes between separators and elements of the underlying iterator:
use joinery::JoinItem;
let mut iter = join.iter();
assert_eq!(iter.next(), Some(JoinItem::Element(&1)));
assert_eq!(iter.next(), Some(JoinItem::Separator(&", ")));
assert_eq!(iter.next(), Some(JoinItem::Element(&2)));
assert_eq!(iter.next(), Some(JoinItem::Separator(&", ")));
assert_eq!(iter.next(), Some(JoinItem::Element(&3)));