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.

Source

pub fn config(&self) -> &HexCodecConfig

Returns the configuration used by this codec.

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)

Encodes bytes into an existing string.

§Parameters

bytes: Bytes to encode.
output: Destination string.

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<()>

Decodes hexadecimal text into an existing byte vector.

§Parameters

text: Hexadecimal text.
output: Destination byte vector.

§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.