gts-id 0.11.0

GTS ID validation and parsing primitives
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//! The error type shared across all GTS identifier and wildcard parsing.

use std::fmt;

/// Pinpoints the `~`-delimited segment at fault within a GTS identifier.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GtsIdSegmentError {
    /// 1-based segment number.
    pub num: usize,
    /// Byte offset of this segment within the full ID string.
    pub offset: usize,
    /// The raw segment string that failed parsing.
    pub segment: String,
}

/// Error from GTS identifier / wildcard parsing.
///
/// There is a single failure category — "this GTS string is invalid" —
/// described by [`cause`](Self::cause). [`segment`](Self::segment) is present
/// when the failure could be pinned to a specific `~`-delimited segment;
/// otherwise it is an identifier-level problem (prefix, case, length, wildcard
/// placement, the single-segment-instance rule, …).
///
/// The `gts` crate re-exports this type under its own name.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GtsIdError {
    /// The full GTS string (identifier or wildcard pattern) that failed.
    pub input: String,
    /// Human-readable description of the problem.
    pub cause: String,
    /// Set when a specific segment is at fault.
    pub segment: Option<GtsIdSegmentError>,
}

impl GtsIdError {
    /// Build an identifier-level error (no specific segment located).
    #[must_use]
    pub fn new(input: impl Into<String>, cause: impl Into<String>) -> Self {
        Self {
            input: input.into(),
            cause: cause.into(),
            segment: None,
        }
    }

    /// Attach the location of the offending `~`-segment.
    #[must_use]
    pub fn with_segment(mut self, num: usize, offset: usize, segment: impl Into<String>) -> Self {
        self.segment = Some(GtsIdSegmentError {
            num,
            offset,
            segment: segment.into(),
        });
        self
    }
}

impl fmt::Display for GtsIdError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.segment {
            Some(s) => write!(
                f,
                "Invalid GTS segment #{} @ offset {}: '{}': {}",
                s.num, s.offset, s.segment, self.cause
            ),
            None => write!(f, "Invalid GTS identifier: {}: {}", self.input, self.cause),
        }
    }
}

impl std::error::Error for GtsIdError {}