Struct bech32::primitives::decode::UncheckedHrpstring

pub struct UncheckedHrpstring<'s> { /* private fields */ }

An HRP string that has been parsed but not yet had the checksum checked.

Parsing an HRP string only checks validity of the characters, it does not validate the checksum in any way.

Unless you are attempting to validate a string with multiple checksums then you likely do not want to use this type directly, instead use [CheckedHrpstring::new(s)].

Examples

use bech32::{Bech32, Bech32m, primitives::decode::UncheckedHrpstring};

let addr = "BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4";
let unchecked = UncheckedHrpstring::new(addr).expect("valid bech32 character encoded string");
if unchecked.has_valid_checksum::<Bech32>() {
    // Remove the checksum and do something with the data.
    let checked = unchecked.remove_checksum::<Bech32>();
    let _ = checked.byte_iter();
} else if unchecked.has_valid_checksum::<Bech32m>() {
    // Remove the checksum and do something with the data as above.
} else {
    // Checksum is not valid for either the bech32 or bech32 checksum algorithms.
}

Implementations

impl<'s> UncheckedHrpstring<'s>

pub fn new(s: &'s str) -> Result<Self, UncheckedHrpstringError>

Parses an bech32 encode string and constructs a UncheckedHrpstring object.

Checks for valid ASCII values, does not validate the checksum.

pub fn hrp(&self) -> Hrp

Returns the human-readable part.

pub fn data_part_ascii(&self) -> &'s [u8]

Returns the data part as ASCII bytes i.e., everything after the separator ‘1’.

The byte values are guaranteed to be valid bech32 characters. Includes the checksum if one was present in the parsed string.

Examples

use bech32::primitives::decode::UncheckedHrpstring;

let addr = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
let ascii = "qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";

let unchecked = UncheckedHrpstring::new(&addr).unwrap();
assert!(unchecked.data_part_ascii().iter().eq(ascii.as_bytes().iter()))

pub fn remove_witness_version(&mut self) -> Option<Fe32>

Attempts to remove the first byte of the data part, treating it as a witness version.

If Self::witness_version succeeds this function removes the first character (witness version byte) from the internal ASCII data part buffer. Future calls to Self::data_part_ascii will no longer include it.

Examples

use bech32::{primitives::decode::UncheckedHrpstring, Fe32};

let addr = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
let ascii = "ar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";

let mut unchecked = UncheckedHrpstring::new(&addr).unwrap();
let witness_version = unchecked.remove_witness_version().unwrap();
assert_eq!(witness_version, Fe32::Q);
assert!(unchecked.data_part_ascii().iter().eq(ascii.as_bytes().iter()))

pub fn witness_version(&self) -> Option<Fe32>

Returns the segwit witness version if there is one.

Attempts to convert the first character of the data part to a witness version. If this succeeds, and it is a valid version (0..16 inclusive) we return it, otherwise None.

Future calls to Self::data_part_ascii will still include the witness version, use Self::remove_witness_version to remove it.

This function makes no guarantees on the validity of the checksum.

Examples

use bech32::{primitives::decode::UncheckedHrpstring, Fe32};

// Note the invalid checksum!
let addr = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzffffff";

let unchecked = UncheckedHrpstring::new(&addr).unwrap();
assert_eq!(unchecked.witness_version(), Some(Fe32::Q));

pub fn validate_and_remove_checksum<Ck: Checksum>( self ) -> Result<CheckedHrpstring<'s>, ChecksumError>

Validates that data has a valid checksum for the Ck algorithm and returns a CheckedHrpstring.

pub fn has_valid_checksum<Ck: Checksum>(&self) -> bool

Validates that data has a valid checksum for the Ck algorithm (this may mean an empty checksum if NoChecksum is used).

This is useful if you do not know which checksum algorithm was used and wish to validate against multiple algorithms consecutively. If this function returns true then call remove_checksum to get a CheckedHrpstring.

pub fn validate_checksum<Ck: Checksum>(&self) -> Result<(), ChecksumError>

Validates that data has a valid checksum for the Ck algorithm (this may mean an empty checksum if NoChecksum is used).

pub fn remove_checksum<Ck: Checksum>(self) -> CheckedHrpstring<'s>

Removes the checksum for the Ck algorithm and returns an CheckedHrpstring.

Data must be valid (ie, first call has_valid_checksum or validate_checksum()). This function is typically paired with has_valid_checksum when validating against multiple checksum algorithms consecutively.

Panics

May panic if data is not valid.

Trait Implementations

impl<'s> Debug for UncheckedHrpstring<'s>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.