/rust/registry/src/index.crates.io-1949cf8c6b5b557f/uuid-1.29.2/src/parser.rs

Source
// Copyright 2013-2014 The Rust Project Developers.
// Copyright 2018 The Uuid Project Developers.
//
// See the COPYRIGHT file at the top-level directory of this distribution.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! [`Uuid`] parsing constructs and utilities.
//!
//! [`Uuid`]: ../struct.Uuid.html

use crate::{
    error::*,
    std::{convert::TryFrom, str},
    Uuid,
};

#[cfg(feature = "std")]
use crate::std::string::String;

impl str::FromStr for Uuid {
    type Err = Error;

    fn from_str(uuid_str: &str) -> Result<Self, Self::Err> {
        Uuid::parse_str(uuid_str)
    }
}

impl TryFrom<&'_ str> for Uuid {
    type Error = Error;

    fn try_from(uuid_str: &'_ str) -> Result<Self, Self::Error> {
        Uuid::parse_str(uuid_str)
    }
}

#[cfg(feature = "std")]
impl TryFrom<String> for Uuid {
    type Error = Error;

    fn try_from(uuid_str: String) -> Result<Self, Self::Error> {
        Uuid::try_from(uuid_str.as_ref())
    }
}

impl Uuid {
    /// Parses a `Uuid` from a string of hexadecimal digits with optional
    /// hyphens.
    ///
    /// Any of the formats generated by this module (simple, hyphenated, urn,
    /// Microsoft GUID) are supported by this parsing function.
    ///
    /// Prefer [`try_parse`] unless you need detailed user-facing diagnostics.
    /// This method will be eventually deprecated in favor of `try_parse`.
    ///
    /// # Examples
    ///
    /// Parse a hyphenated UUID:
    ///
    /// ```
    /// # use uuid::{Uuid, Version, Variant};
    /// # fn main() -> Result<(), uuid::Error> {
    /// let uuid = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;
    ///
    /// assert_eq!(Some(Version::Random), uuid.get_version());
    /// assert_eq!(Variant::RFC4122, uuid.get_variant());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// [`try_parse`]: #method.try_parse
    pub fn parse_str(input: &str) -> Result<Uuid, Error> {
        try_parse(input.as_bytes())
            .map(Uuid::from_bytes)
            .map_err(InvalidUuid::into_err)
    }

    /// Parses a `Uuid` from a string of hexadecimal digits with optional
    /// hyphens.
    ///
    /// This function is similar to [`parse_str`], in fact `parse_str` shares
    /// the same underlying parser. The difference is that if `try_parse`
    /// fails, it won't generate very useful error messages. The `parse_str`
    /// function will eventually be deprecated in favor of `try_parse`.
    ///
    /// To parse a UUID from a byte stream instead of a UTF8 string, see
    /// [`try_parse_ascii`].
    ///
    /// # Examples
    ///
    /// Parse a hyphenated UUID:
    ///
    /// ```
    /// # use uuid::{Uuid, Version, Variant};
    /// # fn main() -> Result<(), uuid::Error> {
    /// let uuid = Uuid::try_parse("550e8400-e29b-41d4-a716-446655440000")?;
    ///
    /// assert_eq!(Some(Version::Random), uuid.get_version());
    /// assert_eq!(Variant::RFC4122, uuid.get_variant());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// [`parse_str`]: #method.parse_str
    /// [`try_parse_ascii`]: #method.try_parse_ascii
    pub const fn try_parse(input: &str) -> Result<Uuid, Error> {
        Self::try_parse_ascii(input.as_bytes())
    }

    /// Parses a `Uuid` from a string of hexadecimal digits with optional
    /// hyphens.
    ///
    /// The input is expected to be a string of ASCII characters. This method
    /// can be more convenient than [`try_parse`] if the UUID is being
    /// parsed from a byte stream instead of from a UTF8 string.
    ///
    /// # Examples
    ///
    /// Parse a hyphenated UUID:
    ///
    /// ```
    /// # use uuid::{Uuid, Version, Variant};
    /// # fn main() -> Result<(), uuid::Error> {
    /// let uuid = Uuid::try_parse_ascii(b"550e8400-e29b-41d4-a716-446655440000")?;
    ///
    /// assert_eq!(Some(Version::Random), uuid.get_version());
    /// assert_eq!(Variant::RFC4122, uuid.get_variant());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// [`try_parse`]: #method.try_parse
    pub const fn try_parse_ascii(input: &[u8]) -> Result<Uuid, Error> {
        match try_parse(input) {
            Ok(bytes) => Ok(Uuid::from_bytes(bytes)),
            // If parsing fails then we don't know exactly what went wrong
            // In this case, we just return a generic error
            Err(_) => Err(Error(ErrorKind::ParseOther)),
        }
    }
}

const fn try_parse(input: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
    match (input.len(), input) {
        // Inputs of 32 bytes must be a non-hyphenated UUID
        (32, s) => parse_simple(s, true),
        // Hyphenated UUIDs may be wrapped in various ways:
        // - `{UUID}` for braced UUIDs
        // - `urn:uuid:UUID` for URNs
        // - `UUID` for a regular hyphenated UUID
        (36, s) | (38, [b'{', s @ .., b'}']) => parse_hyphenated(s),
        (45, s) => {
            let (prefix, s) = s.split_at(9);

            if prefix.eq_ignore_ascii_case(b"urn:uuid:") {
                parse_hyphenated(s)
            } else {
                Err(InvalidUuid(input, RequestedUuid::Any))
            }
        }
        // Any other shaped input is immediately invalid
        _ => Err(InvalidUuid(input, RequestedUuid::Any)),
    }
}

