#join #string #iterator #separator #iterable #joining #elements

no-std joinery

A small crate for generically joining iterators with a separator

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

Download history 29696/week @ 2024-08-16 31734/week @ 2024-08-23 30331/week @ 2024-08-30 31222/week @ 2024-09-06 28508/week @ 2024-09-13 38655/week @ 2024-09-20 30686/week @ 2024-09-27 35633/week @ 2024-10-04 35248/week @ 2024-10-11 42976/week @ 2024-10-18 39167/week @ 2024-10-25 37823/week @ 2024-11-01 45148/week @ 2024-11-08 44574/week @ 2024-11-15 30740/week @ 2024-11-22 28598/week @ 2024-11-29

156,956 downloads per month
Used in 135 crates (11 directly)

MIT license

46KB
718 lines

Travis (.com) GitHub stars Crates.io docs.rs Github commits (since latest release) license

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)));

Dependencies