Crate v_escape provides a macro, `new!` 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!(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"`.
```
v_escape::new!(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`
```
v_escape::new!(MyEscape; 49 -> "bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
```
v_escape::new!(MyEscape; 0x31 -> "bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
```
v_escape::new!(MyEscape; 0o61 -> "bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
```
v_escape::new!(MyEscape; '1' -> "bar");
# fn main() {
assert_eq!(escape("foo 1").to_string(), "foo bar");
# }
```
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.
```
v_escape::new!(
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
```
v_escape::new!(MyEscape; 'o' -> "bar"; print = true);
# fn main() {
# assert_eq!(escape("foo").to_string(), "fbarbar");
# }
```