#[inline]
#[allow(dead_code)]
pub(crate) const fn parse_braced(input: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
    if let (38, [b'{', s @ .., b'}']) = (input.len(), input) {
        parse_hyphenated(s)
    } else {
        Err(InvalidUuid(input, RequestedUuid::Braced))
    }
}

#[inline]
#[allow(dead_code)]
pub(crate) const fn parse_urn(input: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
    if input.len() == 45 && input.split_at(9).0.eq_ignore_ascii_case(b"urn:uuid:") {
        parse_hyphenated(input.split_at(9).1)
    } else {
        Err(InvalidUuid(input, RequestedUuid::Urn))
    }
}

#[inline]
pub(crate) const fn parse_simple(
    s: &'_ [u8],
    speculative: bool,
) -> Result<[u8; 16], InvalidUuid<'_>> {
    // This length check here removes all other bounds
    // checks in this function
    if s.len() != 32 {
        return Err(InvalidUuid(
            s,
            if speculative {
                RequestedUuid::Any
            } else {
                RequestedUuid::Simple
            },
        ));
    }

    // Copy the hex characters into a fixed-size array so the decoder's
    // bounds are statically known.
    let mut hex = [0u8; 32];
    let mut i = 0;
    while i < 32 {
        hex[i] = s[i];
        i += 1;
    }

    match decode_hex32(&hex) {
        Some(buf) => Ok(buf),
        None => Err(InvalidUuid(
            s,
            if speculative {
                RequestedUuid::Any
            } else {
                RequestedUuid::Simple
            },
        )),
    }
}

#[inline]
pub(crate) const fn parse_hyphenated(s: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
    // This length check here removes all other bounds
    // checks in this function
    if s.len() != 36 {
        return Err(InvalidUuid(s, RequestedUuid::Hyphenated));
    }

    // The hex characters are split into five groups separated by hyphens.
    // The indexes we're interested in are:
    //
    // uuid     : 936da01f-9abd-4d9d-80c7-02af85c822a8
    //            |   |   ||   ||   ||   ||   |   |
    // hyphens  : |   |   8|  13|  18|  23|   |   |
    // positions: 0   4    9   14   19   24  28  32

    // First, ensure the hyphens appear in the right places
    match [s[8], s[13], s[18], s[23]] {
        [b'-', b'-', b'-', b'-'] => {}
        _ => return Err(InvalidUuid(s, RequestedUuid::Hyphenated)),
    }

    // Gather the hex characters, skipping the four hyphens, so they're
    // contiguous for the decoder.
    let mut hex = [0u8; 32];
    let mut i = 0;
    while i < 8 {
        hex[i] = s[i];
        i += 1;
    }
    while i < 12 {
        hex[i] = s[i + 1];
        i += 1;
    }
    while i < 16 {
        hex[i] = s[i + 2];
        i += 1;
    }
    while i < 20 {
        hex[i] = s[i + 3];
        i += 1;
    }
    while i < 32 {
        hex[i] = s[i + 4];
        i += 1;
    }

    match decode_hex32(&hex) {
        Some(buf) => Ok(buf),
        None => Err(InvalidUuid(s, RequestedUuid::Hyphenated)),
    }
}

