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");
# fn main() {
# let s = "foo>bar";
let escaped = escape(s);
print!("{}", escaped);
# }
```
## 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. Accepts`i8+` 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`
```
# #[macro_use]
# extern crate v_escape;
new_escape!(MyEscape, "49->bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
```
# #[macro_use]
# extern crate v_escape;
new_escape!(MyEscape, "0x31->bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
```
# #[macro_use]
# extern crate v_escape;
new_escape!(MyEscape, "0o61->bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
```
# #[macro_use]
# extern crate v_escape;
new_escape!(MyEscape, "#1->bar");
# fn main() {
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`.
```
# #[macro_use]
# extern crate v_escape;
new_escape!(MyEscape, "0-> || 33->foo || 66->bar || 127->", ranges = false);
# fn main() {
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.
```
# #[macro_use]
# extern crate v_escape;
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"
);
# fn main() {
assert_eq!(escape("foo>bar<").to_string(), "foobbarf");
# }
```
For debugging purposes, sub-attribute `print`, can be set to `true`
to print generated code
```
# #[macro_use]
# extern crate v_escape;
new_escape!(MyEscape, "o->bar", print = true);
# fn main() {
# assert_eq!(escape("foo").to_string(), "fbarbar");
# }
```