Crate v_escape

Crate v_escape provides a macro, new_escape! that define a struct with escaping functionality. These macros are optimized using simd by default, but this can be alter using sub-attributes.

Quick start

In order to use v_escape you will have to call one of the two macros to create a escape struct. In this example, when using the macro new_escape!(MyEscape, "62->bar"); a new a struct MyEscape will be created that every time its method MyEscape::fmt is called will replace all characters ">" with "bar".

#[macro_use]
extern crate v_escape;

new_escape!(MyEscape, "62->bar");

let escaped = escape(s);

print!("{}", escaped);

To check if rust version has simd functionality. The following code has to be added to file build.rs.

use version_check::is_min_version;

fn main() {
    enable_simd_optimizations();
}

fn enable_simd_optimizations() {
    if !is_min_version("1.27.0").map_or(false, |(yes, _)| yes) {
        println!("cargo:rustc-cfg=v_escape_nosimd");
    }
}

Pairs syntax

v_escape uses a simple syntax to replace characters with their respective quotes. The tuple is named Pair, and several can be defined, referred as Pairs. The syntax to define Pairs consists of a character, followed by the delimiter ->, followed by the substitution quote and the delimiter || (last delimiter is optional):

([character]->[quote] || )*

• character : Character to substitute. Acceptsi8+ from 0 to i8::MAX and accepts the following formats: decimal (49), hexadecimal (0x31), octal (0o61) or character (#1). Note: Numbers are read in ASCII: #6->foo

• quote : Characters that will replace character

new_escape!(MyEscape, "49->bar");
assert_eq!(escape("foo 1").to_string(), "foo bar");

new_escape!(MyEscape, "0x31->bar");
assert_eq!(escape("foo 1").to_string(), "foo bar");

new_escape!(MyEscape, "0o61->bar");
assert_eq!(escape("foo 1").to_string(), "foo bar");

new_escape!(MyEscape, "#1->bar");
assert_eq!(escape("foo 1").to_string(), "foo bar");

ranges refers to a possible optimization that when given a number of pairs, an optimal number of ranges (with a maximum of three) are calculated and used to escape all bytes within each range. It is possible the existence of false positives, and will be discarded. If a lot of pairs have to be discarded sub-attribute ranges must be explicitly disabled. In the case that more than three bytes are used and the distance between the escaped characters is very large, then ranges = false.

new_escape!(MyEscape, "0-> || 33->foo || 66->bar || 127->", ranges = false);
assert_eq!(escape("fooBbar").to_string(), "foobarbar");

In the following example more than 16 pairs are given, this exceeds simd's boundary. If simd optimization is wanted, ranges must be enabled (default) or an error will be thrown. It is possible to not use ranges but simd optimization has to be disabled.

new_escape!(
    MyEscape,
    "62->b || 60->f || B->b || 65->f || 0o67->b || #6->f || 68->b || \
    71->f || 72->b || 73->f || 74->b || 75->f || 76->b || 77->f || \
    78->b || 79->f || 0x1A->f"
);
assert_eq!(escape("foo>bar<").to_string(), "foobbarf");

For debugging purposes, sub-attribute print, can be set to true to print generated code

new_escape!(MyEscape, "o->bar", print = true);

Macros

new_escape

Generates struct $name with escaping functionality at fmt