Struct HexCodec

Source

pub struct HexCodec { /* private fields */ }

Expand description

Encodes and decodes hexadecimal byte strings.

HexCodec is an owned facade for whole byte slices. Whole-string prefix, per-byte prefix, separator, and whitespace handling are part of encode and decode. Use crate::HexByteCodec when a low-level qubit_codec::Codec<Value = u8, Unit = u8> is required.

§Examples

use qubit_codec_misc::HexCodec;

let codec = HexCodec::new();
let encoded = codec.encode(&[0x1f, 0x8b]);
assert_eq!(encoded, "1f8b");
assert_eq!(codec.decode(&encoded).unwrap(), [0x1f, 0x8b]);

Implementations§

Source §

impl HexCodec

Source

pub fn new() -> Self

Creates a lowercase codec without prefix or separators.

§Returns

A hexadecimal codec using lowercase digits.

Source

pub fn upper() -> Self

Creates an uppercase codec without prefix or separators.

§Returns

A hexadecimal codec using uppercase digits.

Source

pub fn from_config(config: HexCodecConfig) -> Self

Creates a codec from an explicit configuration.

§Parameters

config: Configuration moved into the codec without cloning.

§Returns

A codec owning the supplied configuration.

Source

pub fn config(&self) -> &HexCodecConfig

Returns the configuration used by this codec.

§Returns

A shared reference to this codec’s configuration, borrowed from self.

Source

pub fn with_uppercase(self, uppercase: bool) -> Self

Sets whether encoded digits should be uppercase.

§Parameters

uppercase: Whether to use uppercase hexadecimal digits.

§Returns

The updated codec.

Source

pub fn with_prefix(self, prefix: impl Into<String>) -> Self

Sets a whole-output prefix.

The prefix is written once before the encoded bytes and required once before decoded input. For example, using prefix 0x encodes bytes as 0x1f8b.

§Parameters

prefix: Whole-output prefix text such as 0x.

§Returns

The updated codec.

Source

pub fn with_byte_prefix(self, prefix: impl Into<String>) -> Self

Sets a per-byte prefix.

The prefix is written before every encoded byte and required before every decoded byte. For example, using byte prefix 0x and separator encodes bytes as 0x1f 0x8b. When ASCII whitespace is ignored, a complete per-byte prefix is matched before additional whitespace is skipped.

§Parameters

prefix: Per-byte prefix text such as 0x.

§Returns

The updated codec.

Source

pub fn with_separator(self, separator: impl Into<String>) -> Self

Sets a separator written and accepted between encoded bytes.

With a non-empty separator, the two hexadecimal digits of each byte must be contiguous. Ignored ASCII whitespace may surround complete byte tokens and configured separators, but does not replace a required prefix or separator. Without a non-empty separator, ignored whitespace may also occur between the two digits of a byte. A complete structural token is matched before skipping additional whitespace. Non-whitespace separators are matched exactly; a whitespace-only separator still requires whitespace between bytes, and ignored ASCII whitespace may consume additional adjacent whitespace. Prefix case folding does not apply to separators.

§Parameters

separator: Separator text.

§Returns

The updated codec.

Source

pub fn with_ignored_ascii_whitespace(self, ignore: bool) -> Self

Sets whether ASCII whitespace is ignored while decoding.

With a non-empty separator, the two hexadecimal digits of each byte must be contiguous. Ignored ASCII whitespace may surround complete byte tokens and configured separators, but does not replace a required prefix or separator. Without a non-empty separator, ignored whitespace may also occur between the two digits of a byte. A complete structural token is matched before skipping additional whitespace. Non-whitespace separators are matched exactly; a whitespace-only separator still requires whitespace between bytes, and ignored ASCII whitespace may consume additional adjacent whitespace. Prefix case folding does not apply to separators.

§Parameters

ignore: Whether to ignore ASCII whitespace.

§Returns

The updated codec.

Source

pub fn with_ignore_prefix_case(self, ignore: bool) -> Self

Sets whether ASCII case is ignored when decoding configured prefixes.

This option affects whole-output prefixes and per-byte prefixes during decoding only. Encoding writes prefixes exactly as configured.

§Parameters

ignore: Whether to ignore ASCII case while matching prefixes.

§Returns

The updated codec.

Source

pub fn encode(&self, bytes: &[u8]) -> String

Encodes bytes into a hexadecimal string.

§Parameters

bytes: Bytes to encode.

§Returns

Hexadecimal text.

Source

pub fn encode_into(&self, bytes: &[u8], output: &mut String)

Appends the hexadecimal encoding of bytes to an existing string.

Existing contents are preserved. Call output.clear() first to replace them. Each call writes its own configured whole-output prefix; no separator is inserted between existing contents and this call’s output.

§Parameters

bytes: Bytes to encode.
output: Destination string to append to.

§Examples

use qubit_codec_misc::HexCodec;
let codec = HexCodec::new();
let mut output = String::from("header:");
codec.encode_into(&[0xab], &mut output);
assert_eq!(output, "header:ab");
output.clear();
codec.encode_into(&[0xcd], &mut output);
assert_eq!(output, "cd");

Source

pub fn decode(&self, text: &str) -> MiscCodecResult<Vec<u8>>

Decodes hexadecimal text into bytes.

§Parameters

text: Hexadecimal text.

§Returns

Decoded bytes.

§Errors

Returns MiscCodecError when a configured whole or per-byte prefix is missing, when the normalized digit count is odd, or when a non-hex digit is found.

Source

pub fn decode_into( &self, text: &str, output: &mut Vec<u8>, ) -> MiscCodecResult<()>

Appends decoded hexadecimal bytes to an existing vector.

Successful calls append decoded bytes. Call output.clear() first to replace existing contents. If decoding fails, elements and length from before this call are restored, though capacity may change. Contents cleared by the caller before this call are not protected by rollback.

§Parameters

text: Hexadecimal text.
output: Destination byte vector to append to.

§Errors

Returns MiscCodecError when the input is malformed. On such an error, the vector’s elements and length remain unchanged; its capacity may have changed.

§Examples

use qubit_codec_misc::HexCodec;
let codec = HexCodec::new();
let mut output = vec![0xa5];
codec.decode_into("ab", &mut output).unwrap();
assert_eq!(output, [0xa5, 0xab]);
assert!(codec.decode_into("cd0g", &mut output).is_err());
assert_eq!(output, [0xa5, 0xab]);
output.clear();
codec.decode_into("cd", &mut output).unwrap();
assert_eq!(output, [0xcd]);