Skip to content
Candidates for inclusion in the Rust standard library
Branch: master
Clone or download
SimonSapin Merge pull request #16 from SimonSapin/matches
Fix the matches crate on Nightly
Latest commit df2edec Aug 22, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
matches Remove incorrect use of local_inner_macros, fix #15 Aug 22, 2018
return_if_ok Add return_if_ok Jan 25, 2015
text_writer Deprecate the TextWriter trait in favor of std::fmt::Write. Apr 21, 2015
zip_longest Make tests pass on Rust 1.18 and older Aug 22, 2018
LICENSE Add matches! and zip_longest Dec 4, 2014
Makefile Deprecate the TextWriter trait in favor of std::fmt::Write. Apr 21, 2015

These are candidates for addition to the Rust standard library. Each crate is published separately on

The matches! macro

RFC #163

A macro to evaluate, as a boolean, whether an expression matches a pattern.

To use it, add to your Cargo.toml:

matches = "0.1"


#[macro_use] extern crate matches;

fn is_slash(input: &str, pos: uint) -> bool {
    matches!(input.char_at(pos), '/' | '\\')
#[macro_use] extern crate matches;
extern crate serialize;
use serialize::json::Json;

fn object_has_key(json: &Json, key: &str) -> bool {
    matches!(json, &Json::Object(ref obj) if obj.contains_key(key))

The zip_longest iterator adaptor

PR #19283

The standard library has an method that returns a new iterator that yields pairs, and stops when one of the input iterators does.

zip_longest is similar, but instead continues until both iterators are exhausted. Instead of a pair of values (A, B), it yield an EitherOrBoth enum that contains Both(A, B), Left(A), or Right(B) depending on which of the input iterators if any is exhausted.

To use it, add to your Cargo.toml:

zip_longest = "0.1"


#[macro_use] extern crate matches;
extern crate zip_longest;
use zip_longest::{ZipLongestIteratorExt, EitherOrBoth};

fn iter_eq<I, J, T>(i: I, j: J) -> bool
where I: Iterator<T>, J: Iterator<T>, T: Eq {
    i.zip_longest(j).all(|x| matches!(x, EitherOrBoth::Both(a, b) if a == b))

The show! debugging macro

Issue #12015

The minimal code (with only the standard library) for writing something to stdout is currently println!("{}", foo). The "{}", part does not provide any information other than "do the default thing" which, you know, could be implicitly the default. It gets slitghly tedious to type when it is added and removed a lot, for doing “print-style” debugging.

The show! macro is a shortcut for calling println! with any any number of expressions, that are printed space-separated with the default {} / Show formatting.

Note: Although debugging is the primary motivation for show!, there is nothing wrong with using it in “normal” code if it does what you need.

To use it, add to your Cargo.toml:

show = "0.1"


#[macro_use] extern crate show;

use std::os::getenv;

fn defibrillate_flux_capacitor(gigowatts: float) {
    // Temporarily added during debugging:
    show!(gigowatts, getenv("EPOCH"));
    // Equivalent to:
    println!("{} {}", gigowatts, getenv("EPOCH"));

    // ... do complicated stuff here.

The TextWriter trait

Depreacted. Use std::fmt::Write instead.

For historical interest, see the previous README entry and previous code

The return_if_ok! macro

Discuss topic #1416.

The return_if_ok macro takes a Result, then makes the function return early for Ok(_) values or unwraps Err(_) values:

macro_rules! return_if_ok {
    ($expr:expr) => (match $expr {
        Ok(val) => return Ok(val),
        Err(err) => err

Compare with the try! macro which takes a Result, then makes the funciton return early for Err(_) values or unwraps Ok(_) values:

macro_rules! try {
    ($expr:expr) => (match $expr {
        Ok(val) => val,
        Err(err) => return Err(FromError::from_error(err))

If we ignore the FromError conversion, return_if_ok! and try! (which could be named return_if_err!) are [dual][] in the same way that Result::or_else and Result::and_then are dual, and that || and && are dual.

To use it, add to your Cargo.toml:

return_if_ok = "0.1"


I’ve been using Result heavily in Servo’s CSS parsing rewrite. Grammar production rules map (roughly) to functions that return Result, concatenation maps to try! (or Result::and_then), and alternation maps to Result::or_else but would look nicer with return_if_ok! instead:

#[macro_use] extern crate return_if_ok;

/// <'width'> = <length> | <percentage> | "auto"
fn parse_width(input: &mut Parser) -> Result<LengthOrPercentageOrAuto, ()> {
    parse_keyword(input, "auto").map(|()| LengthOrPercentageOrAuto::Auto)

/// <'border-spacing'> = <length> <length>?
/// The second length defaults to the first
fn parse_border_spacing(input: &mut Parser) -> Result<(Length, Length), ()> {
    let first = try!(parse_length(input));
    let second = parse_length(input).unwrap_or(first);
    Ok((first, second))
You can’t perform that action at this time.