Debian Codegraph @

.cargo/vendor/hex-literal/README.md

raw
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