| 1 |
# [RustCrypto]: hex-literal |
| 2 |
|
| 3 |
[![Crate][crate-image]][crate-link] |
| 4 |
[![Docs][docs-image]][docs-link] |
| 5 |
![Apache 2.0/MIT Licensed][license-image] |
| 6 |
![MSRV][rustc-image] |
| 7 |
[![Build Status][build-image]][build-link] |
| 8 |
|
| 9 |
This crate provides the `hex!` macro for converting hexadecimal string literals to a byte array at compile time. |
| 10 |
|
| 11 |
It accepts the following characters in the input string: |
| 12 |
|
| 13 |
- `'0'...'9'`, `'a'...'f'`, `'A'...'F'` — hex characters which will be used in construction of the output byte array |
| 14 |
- `' '`, `'\r'`, `'\n'`, `'\t'` — formatting characters which will be ignored |
| 15 |
|
| 16 |
# Examples |
| 17 |
```rust |
| 18 |
use hex_literal::hex; |
| 19 |
|
| 20 |
// The macro can be used in const contexts |
| 21 |
const DATA: [u8; 4] = hex!("01020304"); |
| 22 |
assert_eq!(DATA, [1, 2, 3, 4]); |
| 23 |
|
| 24 |
// Both upper and lower hex values are supported |
| 25 |
assert_eq!(hex!("a1 b2 c3 d4"), [0xA1, 0xB2, 0xC3, 0xD4]); |
| 26 |
assert_eq!(hex!("E5 E6 90 92"), [0xE5, 0xE6, 0x90, 0x92]); |
| 27 |
assert_eq!(hex!("0a0B 0C0d"), [10, 11, 12, 13]); |
| 28 |
|
| 29 |
// Multi-line literals |
| 30 |
let bytes1 = hex!(" |
| 31 |
00010203 04050607 |
| 32 |
08090a0b 0c0d0e0f |
| 33 |
"); |
| 34 |
assert_eq!( |
| 35 |
bytes1, |
| 36 |
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], |
| 37 |
); |
| 38 |
|
| 39 |
// It's possible to use several literals |
| 40 |
// (results will be concatenated) |
| 41 |
let bytes2 = hex!( |
| 42 |
"00010203 04050607" // first half |
| 43 |
"08090a0b 0c0d0e0f" // second half |
| 44 |
); |
| 45 |
assert_eq!(bytes1, bytes2); |
| 46 |
``` |
| 47 |
|
| 48 |
Using an unsupported character inside literals will result in a compilation error: |
| 49 |
```rust,compile_fail |
| 50 |
hex_literal::hex!("АА"); // Cyrillic "А" |
| 51 |
hex_literal::hex!("11 22"); // Japanese space |
| 52 |
``` |
| 53 |
|
| 54 |
Сomments inside literals are not supported: |
| 55 |
```rust,compile_fail |
| 56 |
hex_literal::hex!("0123 // foo"); |
| 57 |
``` |
| 58 |
|
| 59 |
Each literal must contain an even number of hex characters: |
| 60 |
```rust,compile_fail |
| 61 |
hex_literal::hex!( |
| 62 |
"01234" |
| 63 |
"567" |
| 64 |
); |
| 65 |
``` |
| 66 |
|
| 67 |
## Minimum Supported Rust Version |
| 68 |
|
| 69 |
Rust **1.57** or newer. |
| 70 |
|
| 71 |
In the future, we reserve the right to change MSRV (i.e. MSRV is out-of-scope for this crate's SemVer guarantees), however when we do it will be accompanied by a minor version bump. |
| 72 |
|
| 73 |
## License |
| 74 |
|
| 75 |
Licensed under either of: |
| 76 |
|
| 77 |
* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) |
| 78 |
* [MIT license](http://opensource.org/licenses/MIT) |
| 79 |
|
| 80 |
at your option. |
| 81 |
|
| 82 |
### Contribution |
| 83 |
|
| 84 |
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. |
| 85 |
|
| 86 |
[//]: # (badges) |
| 87 |
|
| 88 |
[crate-image]: https://img.shields.io/crates/v/hex-literal.svg |
| 89 |
[crate-link]: https://crates.io/crates/hex-literal |
| 90 |
[docs-image]: https://docs.rs/hex-literal/badge.svg |
| 91 |
[docs-link]: https://docs.rs/hex-literal/ |
| 92 |
[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg |
| 93 |
[rustc-image]: https://img.shields.io/badge/rustc-1.57+-blue.svg |
| 94 |
[build-image]: https://github.com/RustCrypto/utils/actions/workflows/hex-literal.yml/badge.svg |
| 95 |
[build-link]: https://github.com/RustCrypto/utils/actions/workflows/hex-literal.yml |
| 96 |
|
| 97 |
[//]: # (general links) |
| 98 |
|
| 99 |
[RustCrypto]: https://github.com/RustCrypto |