/// Decodes 32 hexadecimal ASCII characters into 16 bytes, returning `None` if
/// any character is not a valid hexadecimal digit.
#[inline]
const fn decode_hex32(hex: &[u8; 32]) -> Option<[u8; 16]> {
    let mut nibbles = [0u8; 32];
    let mut bad = 0u8;

    let mut i = 0;
    while i < 32 {
        let c = hex[i];

        // '0'..='9' map to 0..=9; 'a'..='f' and 'A'..='F' (via `| 0x20`) map to
        // 0..=5, offset by 10 to land in 10..=15.
        let digit = c.wrapping_sub(b'0');
        let alpha = (c | 0x20).wrapping_sub(b'a');

        let is_digit = digit < 10;
        let is_alpha = alpha < 6;

        nibbles[i] = if is_digit {
            digit
        } else {
            alpha.wrapping_add(10)
        };

        bad |= if is_digit | is_alpha { 0 } else { 1 };

        i += 1;
    }

    if bad != 0 {
        return None;
    }

    let mut buf = [0u8; 16];
    let mut j = 0;
    while j < 16 {
        buf[j] = (nibbles[j * 2] << 4) | nibbles[j * 2 + 1];
        j += 1;
    }

    Some(buf)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{
        fmt::*,
        std::{str::FromStr, string::ToString},
        tests::some_uuid_iter,
    };

    #[test]
    fn test_parse_valid() {
        let from_hyphenated = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap();
        let from_simple = Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c8").unwrap();
        let from_urn = Uuid::parse_str("urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap();
        let from_guid = Uuid::parse_str("{67e55044-10b1-426f-9247-bb680e5fe0c8}").unwrap();

        assert_eq!(from_hyphenated, from_simple);
        assert_eq!(from_hyphenated, from_urn);
        assert_eq!(from_hyphenated, from_guid);

        assert!(Uuid::parse_str("00000000000000000000000000000000").is_ok());
        assert!(Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
        assert!(Uuid::parse_str("F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4").is_ok());
        assert!(Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c8").is_ok());
        assert!(Uuid::parse_str("01020304-1112-2122-3132-414243444546").is_ok());
        assert!(Uuid::parse_str("urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
        assert!(Uuid::parse_str("URN:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
        assert!(Uuid::parse_str("Urn:Uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
        assert!(Uuid::parse_str("{6d93bade-bd9f-4e13-8914-9474e1e3567b}").is_ok());

        assert_eq!(
            from_urn,
            Uuid::parse_str("URN:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap()
        );
        assert_eq!(
            from_urn,
            Uuid::parse_str("urn:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap()
        );

        // Nil
        let nil = Uuid::nil();
        assert_eq!(
            Uuid::parse_str("00000000000000000000000000000000").unwrap(),
            nil
        );
        assert_eq!(
            Uuid::parse_str("00000000-0000-0000-0000-000000000000").unwrap(),
            nil
        );
    }

    #[test]
    fn test_parse_invalid() {
        // Invalid
        assert_eq!(
            Uuid::parse_str(""),
            Err(Error(ErrorKind::ParseLength { len: 0 }))
        );

        assert_eq!(
            Uuid::parse_str("{}"),
            Err(Error(ErrorKind::ParseGroupCount { count: 1 }))
        );

        assert_eq!(
            Uuid::parse_str("!"),
            Err(Error(ErrorKind::ParseChar {
                character: '!',
                index: 0,
            }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faa-B6BF-329BF39FA1E45"),
            Err(Error(ErrorKind::ParseGroupLength {
                group: 4,
                len: 13,
                index: 25,
            }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faa-BBF-329BF39FA1E4"),
            Err(Error(ErrorKind::ParseGroupLength {
                group: 3,
                len: 3,
                index: 20,
            }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faa-BGBF-329BF39FA1E4"),
            Err(Error(ErrorKind::ParseChar {
                character: 'G',
                index: 20,
            }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2F4faaFB6BFF329BF39FA1E4"),
            Err(Error(ErrorKind::ParseGroupCount { count: 2 }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faaFB6BFF329BF39FA1E4"),
            Err(Error(ErrorKind::ParseGroupCount { count: 3 }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faa-B6BFF329BF39FA1E4"),
            Err(Error(ErrorKind::ParseGroupCount { count: 4 }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faa"),
            Err(Error(ErrorKind::ParseGroupCount { count: 3 }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faaXB6BFF329BF39FA1E4"),
            Err(Error(ErrorKind::ParseChar {
                character: 'X',
                index: 18,
            }))
        );

        assert_eq!(
            Uuid::parse_str("{F9168C5E-CEB2-4faa9B6BFF329BF39FA1E41"),
            Err(Error(ErrorKind::ParseChar {
                character: '{',
                index: 0,
            }))
        );

        assert_eq!(
            Uuid::parse_str("{F9168C5E-CEB2-4faa9B6BFF329BF39FA1E41}"),
            Err(Error(ErrorKind::ParseGroupCount { count: 3 }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB-24fa-eB6BFF32-BF39FA1E4"),
            Err(Error(ErrorKind::ParseGroupLength {
                group: 1,
                len: 3,
                index: 10,
            }))
        );

        // // (group, found, expecting)
        assert_eq!(
            Uuid::parse_str("01020304-1112-2122-3132-41424344"),
            Err(Error(ErrorKind::ParseGroupLength {
                group: 4,
                len: 8,
                index: 25,
            }))
        );

        assert_eq!(
            Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c"),
            Err(Error(ErrorKind::ParseLength { len: 31 }))
        );

        assert_eq!(
            Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c88"),
            Err(Error(ErrorKind::ParseLength { len: 33 }))
        );

        assert_eq!(
            Uuid::parse_str("67e5504410b1426f9247bb680e5fe0cg8"),
            Err(Error(ErrorKind::ParseChar {
                character: 'g',
                index: 31,
            }))
        );

        assert_eq!(
            Uuid::parse_str("67e5504410b1426%9247bb680e5fe0c8"),
            Err(Error(ErrorKind::ParseChar {
                character: '%',
                index: 15,
            }))
        );

        assert_eq!(
            Uuid::parse_str("231231212212423424324323477343246663"),
            Err(Error(ErrorKind::ParseGroupCount { count: 1 }))
        );

        assert_eq!(
            Uuid::parse_str("{00000000000000000000000000000000}"),
            Err(Error(ErrorKind::ParseGroupCount { count: 1 }))
        );

        assert_eq!(
            Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c"),
            Err(Error(ErrorKind::ParseLength { len: 31 }))
        );

        assert_eq!(
            Uuid::parse_str("67e550X410b1426f9247bb680e5fe0cd"),
            Err(Error(ErrorKind::ParseChar {
                character: 'X',
                index: 6,
            }))
        );

        assert_eq!(
            Uuid::parse_str("67e550-4105b1426f9247bb680e5fe0c"),
            Err(Error(ErrorKind::ParseGroupCount { count: 2 }))
        );

        assert_eq!(
            Uuid::parse_str("F9168C5E-CEB2-4faa-B6BF1-02BF39FA1E4"),
            Err(Error(ErrorKind::ParseGroupLength {
                group: 3,
                len: 5,
                index: 20,
            }))
        );

        assert_eq!(
            Uuid::parse_str("\u{bcf3c}"),
            Err(Error(ErrorKind::ParseChar {
                character: '\u{bcf3c}',
                index: 0,
            }))
        );

        assert_eq!(
            Uuid::parse_str("\u{130}"),
            Err(Error(ErrorKind::ParseChar {
                character: '\u{130}',
                index: 0,
            }))
        );

        assert_eq!(
            Err(Error(ErrorKind::ParseLength { len: 0 })),
            Hyphenated::from_str("")
        );

        assert_eq!(
            Err(Error(ErrorKind::ParseGroupCount { count: 1 })),
            Hyphenated::from_str("550e8400e29b41d4a716446655440000")
        );

        assert_eq!(
            Err(Error(ErrorKind::ParseChar {
                character: '-',
                index: 8
            })),
            Simple::from_str("550e8400-e29b-41d4-a716-446655440000")
        );

        assert_eq!(
            Err(Error(ErrorKind::ParseChar {
                character: '5',
                index: 0
            })),
            Urn::from_str("550e8400-e29b-41d4-a716-446655440000")
        );
        assert_eq!(
            Err(Error(ErrorKind::ParseChar {
                character: ':',
                index: 0
            })),
            Urn::from_str(":550e8400-e29b-41d4-a716-446655440000")
        );
        assert_eq!(
            Uuid::parse_str("urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap(),
            Urn::from_str("URN:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8")
                .unwrap()
                .into_uuid()
        );

        assert_eq!(
            Err(Error(ErrorKind::ParseChar {
                character: '5',
                index: 0
            })),
            Braced::from_str("550e8400-e29b-41d4-a716-446655440000")
        );
        assert_eq!(
            Err(Error(ErrorKind::ParseChar {
                character: '{',
                index: 1
            })),
            Braced::from_str("{{550e8400-e29b-41d4-a716-446655440000}}")
        );

        // Unicode
        assert_eq!(
            Uuid::from_str("{6e0----------9=4O-0e5\u{14}e0c4\u{ec2f}8}"),
            Err(Error(ErrorKind::ParseChar {
                character: '=',
                index: 15,
            }))
        );

        assert_eq!(
            Uuid::from_str("urn:uuid:urae0c8"),
            Err(Error(ErrorKind::ParseChar {
                character: 'u',
                index: 9,
            }))
        );
    }

    #[test]
    fn test_roundtrip_default() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.to_string();
            let uuid_out = Uuid::parse_str(&orig_str).unwrap();
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_roundtrip_hyphenated() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.hyphenated().to_string();
            let uuid_out = Uuid::parse_str(&orig_str).unwrap();
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_roundtrip_simple() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.simple().to_string();
            let uuid_out = Uuid::parse_str(&orig_str).unwrap();
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_roundtrip_urn() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.urn().to_string();
            let uuid_out = Uuid::parse_str(&orig_str).unwrap();
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_roundtrip_braced() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.braced().to_string();
            let uuid_out = Uuid::parse_str(&orig_str).unwrap();
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_roundtrip_parse_urn() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.urn().to_string();
            let uuid_out = Uuid::from_bytes(parse_urn(orig_str.as_bytes()).unwrap());
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_roundtrip_parse_braced() {
        for uuid_orig in some_uuid_iter() {
            let orig_str = uuid_orig.braced().to_string();
            let uuid_out = Uuid::from_bytes(parse_braced(orig_str.as_bytes()).unwrap());
            assert_eq!(uuid_orig, uuid_out);
        }
    }

    #[test]
    fn test_try_parse_ascii_non_utf8() {
        assert!(Uuid::try_parse_ascii(b"67e55044-10b1-426f-9247-bb680e5\0e0c8").is_err());
    }
}

Coverage Report

Created: 2026-11-12 07:09

Line	Count	Source
1		// Copyright 2013-2014 The Rust Project Developers.
2		// Copyright 2018 The Uuid Project Developers.
3		//
4		// See the COPYRIGHT file at the top-level directory of this distribution.
5		//
6		// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
7		// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
8		// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
9		// option. This file may not be copied, modified, or distributed
10		// except according to those terms.
11
12		//! [`Uuid`] parsing constructs and utilities.
13		//!
14		//! [`Uuid`]: ../struct.Uuid.html
15
16		use crate::{
17		error::*,
18		std::{convert::TryFrom, str},
19		Uuid,
20		};
21
22		#[cfg(feature = "std")]
23		use crate::std::string::String;
24
25		impl str::FromStr for Uuid {
26		type Err = Error;
27
28	0	fn from_str(uuid_str: &str) -> Result<Self, Self::Err> {
29	0	Uuid::parse_str(uuid_str)
30	0	}
31		}
32
33		impl TryFrom<&'_ str> for Uuid {
34		type Error = Error;
35
36	0	fn try_from(uuid_str: &'_ str) -> Result<Self, Self::Error> {
37	0	Uuid::parse_str(uuid_str)
38	0	}
39		}
40
41		#[cfg(feature = "std")]
42		impl TryFrom<String> for Uuid {
43		type Error = Error;
44
45	0	fn try_from(uuid_str: String) -> Result<Self, Self::Error> {
46	0	Uuid::try_from(uuid_str.as_ref())
47	0	}
48		}
49
50		impl Uuid {
51		/// Parses a `Uuid` from a string of hexadecimal digits with optional
52		/// hyphens.
53		///
54		/// Any of the formats generated by this module (simple, hyphenated, urn,
55		/// Microsoft GUID) are supported by this parsing function.
56		///
57		/// Prefer [`try_parse`] unless you need detailed user-facing diagnostics.
58		/// This method will be eventually deprecated in favor of `try_parse`.
59		///
60		/// # Examples
61		///
62		/// Parse a hyphenated UUID:
63		///
64		/// ```
65		/// # use uuid::{Uuid, Version, Variant};
66		/// # fn main() -> Result<(), uuid::Error> {
67		/// let uuid = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;
68		///
69		/// assert_eq!(Some(Version::Random), uuid.get_version());
70		/// assert_eq!(Variant::RFC4122, uuid.get_variant());
71		/// # Ok(())
72		/// # }
73		/// ```
74		///
75		/// [`try_parse`]: #method.try_parse
76	1.21k	pub fn parse_str(input: &str) -> Result<Uuid, Error> {
77	1.21k	try_parse(input.as_bytes())
78	1.21k	.map(Uuid::from_bytes)
79	1.21k	.map_err(InvalidUuid::into_err)
80	1.21k	}
81
82		/// Parses a `Uuid` from a string of hexadecimal digits with optional
83		/// hyphens.
84		///
85		/// This function is similar to [`parse_str`], in fact `parse_str` shares
86		/// the same underlying parser. The difference is that if `try_parse`
87		/// fails, it won't generate very useful error messages. The `parse_str`
88		/// function will eventually be deprecated in favor of `try_parse`.
89		///
90		/// To parse a UUID from a byte stream instead of a UTF8 string, see
91		/// [`try_parse_ascii`].
92		///
93		/// # Examples
94		///
95		/// Parse a hyphenated UUID:
96		///
97		/// ```
98		/// # use uuid::{Uuid, Version, Variant};
99		/// # fn main() -> Result<(), uuid::Error> {
100		/// let uuid = Uuid::try_parse("550e8400-e29b-41d4-a716-446655440000")?;
101		///
102		/// assert_eq!(Some(Version::Random), uuid.get_version());
103		/// assert_eq!(Variant::RFC4122, uuid.get_variant());
104		/// # Ok(())
105		/// # }
106		/// ```
107		///
108		/// [`parse_str`]: #method.parse_str
109		/// [`try_parse_ascii`]: #method.try_parse_ascii
110	0	pub const fn try_parse(input: &str) -> Result<Uuid, Error> {
111	0	Self::try_parse_ascii(input.as_bytes())
112	0	}
113
114		/// Parses a `Uuid` from a string of hexadecimal digits with optional
115		/// hyphens.
116		///
117		/// The input is expected to be a string of ASCII characters. This method
118		/// can be more convenient than [`try_parse`] if the UUID is being
119		/// parsed from a byte stream instead of from a UTF8 string.
120		///
121		/// # Examples
122		///
123		/// Parse a hyphenated UUID:
124		///
125		/// ```
126		/// # use uuid::{Uuid, Version, Variant};
127		/// # fn main() -> Result<(), uuid::Error> {
128		/// let uuid = Uuid::try_parse_ascii(b"550e8400-e29b-41d4-a716-446655440000")?;
129		///
130		/// assert_eq!(Some(Version::Random), uuid.get_version());
131		/// assert_eq!(Variant::RFC4122, uuid.get_variant());
132		/// # Ok(())
133		/// # }
134		/// ```
135		///
136		/// [`try_parse`]: #method.try_parse
137	0	pub const fn try_parse_ascii(input: &[u8]) -> Result<Uuid, Error> {
138	0	match try_parse(input) {
139	0	Ok(bytes) => Ok(Uuid::from_bytes(bytes)),
140		// If parsing fails then we don't know exactly what went wrong
141		// In this case, we just return a generic error
142	0	Err(_) => Err(Error(ErrorKind::ParseOther)),
143		}
144	0	}
145		}
146
147	1.21k	const fn try_parse(input: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
148	1.21k	match (input.len(), input) {
149		// Inputs of 32 bytes must be a non-hyphenated UUID
150	335	(32, s) => parse_simple(s, true),
151		// Hyphenated UUIDs may be wrapped in various ways:
152		// - `{UUID}` for braced UUIDs
153		// - `urn:uuid:UUID` for URNs
154		// - `UUID` for a regular hyphenated UUID
155	290	(36, s) \| (38, [b'{', s @ .., b'}']) => parse_hyphenated(s),
156	159	(45, s) => {
157	159	let (prefix, s) = s.split_at(9);
158
159	159	if prefix.eq_ignore_ascii_case(b"urn:uuid:") {
160	29	parse_hyphenated(s)
161		} else {
162	130	Err(InvalidUuid(input, RequestedUuid::Any))
163		}
164		}
165		// Any other shaped input is immediately invalid
166	434	_ => Err(InvalidUuid(input, RequestedUuid::Any)),
167		}
168	1.21k	}
169
170		#[inline]
171		#[allow(dead_code)]
172	0	pub(crate) const fn parse_braced(input: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
173	0	if let (38, [b'{', s @ .., b'}']) = (input.len(), input) {
174	0	parse_hyphenated(s)
175		} else {
176	0	Err(InvalidUuid(input, RequestedUuid::Braced))
177		}
178	0	}
179
180		#[inline]
181		#[allow(dead_code)]
182	0	pub(crate) const fn parse_urn(input: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
183	0	if input.len() == 45 && input.split_at(9).0.eq_ignore_ascii_case(b"urn:uuid:") {
184	0	parse_hyphenated(input.split_at(9).1)
185		} else {
186	0	Err(InvalidUuid(input, RequestedUuid::Urn))
187		}
188	0	}
189
190		#[inline]
191	335	pub(crate) const fn parse_simple(
192	335	s: &'_ [u8],
193	335	speculative: bool,
194	335	) -> Result<[u8; 16], InvalidUuid<'_>> {
195		// This length check here removes all other bounds
196		// checks in this function
197	335	if s.len() != 32 {
198		return Err(InvalidUuid(
199	0	s,
200	0	if speculative {
201	0	RequestedUuid::Any
202		} else {
203	0	RequestedUuid::Simple
204		},
205		));
206	335	}
207
208		// Copy the hex characters into a fixed-size array so the decoder's
209		// bounds are statically known.
210	335	let mut hex = [0u8; 32];
211	335	let mut i = 0;
212	11.0k	while i < 32 {
213	10.7k	hex[i] = s[i];
214	10.7k	i += 1;
215	10.7k	}
216
217	335	match decode_hex32(&hex) {
218	328	Some(buf) => Ok(buf),
219		None => Err(InvalidUuid(
220	7	s,
221	7	if speculative {
222	7	RequestedUuid::Any
223		} else {
224	0	RequestedUuid::Simple
225		},
226		)),
227		}
228	335	}
229
230		#[inline]
231	319	pub(crate) const fn parse_hyphenated(s: &'_ [u8]) -> Result<[u8; 16], InvalidUuid<'_>> {
232		// This length check here removes all other bounds
233		// checks in this function
234	319	if s.len() != 36 {
235	0	return Err(InvalidUuid(s, RequestedUuid::Hyphenated));
236	319	}
237
238		// The hex characters are split into five groups separated by hyphens.
239		// The indexes we're interested in are:
240		//
241		// uuid : 936da01f-9abd-4d9d-80c7-02af85c822a8
242		// \| \| \|\| \|\| \|\| \|\| \| \|
243		// hyphens : \| \| 8\| 13\| 18\| 23\| \| \|
244		// positions: 0 4 9 14 19 24 28 32
245
246		// First, ensure the hyphens appear in the right places
247	319	match [s[8], s[13], s[18], s[23]] {
248	240	[b'-', b'-', b'-', b'-'] => {}
249	79	_ => return Err(InvalidUuid(s, RequestedUuid::Hyphenated)),
250		}
251
252		// Gather the hex characters, skipping the four hyphens, so they're
253		// contiguous for the decoder.
254	240	let mut hex = [0u8; 32];
255	240	let mut i = 0;
256	2.16k	while i < 8 {
257	1.92k	hex[i] = s[i];
258	1.92k	i += 1;
259	1.92k	}
260	1.20k	while i < 12 {
261	960	hex[i] = s[i + 1];
262	960	i += 1;
263	960	}
264	1.20k	while i < 16 {
265	960	hex[i] = s[i + 2];
266	960	i += 1;
267	960	}
268	1.20k	while i < 20 {
269	960	hex[i] = s[i + 3];
270	960	i += 1;
271	960	}
272	3.12k	while i < 32 {
273	2.88k	hex[i] = s[i + 4];
274	2.88k	i += 1;
275	2.88k	}
276
277	240	match decode_hex32(&hex) {
278	237	Some(buf) => Ok(buf),
279	3	None => Err(InvalidUuid(s, RequestedUuid::Hyphenated)),
280		}
281	319	}
282
283		/// Decodes 32 hexadecimal ASCII characters into 16 bytes, returning `None` if
284		/// any character is not a valid hexadecimal digit.
285		#[inline]
286	575	const fn decode_hex32(hex: &[u8; 32]) -> Option<[u8; 16]> {
287	575	let mut nibbles = [0u8; 32];
288	575	let mut bad = 0u8;
289
290	575	let mut i = 0;
291	18.9k	while i < 32 {
292	18.4k	let c = hex[i];
293
294		// '0'..='9' map to 0..=9; 'a'..='f' and 'A'..='F' (via `\| 0x20`) map to
295		// 0..=5, offset by 10 to land in 10..=15.
296	18.4k	let digit = c.wrapping_sub(b'0');
297	18.4k	let alpha = (c \| 0x20).wrapping_sub(b'a');
298
299	18.4k	let is_digit = digit < 10;
300	18.4k	let is_alpha = alpha < 6;
301
302	18.4k	nibbles[i] = if is_digit {
303	13.4k	digit
304		} else {
305	4.96k	alpha.wrapping_add(10)
306		};
307
308	18.4k	bad \|= if is_digit \| is_alpha { 0 } else { 1 };
309
310	18.4k	i += 1;
311		}
312
313	575	if bad != 0 {
314	10	return None;
315	565	}
316
317	565	let mut buf = [0u8; 16];
318	565	let mut j = 0;
319	9.60k	while j < 16 {
320	9.04k	buf[j] = (nibbles[j * 2] << 4) \| nibbles[j * 2 + 1];
321	9.04k	j += 1;
322	9.04k	}
323
324	565	Some(buf)
325	575	}
326
327		#[cfg(test)]
328		mod tests {
329		use super::*;
330		use crate::{
331		fmt::*,
332		std::{str::FromStr, string::ToString},
333		tests::some_uuid_iter,
334		};
335
336		#[test]
337		fn test_parse_valid() {
338		let from_hyphenated = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap();
339		let from_simple = Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c8").unwrap();
340		let from_urn = Uuid::parse_str("urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap();
341		let from_guid = Uuid::parse_str("{67e55044-10b1-426f-9247-bb680e5fe0c8}").unwrap();
342
343		assert_eq!(from_hyphenated, from_simple);
344		assert_eq!(from_hyphenated, from_urn);
345		assert_eq!(from_hyphenated, from_guid);
346
347		assert!(Uuid::parse_str("00000000000000000000000000000000").is_ok());
348		assert!(Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
349		assert!(Uuid::parse_str("F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4").is_ok());
350		assert!(Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c8").is_ok());
351		assert!(Uuid::parse_str("01020304-1112-2122-3132-414243444546").is_ok());
352		assert!(Uuid::parse_str("urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
353		assert!(Uuid::parse_str("URN:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
354		assert!(Uuid::parse_str("Urn:Uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").is_ok());
355		assert!(Uuid::parse_str("{6d93bade-bd9f-4e13-8914-9474e1e3567b}").is_ok());
356
357		assert_eq!(
358		from_urn,
359		Uuid::parse_str("URN:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap()
360		);
361		assert_eq!(
362		from_urn,
363		Uuid::parse_str("urn:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap()
364		);
365
366		// Nil
367		let nil = Uuid::nil();
368		assert_eq!(
369		Uuid::parse_str("00000000000000000000000000000000").unwrap(),
370		nil
371		);
372		assert_eq!(
373		Uuid::parse_str("00000000-0000-0000-0000-000000000000").unwrap(),
374		nil
375		);
376		}
377
378		#[test]
379		fn test_parse_invalid() {
380		// Invalid
381		assert_eq!(
382		Uuid::parse_str(""),
383		Err(Error(ErrorKind::ParseLength { len: 0 }))
384		);
385
386		assert_eq!(
387		Uuid::parse_str("{}"),
388		Err(Error(ErrorKind::ParseGroupCount { count: 1 }))
389		);
390
391		assert_eq!(
392		Uuid::parse_str("!"),
393		Err(Error(ErrorKind::ParseChar {
394		character: '!',
395		index: 0,
396		}))
397		);
398
399		assert_eq!(
400		Uuid::parse_str("F9168C5E-CEB2-4faa-B6BF-329BF39FA1E45"),
401		Err(Error(ErrorKind::ParseGroupLength {
402		group: 4,
403		len: 13,
404		index: 25,
405		}))
406		);
407
408		assert_eq!(
409		Uuid::parse_str("F9168C5E-CEB2-4faa-BBF-329BF39FA1E4"),
410		Err(Error(ErrorKind::ParseGroupLength {
411		group: 3,
412		len: 3,
413		index: 20,
414		}))
415		);
416
417		assert_eq!(
418		Uuid::parse_str("F9168C5E-CEB2-4faa-BGBF-329BF39FA1E4"),
419		Err(Error(ErrorKind::ParseChar {
420		character: 'G',
421		index: 20,
422		}))
423		);
424
425		assert_eq!(
426		Uuid::parse_str("F9168C5E-CEB2F4faaFB6BFF329BF39FA1E4"),
427		Err(Error(ErrorKind::ParseGroupCount { count: 2 }))
428		);
429
430		assert_eq!(
431		Uuid::parse_str("F9168C5E-CEB2-4faaFB6BFF329BF39FA1E4"),
432		Err(Error(ErrorKind::ParseGroupCount { count: 3 }))
433		);
434
435		assert_eq!(
436		Uuid::parse_str("F9168C5E-CEB2-4faa-B6BFF329BF39FA1E4"),
437		Err(Error(ErrorKind::ParseGroupCount { count: 4 }))
438		);
439
440		assert_eq!(
441		Uuid::parse_str("F9168C5E-CEB2-4faa"),
442		Err(Error(ErrorKind::ParseGroupCount { count: 3 }))
443		);
444
445		assert_eq!(
446		Uuid::parse_str("F9168C5E-CEB2-4faaXB6BFF329BF39FA1E4"),
447		Err(Error(ErrorKind::ParseChar {
448		character: 'X',
449		index: 18,
450		}))
451		);
452
453		assert_eq!(
454		Uuid::parse_str("{F9168C5E-CEB2-4faa9B6BFF329BF39FA1E41"),
455		Err(Error(ErrorKind::ParseChar {
456		character: '{',
457		index: 0,
458		}))
459		);
460
461		assert_eq!(
462		Uuid::parse_str("{F9168C5E-CEB2-4faa9B6BFF329BF39FA1E41}"),
463		Err(Error(ErrorKind::ParseGroupCount { count: 3 }))
464		);
465
466		assert_eq!(
467		Uuid::parse_str("F9168C5E-CEB-24fa-eB6BFF32-BF39FA1E4"),
468		Err(Error(ErrorKind::ParseGroupLength {
469		group: 1,
470		len: 3,
471		index: 10,
472		}))
473		);
474
475		// // (group, found, expecting)
476		assert_eq!(
477		Uuid::parse_str("01020304-1112-2122-3132-41424344"),
478		Err(Error(ErrorKind::ParseGroupLength {
479		group: 4,
480		len: 8,
481		index: 25,
482		}))
483		);
484
485		assert_eq!(
486		Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c"),
487		Err(Error(ErrorKind::ParseLength { len: 31 }))
488		);
489
490		assert_eq!(
491		Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c88"),
492		Err(Error(ErrorKind::ParseLength { len: 33 }))
493		);
494
495		assert_eq!(
496		Uuid::parse_str("67e5504410b1426f9247bb680e5fe0cg8"),
497		Err(Error(ErrorKind::ParseChar {
498		character: 'g',
499		index: 31,
500		}))
501		);
502
503		assert_eq!(
504		Uuid::parse_str("67e5504410b1426%9247bb680e5fe0c8"),
505		Err(Error(ErrorKind::ParseChar {
506		character: '%',
507		index: 15,
508		}))
509		);
510
511		assert_eq!(
512		Uuid::parse_str("231231212212423424324323477343246663"),
513		Err(Error(ErrorKind::ParseGroupCount { count: 1 }))
514		);
515
516		assert_eq!(
517		Uuid::parse_str("{00000000000000000000000000000000}"),
518		Err(Error(ErrorKind::ParseGroupCount { count: 1 }))
519		);
520
521		assert_eq!(
522		Uuid::parse_str("67e5504410b1426f9247bb680e5fe0c"),
523		Err(Error(ErrorKind::ParseLength { len: 31 }))
524		);
525
526		assert_eq!(
527		Uuid::parse_str("67e550X410b1426f9247bb680e5fe0cd"),
528		Err(Error(ErrorKind::ParseChar {
529		character: 'X',
530		index: 6,
531		}))
532		);
533
534		assert_eq!(
535		Uuid::parse_str("67e550-4105b1426f9247bb680e5fe0c"),
536		Err(Error(ErrorKind::ParseGroupCount { count: 2 }))
537		);
538
539		assert_eq!(
540		Uuid::parse_str("F9168C5E-CEB2-4faa-B6BF1-02BF39FA1E4"),
541		Err(Error(ErrorKind::ParseGroupLength {
542		group: 3,
543		len: 5,
544		index: 20,
545		}))
546		);
547
548		assert_eq!(
549		Uuid::parse_str("\u{bcf3c}"),
550		Err(Error(ErrorKind::ParseChar {
551		character: '\u{bcf3c}',
552		index: 0,
553		}))
554		);
555
556		assert_eq!(
557		Uuid::parse_str("\u{130}"),
558		Err(Error(ErrorKind::ParseChar {
559		character: '\u{130}',
560		index: 0,
561		}))
562		);
563
564		assert_eq!(
565		Err(Error(ErrorKind::ParseLength { len: 0 })),
566		Hyphenated::from_str("")
567		);
568
569		assert_eq!(
570		Err(Error(ErrorKind::ParseGroupCount { count: 1 })),
571		Hyphenated::from_str("550e8400e29b41d4a716446655440000")
572		);
573
574		assert_eq!(
575		Err(Error(ErrorKind::ParseChar {
576		character: '-',
577		index: 8
578		})),
579		Simple::from_str("550e8400-e29b-41d4-a716-446655440000")
580		);
581
582		assert_eq!(
583		Err(Error(ErrorKind::ParseChar {
584		character: '5',
585		index: 0
586		})),
587		Urn::from_str("550e8400-e29b-41d4-a716-446655440000")
588		);
589		assert_eq!(
590		Err(Error(ErrorKind::ParseChar {
591		character: ':',
592		index: 0
593		})),
594		Urn::from_str(":550e8400-e29b-41d4-a716-446655440000")
595		);
596		assert_eq!(
597		Uuid::parse_str("urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap(),
598		Urn::from_str("URN:UUID:67e55044-10b1-426f-9247-bb680e5fe0c8")
599		.unwrap()
600		.into_uuid()
601		);
602
603		assert_eq!(
604		Err(Error(ErrorKind::ParseChar {
605		character: '5',
606		index: 0
607		})),
608		Braced::from_str("550e8400-e29b-41d4-a716-446655440000")
609		);
610		assert_eq!(
611		Err(Error(ErrorKind::ParseChar {
612		character: '{',
613		index: 1
614		})),
615		Braced::from_str("{{550e8400-e29b-41d4-a716-446655440000}}")
616		);
617
618		// Unicode
619		assert_eq!(
620		Uuid::from_str("{6e0----------9=4O-0e5\u{14}e0c4\u{ec2f}8}"),
621		Err(Error(ErrorKind::ParseChar {
622		character: '=',
623		index: 15,
624		}))
625		);
626
627		assert_eq!(
628		Uuid::from_str("urn:uuid:urae0c8"),
629		Err(Error(ErrorKind::ParseChar {
630		character: 'u',
631		index: 9,
632		}))
633		);
634		}
635
636		#[test]
637		fn test_roundtrip_default() {
638		for uuid_orig in some_uuid_iter() {
639		let orig_str = uuid_orig.to_string();
640		let uuid_out = Uuid::parse_str(&orig_str).unwrap();
641		assert_eq!(uuid_orig, uuid_out);
642		}
643		}
644
645		#[test]
646		fn test_roundtrip_hyphenated() {
647		for uuid_orig in some_uuid_iter() {
648		let orig_str = uuid_orig.hyphenated().to_string();
649		let uuid_out = Uuid::parse_str(&orig_str).unwrap();
650		assert_eq!(uuid_orig, uuid_out);
651		}
652		}
653
654		#[test]
655		fn test_roundtrip_simple() {
656		for uuid_orig in some_uuid_iter() {
657		let orig_str = uuid_orig.simple().to_string();
658		let uuid_out = Uuid::parse_str(&orig_str).unwrap();
659		assert_eq!(uuid_orig, uuid_out);
660		}
661		}
662
663		#[test]
664		fn test_roundtrip_urn() {
665		for uuid_orig in some_uuid_iter() {
666		let orig_str = uuid_orig.urn().to_string();
667		let uuid_out = Uuid::parse_str(&orig_str).unwrap();
668		assert_eq!(uuid_orig, uuid_out);
669		}
670		}
671
672		#[test]
673		fn test_roundtrip_braced() {
674		for uuid_orig in some_uuid_iter() {
675		let orig_str = uuid_orig.braced().to_string();
676		let uuid_out = Uuid::parse_str(&orig_str).unwrap();
677		assert_eq!(uuid_orig, uuid_out);
678		}
679		}
680
681		#[test]
682		fn test_roundtrip_parse_urn() {
683		for uuid_orig in some_uuid_iter() {
684		let orig_str = uuid_orig.urn().to_string();
685		let uuid_out = Uuid::from_bytes(parse_urn(orig_str.as_bytes()).unwrap());
686		assert_eq!(uuid_orig, uuid_out);
687		}
688		}
689
690		#[test]
691		fn test_roundtrip_parse_braced() {
692		for uuid_orig in some_uuid_iter() {
693		let orig_str = uuid_orig.braced().to_string();
694		let uuid_out = Uuid::from_bytes(parse_braced(orig_str.as_bytes()).unwrap());
695		assert_eq!(uuid_orig, uuid_out);
696		}
697		}
698
699		#[test]
700		fn test_try_parse_ascii_non_utf8() {
701		assert!(Uuid::try_parse_ascii(b"67e55044-10b1-426f-9247-bb680e5\0e0c8").is_err());
702		}
703		}