datetime-string 0.2.2

//! Time offset string in `+hh:mm` or `-hh:mm` format.
//!
//! This is also an RFC 3339 [`time-numoffset`].
//!
//! [`time-numoffset`]: https://tools.ietf.org/html/rfc3339#section-5.6

use core::{
    convert::TryFrom,
    fmt,
    ops::{self, Range, RangeTo},
    str,
};

use crate::{parse::parse_digits2, str::write_digit2};

#[cfg(feature = "alloc")]
use alloc::{string::String, vec::Vec};

use crate::common::TimeOffsetSign;

use crate::error::{ComponentKind, Error, ErrorKind};

/// Length of time-numoffset (e.g. "+12:34").
const NUM_OFFSET_LEN: usize = 6;
/// Range of the absolute hour in the string.
const HOUR_ABS_RANGE: Range<usize> = 1..3;
/// Range of the signed hour in the string.
const HOUR_SIGNED_RANGE: RangeTo<usize> = ..3;
/// Range of the minute in the string.
const MINUTE_RANGE: Range<usize> = 4..6;
/// Maximum value of the hour.
const HOUR_MAX: u8 = 23;
/// Maximum value of the minute.
const MINUTE_MAX: u8 = 59;

/// Validates the given string as an RFC 3339 [`time-numoffset`] string.
///
/// [`time-numoffset`]: https://tools.ietf.org/html/rfc3339#section-5.6
fn validate_bytes(s: &[u8]) -> Result<(), Error> {
    let s: &[u8; NUM_OFFSET_LEN] = TryFrom::try_from(s).map_err(|_| {
        if s.len() < NUM_OFFSET_LEN {
            ErrorKind::TooShort
        } else {
            ErrorKind::TooLong
        }
    })?;

    if ((s[0] != b'+') && (s[0] != b'-')) || (s[3] != b':') {
        return Err(ErrorKind::InvalidSeparator.into());
    }

    let hour_s: [u8; 2] = [s[1], s[2]];
    let minute_s: [u8; 2] = [s[4], s[5]];

    if !hour_s.iter().all(u8::is_ascii_digit) {
        return Err(ErrorKind::InvalidComponentType(ComponentKind::OffsetHour).into());
    }
    if !minute_s.iter().all(u8::is_ascii_digit) {
        return Err(ErrorKind::InvalidComponentType(ComponentKind::OffsetMinute).into());
    }

    let hour = parse_digits2(hour_s);
    if hour > HOUR_MAX {
        return Err(ErrorKind::ComponentOutOfRange(ComponentKind::OffsetHour).into());
    }
    let minute = parse_digits2(minute_s);
    if minute > MINUTE_MAX {
        return Err(ErrorKind::ComponentOutOfRange(ComponentKind::OffsetMinute).into());
    }

    Ok(())
}

/// String slice for a time offset in `+hh:mm` or `-hh:mm` format, such as `+09:00` and `-00:00`.
///
/// This is also an RFC 3339 [`time-numoffset`] string.
///
/// [`time-numoffset`]: https://tools.ietf.org/html/rfc3339#section-5.6
#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(transparent)]
// Note that `derive(Serialize)` cannot used here, because it encodes this as
// `[u8]` rather than as a string.
//
// Comparisons implemented for the type are consistent (at least it is intended to be so).
// See <https://github.com/rust-lang/rust-clippy/issues/2025>.
// Note that `clippy::derive_ord_xor_partial_ord` would be introduced since Rust 1.47.0.
#[allow(clippy::derive_hash_xor_eq)]
#[allow(unknown_lints, clippy::derive_ord_xor_partial_ord)]
pub struct TimeNumOffsetColonStr([u8]);

impl TimeNumOffsetColonStr {
    /// Creates a `&TimeNumOffsetColonStr` from the given byte slice.
    ///
    /// This performs assertion in debug build, but not in release build.
    ///
    /// # Safety
    ///
    /// `validate_bytes(s)` should return `Ok(())`.
    #[inline]
    #[must_use]
    pub(crate) unsafe fn from_bytes_maybe_unchecked(s: &[u8]) -> &Self {
        debug_assert_ok!(validate_bytes(s));
        &*(s as *const [u8] as *const Self)
    }

    /// Creates a `&mut TimeNumOffsetColonStr` from the given mutable byte slice.
    ///
    /// This performs assertion in debug build, but not in release build.
    ///
    /// # Safety
    ///
    /// `validate_bytes(s)` should return `Ok(())`.
    #[inline]
    #[must_use]
    pub(crate) unsafe fn from_bytes_maybe_unchecked_mut(s: &mut [u8]) -> &mut Self {
        debug_assert_ok!(validate_bytes(s));
        &mut *(s as *mut [u8] as *mut Self)
    }

    /// Creates a `&mut TimeNumOffsetColonStr` from the given mutable string slice.
    ///
    /// This performs assertion in debug build, but not in release build.
    ///
    /// # Safety
    ///
    /// `validate_bytes(s.as_bytes())` should return `Ok(())`.
    #[inline]
    #[must_use]
    unsafe fn from_str_maybe_unchecked_mut(s: &mut str) -> &mut Self {
        // This is safe because `TimeNumOffsetColonStr` ensures that the
        // underlying bytes are ASCII string after modification.
        Self::from_bytes_maybe_unchecked_mut(s.as_bytes_mut())
    }

    /// Creates a new `&TimeNumOffsetColonStr` from a string slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    /// assert_eq!(offset.as_str(), "-12:34");
    ///
    /// assert!(TimeNumOffsetColonStr::from_str("+00:00").is_ok());
    /// assert!(TimeNumOffsetColonStr::from_str("+23:59").is_ok());
    /// assert!(TimeNumOffsetColonStr::from_str("-00:00").is_ok());
    /// assert!(TimeNumOffsetColonStr::from_str("-23:59").is_ok());
    ///
    /// assert!(TimeNumOffsetColonStr::from_str("Z").is_err(), "Not time-numoffset");
    /// assert!(TimeNumOffsetColonStr::from_str("+24:00").is_err(), "Invalid hour");
    /// assert!(TimeNumOffsetColonStr::from_str("+00:60").is_err(), "Invalid minute");
    /// assert!(TimeNumOffsetColonStr::from_str("-24:00").is_err(), "Invalid hour");
    /// assert!(TimeNumOffsetColonStr::from_str("-00:60").is_err(), "Invalid minute");
    /// assert!(TimeNumOffsetColonStr::from_str("?00:00").is_err(), "Invalid sign");
    /// assert!(TimeNumOffsetColonStr::from_str("00:00").is_err(), "Sign is missing");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    // `FromStr` trait cannot be implemented for a slice.
    #[allow(clippy::should_implement_trait)]
    pub fn from_str(s: &str) -> Result<&Self, Error> {
        TryFrom::try_from(s)
    }

    /// Creates a new `&mut TimeNumOffsetColonStr` from a mutable string slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    /// let mut buf = "-12:34".to_owned();
    /// let offset = TimeNumOffsetColonStr::from_mut_str(&mut buf)?;
    /// assert_eq!(offset.as_str(), "-12:34");
    ///
    /// offset.set_sign(TimeOffsetSign::Positive);
    /// assert_eq!(offset.as_str(), "+12:34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn from_mut_str(s: &mut str) -> Result<&mut Self, Error> {
        TryFrom::try_from(s)
    }

    /// Creates a new `&TimeNumOffsetColonStr` from a byte slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_bytes(b"-12:34")?;
    /// assert_eq!(offset.as_str(), "-12:34");
    ///
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"+00:00").is_ok());
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"+23:59").is_ok());
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"-00:00").is_ok());
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"-23:59").is_ok());
    ///
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"Z").is_err(), "Not time-numoffset");
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"+24:00").is_err(), "Invalid hour");
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"+00:60").is_err(), "Invalid minute");
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"-24:00").is_err(), "Invalid hour");
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"-00:60").is_err(), "Invalid minute");
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"?00:00").is_err(), "Invalid sign");
    /// assert!(TimeNumOffsetColonStr::from_bytes(b"00:00").is_err(), "Sign is missing");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn from_bytes(s: &[u8]) -> Result<&Self, Error> {
        TryFrom::try_from(s)
    }

    /// Creates a new `&mut TimeNumOffsetColonStr` from a mutable byte slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let offset = TimeNumOffsetColonStr::from_bytes_mut(&mut buf)?;
    /// assert_eq!(offset.as_str(), "-12:34");
    ///
    /// offset.set_sign(TimeOffsetSign::Positive);
    /// assert_eq!(offset.as_str(), "+12:34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn from_bytes_mut(s: &mut [u8]) -> Result<&mut Self, Error> {
        TryFrom::try_from(s)
    }

    /// Assigns the given value.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let mut buf: [u8; 6] = *b"+09:00";
    /// let offset = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(offset.as_str(), "+09:00");
    ///
    /// let newoffset = TimeNumOffsetColonStr::from_str("-00:00")?;
    ///
    /// offset.assign(newoffset);
    /// assert_eq!(offset.as_str(), "-00:00");
    /// assert_eq!(buf, *b"-00:00");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn assign(&mut self, v: &Self) {
        debug_assert_eq!(self.0.len(), v.0.len());
        self.0.copy_from_slice(&v.0);
    }

    /// Returns a string slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.as_str(), "-12:34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        unsafe {
            // This is safe because `TimeNumOffsetColonStr` ensures that the
            // underlying bytes are ASCII string.
            debug_assert_safe_version_ok!(str::from_utf8(&self.0));
            str::from_utf8_unchecked(&self.0)
        }
    }

    /// Returns a byte slice.
    ///
    /// If you want to use indexed access, prefer [`as_bytes_fixed_len`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_bytes(b"-12:34")?;
    ///
    /// assert_eq!(offset.as_bytes(), b"-12:34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    ///
    /// [`as_bytes_fixed_len`]: #method.as_bytes_fixed_len
    #[inline]
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Returns a fixed length byte slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// let fixed_len: &[u8; 6] = offset.as_bytes_fixed_len();
    /// assert_eq!(fixed_len, b"-12:34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn as_bytes_fixed_len(&self) -> &[u8; 6] {
        debug_assert_eq!(
            self.len(),
            NUM_OFFSET_LEN,
            "TimeNumOffsetColonStr must always be 6 bytes"
        );

        debug_assert_safe_version_ok!(<&[u8; NUM_OFFSET_LEN]>::try_from(&self.0));
        let ptr = self.0.as_ptr() as *const [u8; NUM_OFFSET_LEN];
        // This must be always safe because the length is already checked.
        unsafe { &*ptr }
    }

    /// Returns the time offset sign.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let positive = TimeNumOffsetColonStr::from_str("+12:34")?;
    /// assert_eq!(positive.sign(), TimeOffsetSign::Positive);
    ///
    /// let negative = TimeNumOffsetColonStr::from_str("-12:34")?;
    /// assert_eq!(negative.sign(), TimeOffsetSign::Negative);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    ///
    /// Note that signs are preserved for `+00:00` and `-00:00`.
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let positive0 = TimeNumOffsetColonStr::from_str("+00:00")?;
    /// assert_eq!(positive0.sign(), TimeOffsetSign::Positive);
    ///
    /// let negative0 = TimeNumOffsetColonStr::from_str("-00:00")?;
    /// assert_eq!(negative0.sign(), TimeOffsetSign::Negative);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn sign(&self) -> TimeOffsetSign {
        if self.as_bytes()[0] == b'+' {
            TimeOffsetSign::Positive
        } else {
            debug_assert_eq!(self.0[0], b'-');
            TimeOffsetSign::Negative
        }
    }

    /// Returns a mutable reference to the byte which contains the sign character.
    ///
    /// # Safety
    ///
    /// The returned byte should have `b'+'` or `b'-'`.
    /// If other values are stored, it may lead to undefined behavior.
    #[inline]
    #[must_use]
    unsafe fn sign_byte_mut(&mut self) -> &mut u8 {
        debug_assert_safe_version_some!(self.0.get(0));
        self.0.get_unchecked_mut(0)
    }

    /// Sets the given sign.
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let mut buf = "-12:34".to_owned();
    /// let offset = TimeNumOffsetColonStr::from_mut_str(&mut buf)?;
    /// assert_eq!(offset.as_str(), "-12:34");
    /// assert_eq!(offset.sign(), TimeOffsetSign::Negative);
    ///
    /// offset.set_sign(TimeOffsetSign::Positive);
    /// assert_eq!(offset.as_str(), "+12:34");
    /// assert_eq!(offset.sign(), TimeOffsetSign::Positive);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn set_sign(&mut self, sign: TimeOffsetSign) {
        let byte = match sign {
            TimeOffsetSign::Positive => b'+',
            TimeOffsetSign::Negative => b'-',
        };
        unsafe {
            // This is safe because a valid time-numoffset is also an ASCII string,
            // and the substituted value (`byte`) is also an ASCII character.
            *self.sign_byte_mut() = byte;
        }
        debug_assert_ok!(validate_bytes(&self.0));
        debug_assert_eq!(self.sign(), sign);
    }

    /// Returns the absolute hour as a string slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.hour_abs_str(), "12");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn hour_abs_str(&self) -> &str {
        unsafe {
            // This is safe because the string is ASCII string and
            // `HOUR_ABS_RANGE` is always inside the string.
            debug_assert_safe_version_ok!(str::from_utf8(&self.0[HOUR_ABS_RANGE]));
            str::from_utf8_unchecked(self.0.get_unchecked(HOUR_ABS_RANGE))
        }
    }

    /// Returns the absolute hour as a fixed length byte slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// let hour_fixed_len: &[u8; 2] = offset.hour_abs_bytes_fixed_len();
    /// assert_eq!(hour_fixed_len, b"12");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn hour_abs_bytes_fixed_len(&self) -> &[u8; 2] {
        unsafe {
            // This is safe because `HOUR_ABS_RANGE` fits inside the string.
            debug_assert_safe_version_ok!(<&[u8; 2]>::try_from(&self.0[HOUR_ABS_RANGE]));
            let ptr = self.0.as_ptr().add(HOUR_ABS_RANGE.start) as *const [u8; 2];
            &*ptr
        }
    }

    /// Returns the absolute hour as a fixed length mutable byte slice.
    ///
    /// # Safety
    ///
    /// The returned slice should have only ASCII digits.
    /// If non-ASCII digits are stored, it may lead to undefined behavior.
    #[inline]
    #[must_use]
    unsafe fn hour_abs_bytes_mut_fixed_len(&mut self) -> &mut [u8; 2] {
        // This is safe because `HOUR_ABS_RANGE` fits inside the string.
        debug_assert_ok!(<&[u8; 2]>::try_from(&self.0[HOUR_ABS_RANGE]));
        let ptr = self.0.as_mut_ptr().add(HOUR_ABS_RANGE.start) as *mut [u8; 2];
        &mut *ptr
    }

    /// Returns the absolute hour as an integer.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.hour_abs(), 12);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn hour_abs(&self) -> u8 {
        parse_digits2(*self.hour_abs_bytes_fixed_len())
    }

    /// Sets the given absolute hour value to the string.
    ///
    /// # Failures
    ///
    /// * Fails if the time after modification is invalid.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_hour_abs(0)?;
    /// assert_eq!(time.as_str(), "-00:34");
    ///
    /// assert!(time.set_hour_abs(24).is_err(), "-24:34 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn set_hour_abs(&mut self, hour_abs: u8) -> Result<(), Error> {
        if hour_abs > HOUR_MAX {
            return Err(ErrorKind::ComponentOutOfRange(ComponentKind::OffsetHour).into());
        }
        unsafe {
            // This is safe because `write_digit2()` fills the slice with ASCII digits.
            write_digit2(self.hour_abs_bytes_mut_fixed_len(), hour_abs);
        }
        debug_assert_ok!(validate_bytes(&self.0));

        Ok(())
    }

    /// Returns the signed hour as a string slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.hour_signed_str(), "-12");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn hour_signed_str(&self) -> &str {
        unsafe {
            // This is safe because the string is ASCII string and
            // `HOUR_SIGNED_RANGE` is always inside the string.
            debug_assert_safe_version_ok!(str::from_utf8(&self.0[HOUR_SIGNED_RANGE]));
            str::from_utf8_unchecked(self.0.get_unchecked(HOUR_SIGNED_RANGE))
        }
    }

    /// Returns the signed hour as a fixed length byte slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// let hour_fixed_len: &[u8; 3] = offset.hour_signed_bytes_fixed_len();
    /// assert_eq!(hour_fixed_len, b"-12");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn hour_signed_bytes_fixed_len(&self) -> &[u8; 3] {
        debug_assert_safe_version_ok!(<&[u8; 3]>::try_from(&self.0[HOUR_SIGNED_RANGE]));
        let ptr = self.0[HOUR_SIGNED_RANGE].as_ptr() as *const [u8; 3];
        // This must be always safe because the string is valid time-numoffset string.
        unsafe { &*ptr }
    }

    /// Returns the signed hour as an integer.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.hour_signed(), -12);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    ///
    /// Note that both `+00` and `-00` are treaded as the same 0.
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let positive = TimeNumOffsetColonStr::from_str("+00:59")?;
    /// assert_eq!(positive.hour_signed(), 0);
    ///
    /// let negative = TimeNumOffsetColonStr::from_str("-00:59")?;
    /// assert_eq!(negative.hour_signed(), 0);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn hour_signed(&self) -> i8 {
        let abs = self.hour_abs() as i8;
        match self.sign() {
            TimeOffsetSign::Positive => abs,
            TimeOffsetSign::Negative => -abs,
        }
    }

    /// Sets the given absolute hour value and sign to the string.
    ///
    /// # Failures
    ///
    /// * Fails if the time after modification is invalid.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_sign_and_hour_abs(TimeOffsetSign::Positive, 23)?;
    /// assert_eq!(time.as_str(), "+23:34");
    ///
    /// assert!(time.set_sign_and_hour_abs(TimeOffsetSign::Negative, 24).is_err(), "-24:34 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn set_sign_and_hour_abs(
        &mut self,
        sign: TimeOffsetSign,
        hour_abs: u8,
    ) -> Result<(), Error> {
        self.set_hour_abs(hour_abs)?;
        self.set_sign(sign);
        debug_assert_ok!(validate_bytes(&self.0));

        Ok(())
    }

    /// Sets the given signed hour value to the string.
    ///
    /// If `0` is passed, it is always considered as positive 0.
    ///
    /// # Failures
    ///
    /// * Fails if the time after modification is invalid.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_hour_signed(0)?;
    /// assert_eq!(time.as_str(), "+00:34");
    ///
    /// time.set_hour_signed(-1)?;
    /// assert_eq!(time.as_str(), "-01:34");
    ///
    /// assert!(time.set_hour_signed(24).is_err(), "+24:34 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn set_hour_signed(&mut self, hour: i8) -> Result<(), Error> {
        let sign = if hour >= 0 {
            TimeOffsetSign::Positive
        } else {
            TimeOffsetSign::Negative
        };
        let hour_abs = hour.wrapping_abs() as u8;

        self.set_sign_and_hour_abs(sign, hour_abs)
    }

    /// Returns the minute as a string slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.minute_str(), "34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn minute_str(&self) -> &str {
        unsafe {
            // This is safe because the string is ASCII string and
            // `MINUTE_RANGE` is always inside the string.
            debug_assert_safe_version_ok!(str::from_utf8(&self.0[MINUTE_RANGE]));
            str::from_utf8_unchecked(self.0.get_unchecked(MINUTE_RANGE))
        }
    }

    /// Returns the minute as a fixed length byte slice.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// let minute_fixed_len: &[u8; 2] = offset.minute_bytes_fixed_len();
    /// assert_eq!(minute_fixed_len, b"34");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn minute_bytes_fixed_len(&self) -> &[u8; 2] {
        unsafe {
            // This is safe because `MINUTE_RANGE` fits inside the string.
            debug_assert_safe_version_ok!(<&[u8; 2]>::try_from(&self.0[MINUTE_RANGE]));
            let ptr = self.0.as_ptr().add(MINUTE_RANGE.start) as *const [u8; 2];
            &*ptr
        }
    }

    /// Returns the minute as a fixed length mutable byte slice.
    ///
    /// # Safety
    ///
    /// The returned slice should have only ASCII digits.
    /// If non-ASCII digits are stored, it may lead to undefined behavior.
    #[inline]
    #[must_use]
    unsafe fn minute_bytes_mut_fixed_len(&mut self) -> &mut [u8; 2] {
        // This is safe because `MINUTE_RANGE` fits inside the string.
        debug_assert_ok!(<&[u8; 2]>::try_from(&self.0[MINUTE_RANGE]));
        let ptr = self.0.as_mut_ptr().add(MINUTE_RANGE.start) as *mut [u8; 2];
        &mut *ptr
    }

    /// Returns the minute as an integer.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.minute(), 34);
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn minute(&self) -> u8 {
        parse_digits2(*self.minute_bytes_fixed_len())
    }

    /// Sets the given minute value to the string.
    ///
    /// # Failures
    ///
    /// * Fails if the time after modification is invalid.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_minute(01)?;
    /// assert_eq!(time.as_str(), "-12:01");
    ///
    /// assert!(time.set_minute(60).is_err(), "-12:60 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn set_minute(&mut self, minute: u8) -> Result<(), Error> {
        if minute > MINUTE_MAX {
            return Err(ErrorKind::ComponentOutOfRange(ComponentKind::OffsetMinute).into());
        }
        unsafe {
            // This is safe because `write_digit2()` fills the slice with ASCII digits.
            write_digit2(self.minute_bytes_mut_fixed_len(), minute);
        }
        debug_assert_ok!(validate_bytes(&self.0));

        Ok(())
    }

    /// Sets the given signed hour and minute value to the string.
    ///
    /// If `0` is passed, it is always considered as positive 0.
    ///
    /// # Failures
    ///
    /// * Fails if the time after modification is invalid.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_time_signed(0, 56)?;
    /// assert_eq!(time.as_str(), "+00:56");
    ///
    /// time.set_time_signed(-1, 23)?;
    /// assert_eq!(time.as_str(), "-01:23");
    ///
    /// assert!(time.set_time_signed(24, 00).is_err(), "+24:00 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    pub fn set_time_signed(&mut self, hour: i8, minute: u8) -> Result<(), Error> {
        let hour_abs = hour.wrapping_abs() as u8;
        let sign = if hour >= 0 {
            TimeOffsetSign::Positive
        } else {
            TimeOffsetSign::Negative
        };

        self.set_sign_and_time(sign, hour_abs, minute)
    }

    /// Sets the given sign, absolute hour, and minute value to the string.
    ///
    /// If `0` is passed, it is always considered as positive 0.
    ///
    /// # Failures
    ///
    /// * Fails if the time after modification is invalid.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_sign_and_time(TimeOffsetSign::Negative, 0, 56)?;
    /// assert_eq!(time.as_str(), "-00:56");
    ///
    /// time.set_sign_and_time(TimeOffsetSign::Positive, 1, 23)?;
    /// assert_eq!(time.as_str(), "+01:23");
    ///
    /// assert!(time.set_sign_and_time(TimeOffsetSign::Positive, 24, 00).is_err(), "+24:00 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    pub fn set_sign_and_time(
        &mut self,
        sign: TimeOffsetSign,
        hour_abs: u8,
        minute: u8,
    ) -> Result<(), Error> {
        if hour_abs > HOUR_MAX {
            return Err(ErrorKind::ComponentOutOfRange(ComponentKind::OffsetHour).into());
        }
        if minute > MINUTE_MAX {
            return Err(ErrorKind::ComponentOutOfRange(ComponentKind::OffsetMinute).into());
        }

        self.set_sign(sign);
        unsafe {
            // This is safe because `write_digit2()` fills the slice with ASCII digits.
            write_digit2(self.hour_abs_bytes_mut_fixed_len(), hour_abs);
            write_digit2(self.minute_bytes_mut_fixed_len(), minute);
        }
        debug_assert_ok!(validate_bytes(&self.0));

        Ok(())
    }

    /// Returns the time offset in minutes.
    ///
    /// Note that both `+00:00` and `-00:00` is considered as 0 minutes offset.
    /// RFC 3339 defines semantics of `-00:00` as "unknown local offset".
    /// If your application should be aware of that semantics, use
    /// [`is_unknown_local_offset`] method or [`sign`] method to distinguish them.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let offset = TimeNumOffsetColonStr::from_str("-12:34")?;
    ///
    /// assert_eq!(offset.in_minutes(), -(12 * 60 + 34));
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    ///
    /// `0` is returned for both `+00:00` and `-00:00`.
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let positive0 = TimeNumOffsetColonStr::from_str("+00:00")?;
    /// assert_eq!(positive0.in_minutes(), 0);
    /// assert_eq!(positive0.sign(), TimeOffsetSign::Positive);
    /// assert!(!positive0.is_unknown_local_offset(), "0 minutes time offset");
    ///
    /// let negative0 = TimeNumOffsetColonStr::from_str("-00:00")?;
    /// assert_eq!(negative0.in_minutes(), 0);
    /// assert_eq!(negative0.sign(), TimeOffsetSign::Negative);
    /// assert!(negative0.is_unknown_local_offset(), "unknown local offset");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    ///
    /// [`is_unknown_local_offset`]: TimeNumOffsetColonStr::is_unknown_local_offset
    /// [`sign`]: TimeNumOffsetColonStr::sign
    #[must_use]
    pub fn in_minutes(&self) -> i16 {
        let abs_min = self.hour_abs() as i16 * 60 + self.minute() as i16;
        match self.sign() {
            TimeOffsetSign::Positive => abs_min,
            TimeOffsetSign::Negative => -abs_min,
        }
    }

    /// Sets the time offset for the given offset in minutes.
    ///
    /// # Failures
    ///
    /// * Fails if the value is invalid as time offset, i.e. it is not between
    ///   -1440 and 1440.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// let mut buf: [u8; 6] = *b"-12:34";
    /// let time = TimeNumOffsetColonStr::from_bytes_mut(&mut buf[..])?;
    /// assert_eq!(time.as_str(), "-12:34");
    ///
    /// time.set_in_minutes(9 * 60)?;
    /// assert_eq!(time.as_str(), "+09:00");
    ///
    /// time.set_in_minutes(0)?;
    /// assert_eq!(time.as_str(), "+00:00");
    ///
    /// assert!(time.set_in_minutes(-24 * 60).is_err(), "-24:00 is invalid");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    pub fn set_in_minutes(&mut self, v: i16) -> Result<(), Error> {
        /// Maximum allowed absolute value of minutes.
        const IN_MINUTES_MAX: i16 = HOUR_MAX as i16 * 60 + MINUTE_MAX as i16;

        if (v < -IN_MINUTES_MAX) || (v > IN_MINUTES_MAX) {
            return Err(ErrorKind::ComponentOutOfRange(ComponentKind::Offset).into());
        }

        let sign = if v < 0 {
            TimeOffsetSign::Negative
        } else {
            TimeOffsetSign::Positive
        };
        // The valid time offset does not overflow on `.abs()`.
        let v = v.abs();
        let hour_abs = (v / 60) as u8;
        let minute = (v % 60) as u8;

        self.set_sign_and_time(sign, hour_abs, minute)
    }

    /// Returns `true` if and only if the time offset means "unknown local offset" in RFC 3339.
    ///
    /// RFC 3339 defines `-00:00` as "unknown local offset".
    ///
    /// > If the time in UTC is known, but the offset to local time is unknown,
    /// > this can be represented with an offset of "-00:00".
    /// > This differs semantically from an offset of "Z" or "+00:00", which
    /// > imply that UTC is the preferred reference point for the specified
    /// > time.
    /// >
    /// > --- [RFC 3339, section 4.3. Unknown Local Offset Convention][rfc3339-4-3]
    ///
    /// This method returns `true` for `-00:00`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonStr;
    /// use datetime_string::common::TimeOffsetSign;
    ///
    /// let positive0 = TimeNumOffsetColonStr::from_str("+00:00")?;
    /// assert!(!positive0.is_unknown_local_offset(), "0 minutes time offset");
    ///
    /// let negative0 = TimeNumOffsetColonStr::from_str("-00:00")?;
    /// assert!(negative0.is_unknown_local_offset(), "unknown local offset");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    ///
    /// [rfc3339-4-3]: https://tools.ietf.org/html/rfc3339#section-4.3
    #[inline]
    #[must_use]
    pub fn is_unknown_local_offset(&self) -> bool {
        &self.0 == b"-00:00"
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl alloc::borrow::ToOwned for TimeNumOffsetColonStr {
    type Owned = TimeNumOffsetColonString;

    #[inline]
    fn to_owned(&self) -> Self::Owned {
        self.into()
    }
}

impl AsRef<[u8]> for TimeNumOffsetColonStr {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        self.as_bytes()
    }
}

impl AsRef<str> for TimeNumOffsetColonStr {
    #[inline]
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl AsRef<TimeNumOffsetColonStr> for TimeNumOffsetColonStr {
    #[inline]
    fn as_ref(&self) -> &TimeNumOffsetColonStr {
        self
    }
}

impl AsMut<TimeNumOffsetColonStr> for TimeNumOffsetColonStr {
    #[inline]
    fn as_mut(&mut self) -> &mut TimeNumOffsetColonStr {
        self
    }
}

impl<'a> From<&'a TimeNumOffsetColonStr> for &'a str {
    #[inline]
    fn from(v: &'a TimeNumOffsetColonStr) -> Self {
        v.as_str()
    }
}

#[cfg(feature = "chrono04")]
#[cfg_attr(docsrs, doc(cfg(feature = "chrono04")))]
impl From<&TimeNumOffsetColonStr> for chrono04::FixedOffset {
    #[inline]
    fn from(v: &TimeNumOffsetColonStr) -> Self {
        Self::east(i32::from(v.in_minutes()) * 60)
    }
}

#[cfg(feature = "time03")]
#[cfg_attr(docsrs, doc(cfg(feature = "time03")))]
impl From<&TimeNumOffsetColonStr> for time03::UtcOffset {
    #[inline]
    fn from(v: &TimeNumOffsetColonStr) -> Self {
        // `TimeNumOffsetColonStr` can represent `-23:59` to `+23:59`.
        // `time03::UtcOffset` can represent `-23:59:59` to `+23:59:59`.
        // So this conversion should never fail.
        Self::from_whole_seconds(i32::from(v.in_minutes()) * 60)
            .expect("[validity] `time03::UtcOffset` can represent `-23:59:59` to `+23:59:59`")
    }
}

impl<'a> TryFrom<&'a [u8]> for &'a TimeNumOffsetColonStr {
    type Error = Error;

    #[inline]
    fn try_from(v: &'a [u8]) -> Result<Self, Self::Error> {
        validate_bytes(v)?;
        Ok(unsafe {
            // This is safe because a valid time-numoffset string is also an ASCII string.
            TimeNumOffsetColonStr::from_bytes_maybe_unchecked(v)
        })
    }
}

impl<'a> TryFrom<&'a mut [u8]> for &'a mut TimeNumOffsetColonStr {
    type Error = Error;

    #[inline]
    fn try_from(v: &'a mut [u8]) -> Result<Self, Self::Error> {
        validate_bytes(v)?;
        Ok(unsafe {
            // This is safe because a valid time-numoffset string is also an ASCII string.
            TimeNumOffsetColonStr::from_bytes_maybe_unchecked_mut(v)
        })
    }
}

impl<'a> TryFrom<&'a str> for &'a TimeNumOffsetColonStr {
    type Error = Error;

    #[inline]
    fn try_from(v: &'a str) -> Result<Self, Self::Error> {
        Self::try_from(v.as_bytes())
    }
}

impl<'a> TryFrom<&'a mut str> for &'a mut TimeNumOffsetColonStr {
    type Error = Error;

    #[inline]
    fn try_from(v: &'a mut str) -> Result<Self, Self::Error> {
        validate_bytes(v.as_bytes())?;
        Ok(unsafe {
            // This is safe because a valid time-numoffset string is also an ASCII string.
            TimeNumOffsetColonStr::from_str_maybe_unchecked_mut(v)
        })
    }
}

impl fmt::Display for TimeNumOffsetColonStr {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.as_str().fmt(f)
    }
}

impl ops::Deref for TimeNumOffsetColonStr {
    type Target = str;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.as_str()
    }
}

impl_cmp_symmetric!(str, TimeNumOffsetColonStr, &TimeNumOffsetColonStr);
impl_cmp_symmetric!([u8], TimeNumOffsetColonStr, [u8]);
impl_cmp_symmetric!([u8], TimeNumOffsetColonStr, &[u8]);
impl_cmp_symmetric!([u8], &TimeNumOffsetColonStr, [u8]);
impl_cmp_symmetric!(str, TimeNumOffsetColonStr, str);
impl_cmp_symmetric!(str, TimeNumOffsetColonStr, &str);
impl_cmp_symmetric!(str, &TimeNumOffsetColonStr, str);

#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
impl serde::Serialize for TimeNumOffsetColonStr {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

/// Owned string for a time offset in `+hh:mm` or `-hh:mm` format, such as `+09:00` and `-00:00`.
///
/// This is also an RFC 3339 [`time-numoffset`] string.
///
/// This is a fixed length string, and implements [`Copy`] trait.
///
/// To create a value of this type, use [`str::parse`] method or
/// [`std::convert::TryFrom`] trait, or convert from `&TimeNumOffsetColonStr`.
///
/// # Examples
///
/// ```
/// # use datetime_string::common::TimeNumOffsetColonString;
/// use datetime_string::common::TimeNumOffsetColonStr;
/// use std::convert::TryFrom;
///
/// let try_from = TimeNumOffsetColonString::try_from("-12:34")?;
///
/// let parse = "-12:34".parse::<TimeNumOffsetColonString>()?;
/// let parse2: TimeNumOffsetColonString = "-12:34".parse()?;
///
/// let to_owned = TimeNumOffsetColonStr::from_str("-12:34")?.to_owned();
/// let into: TimeNumOffsetColonString = TimeNumOffsetColonStr::from_str("-12:34")?.into();
/// # Ok::<_, datetime_string::Error>(())
/// ```
///
/// [`time-numoffset`]: https://tools.ietf.org/html/rfc3339#section-5.6
// Note that `derive(Serialize)` cannot used here, because it encodes this as
// `[u8; 6]` rather than as a string.
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(transparent)]
// Comparisons implemented for the type are consistent (at least it is intended to be so).
// See <https://github.com/rust-lang/rust-clippy/issues/2025>.
// Note that `clippy::derive_ord_xor_partial_ord` would be introduced since Rust 1.47.0.
#[allow(clippy::derive_hash_xor_eq)]
#[allow(unknown_lints, clippy::derive_ord_xor_partial_ord)]
pub struct TimeNumOffsetColonString([u8; NUM_OFFSET_LEN]);

impl TimeNumOffsetColonString {
    /// Creates a `TimeNumOffsetColonString` from the given bytes.
    ///
    /// # Safety
    ///
    /// `validate_bytes(&s)` should return `Ok(())`.
    #[inline]
    #[must_use]
    unsafe fn new_maybe_unchecked(s: [u8; 6]) -> Self {
        debug_assert_ok!(validate_bytes(&s));
        Self(s)
    }

    /// Returns `+00:00`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// let utc = TimeNumOffsetColonString::utc();
    /// assert_eq!(utc.as_str(), "+00:00");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn utc() -> Self {
        unsafe {
            // This is safe because `+00:00` is valid.
            debug_assert_safe_version_ok!(Self::try_from(*b"+00:00"));
            Self::new_maybe_unchecked(*b"+00:00")
        }
    }

    /// Returns `-00:00`, which is defined in RFC 3339 to indicate "unknown local offset".
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// let unknown_local_offset = TimeNumOffsetColonString::unknown_local_offset();
    /// assert_eq!(unknown_local_offset.as_str(), "-00:00");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn unknown_local_offset() -> Self {
        unsafe {
            // This is safe because `-00:00` is valid.
            debug_assert_safe_version_ok!(Self::try_from(*b"-00:00"));
            Self::new_maybe_unchecked(*b"-00:00")
        }
    }

    /// Creates a new `TimeNumOffsetColonStr` from the given minutes.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// let time = TimeNumOffsetColonString::from_minutes(9 * 60)?;
    /// assert_eq!(time.as_str(), "+09:00");
    ///
    /// assert!(TimeNumOffsetColonString::from_minutes(-24 * 60).is_err(), "-24:00 is invaild time");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    pub fn from_minutes(minutes: i16) -> Result<Self, Error> {
        let mut v = Self::utc();
        v.set_in_minutes(minutes)?;
        Ok(v)
    }

    /// Creates a new `TimeNumOffsetColonStr` from the given minutes.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// use datetime_string::common::TimeOffsetSign;
    /// let time = TimeNumOffsetColonString::from_sign_and_hm(TimeOffsetSign::Positive, 9, 30)?;
    /// assert_eq!(time.as_str(), "+09:30");
    ///
    /// let unknown_local_offset = TimeNumOffsetColonString::from_sign_and_hm(TimeOffsetSign::Negative, 0, 0)?;
    /// assert_eq!(unknown_local_offset.as_str(), "-00:00");
    ///
    /// assert!(
    ///     TimeNumOffsetColonString::from_sign_and_hm(TimeOffsetSign::Negative, 24, 0).is_err(),
    ///     "-24:00 is invaild time"
    /// );
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    pub fn from_sign_and_hm(sign: TimeOffsetSign, hour_abs: u8, minute: u8) -> Result<Self, Error> {
        let mut v = Self::utc();
        v.set_sign_and_time(sign, hour_abs, minute)?;
        Ok(v)
    }

    /// Creates a new `TimeNumOffsetColonStr` from the given minutes.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// let offset = TimeNumOffsetColonString::from_hm_signed(-9, 0)?;
    /// assert_eq!(offset.as_str(), "-09:00");
    ///
    /// let unknown_local_offset = TimeNumOffsetColonString::from_hm_signed(0, 0)?;
    /// assert_eq!(unknown_local_offset.as_str(), "+00:00");
    ///
    /// assert!( TimeNumOffsetColonString::from_hm_signed(-24, 0).is_err(), "-24:00 is invaild time");
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    pub fn from_hm_signed(hour: i8, minute: u8) -> Result<Self, Error> {
        let mut v = Self::utc();
        v.set_time_signed(hour, minute)?;
        Ok(v)
    }

    /// Returns a `&TimeNumOffsetColonStr` for the string.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// use datetime_string::common::TimeNumOffsetColonStr;
    ///
    /// let offset = "-12:34".parse::<TimeNumOffsetColonString>()?;
    ///
    /// // Usually you don't need to call `as_deref()` explicitly, because
    /// // `Deref<Target = TimeNumOffsetColonStr>` trait is implemented.
    /// let _: &TimeNumOffsetColonStr = offset.as_deref();
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn as_deref(&self) -> &TimeNumOffsetColonStr {
        unsafe {
            // This is safe because `self.0` is valid time-numoffset string.
            debug_assert_ok!(TimeNumOffsetColonStr::from_bytes(&self.0));
            TimeNumOffsetColonStr::from_bytes_maybe_unchecked(&self.0)
        }
    }

    /// Returns a `&mut TimeNumOffsetColonStr` for the string.
    ///
    /// # Examples
    ///
    /// ```
    /// # use datetime_string::common::TimeNumOffsetColonString;
    /// use datetime_string::common::TimeNumOffsetColonStr;
    ///
    /// let mut offset = "-12:34".parse::<TimeNumOffsetColonString>()?;
    ///
    /// // Usually you don't need to call `as_deref_mut()` explicitly, because
    /// // `DerefMut` trait is implemented.
    /// let _: &mut TimeNumOffsetColonStr = offset.as_deref_mut();
    /// # Ok::<_, datetime_string::Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn as_deref_mut(&mut self) -> &mut TimeNumOffsetColonStr {
        unsafe {
            // This is safe because `self.0` is valid time-numoffset string.
            debug_assert_ok!(TimeNumOffsetColonStr::from_bytes(&self.0));
            TimeNumOffsetColonStr::from_bytes_maybe_unchecked_mut(&mut self.0)
        }
    }
}

impl core::borrow::Borrow<TimeNumOffsetColonStr> for TimeNumOffsetColonString {
    #[inline]
    fn borrow(&self) -> &TimeNumOffsetColonStr {
        self.as_deref()
    }
}

impl core::borrow::BorrowMut<TimeNumOffsetColonStr> for TimeNumOffsetColonString {
    #[inline]
    fn borrow_mut(&mut self) -> &mut TimeNumOffsetColonStr {
        self.as_deref_mut()
    }
}

impl AsRef<[u8]> for TimeNumOffsetColonString {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        self.as_bytes()
    }
}

impl AsRef<str> for TimeNumOffsetColonString {
    #[inline]
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl AsRef<TimeNumOffsetColonStr> for TimeNumOffsetColonString {
    #[inline]
    fn as_ref(&self) -> &TimeNumOffsetColonStr {
        self
    }
}

impl AsMut<TimeNumOffsetColonStr> for TimeNumOffsetColonString {
    #[inline]
    fn as_mut(&mut self) -> &mut TimeNumOffsetColonStr {
        self
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl From<TimeNumOffsetColonString> for Vec<u8> {
    #[inline]
    fn from(v: TimeNumOffsetColonString) -> Vec<u8> {
        (*v.as_bytes_fixed_len()).into()
    }
}

#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
impl From<TimeNumOffsetColonString> for String {
    #[inline]
    fn from(v: TimeNumOffsetColonString) -> String {
        let vec: Vec<u8> = (*v.as_bytes_fixed_len()).into();
        unsafe {
            // This is safe because a valid time-numoffset string is also an ASCII string.
            String::from_utf8_unchecked(vec)
        }
    }
}

impl From<&TimeNumOffsetColonStr> for TimeNumOffsetColonString {
    fn from(v: &TimeNumOffsetColonStr) -> Self {
        unsafe {
            // This is safe because the value is already validated.
            Self::new_maybe_unchecked(*v.as_bytes_fixed_len())
        }
    }
}

impl TryFrom<&[u8]> for TimeNumOffsetColonString {
    type Error = Error;

    #[inline]
    fn try_from(v: &[u8]) -> Result<Self, Self::Error> {
        TimeNumOffsetColonStr::from_bytes(v).map(Into::into)
    }
}

impl TryFrom<&str> for TimeNumOffsetColonString {
    type Error = Error;

    #[inline]
    fn try_from(v: &str) -> Result<Self, Self::Error> {
        TimeNumOffsetColonStr::from_str(v).map(Into::into)
    }
}

impl TryFrom<[u8; 6]> for TimeNumOffsetColonString {
    type Error = Error;

    #[inline]
    fn try_from(v: [u8; 6]) -> Result<Self, Self::Error> {
        validate_bytes(&v)?;
        Ok(unsafe {
            // This is safe because the value is successfully validated.
            Self::new_maybe_unchecked(v)
        })
    }
}

#[cfg(feature = "chrono04")]
#[cfg_attr(docsrs, doc(cfg(feature = "chrono04")))]
impl TryFrom<&chrono04::FixedOffset> for TimeNumOffsetColonString {
    type Error = Error;

    /// Converts the given offset into `TimeNumOffsetColonString`.
    ///
    /// # Failures
    ///
    /// Fails when the second is not zero (for example, `+00:00:30`).
    fn try_from(v: &chrono04::FixedOffset) -> Result<Self, Self::Error> {
        let seconds = v.local_minus_utc();

        if seconds % 60 != 0 {
            // `TimeNumOffsetColonString` can have only offsets with seconds part zero.
            return Err(ErrorKind::ComponentOutOfRange(ComponentKind::Offset).into());
        }
        // `chrono04::offset::FixedOffset` is guaranteed to have time offset
        // from UTC-23:59:59 to UTC+23:59:59.
        // This range can be representable by TimeNumOffsetColonString, if the
        // seconds component is zero.
        debug_assert!(seconds < i32::from(i16::max_value()));
        Ok(Self::from_minutes((seconds / 60) as i16)
            .expect("`chrono04::FixedOffset` must always have a valid time"))
    }
}

impl fmt::Display for TimeNumOffsetColonString {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.as_deref().fmt(f)
    }
}

impl ops::Deref for TimeNumOffsetColonString {
    type Target = TimeNumOffsetColonStr;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.as_deref()
    }
}

impl ops::DerefMut for TimeNumOffsetColonString {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.as_deref_mut()
    }
}

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

    #[inline]
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::try_from(s)
    }
}

impl_cmp_symmetric!(
    TimeNumOffsetColonStr,
    TimeNumOffsetColonString,
    &TimeNumOffsetColonString
);
impl_cmp_symmetric!(
    TimeNumOffsetColonStr,
    TimeNumOffsetColonString,
    TimeNumOffsetColonStr
);
impl_cmp_symmetric!(
    TimeNumOffsetColonStr,
    TimeNumOffsetColonString,
    &TimeNumOffsetColonStr
);
impl_cmp_symmetric!(str, TimeNumOffsetColonString, str);
impl_cmp_symmetric!(str, TimeNumOffsetColonString, &str);
impl_cmp_symmetric!(str, &TimeNumOffsetColonString, str);
impl_cmp_symmetric!([u8], TimeNumOffsetColonString, [u8]);
impl_cmp_symmetric!([u8], TimeNumOffsetColonString, &[u8]);
impl_cmp_symmetric!([u8], &TimeNumOffsetColonString, [u8]);

#[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
impl serde::Serialize for TimeNumOffsetColonString {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

/// Items for serde support.
#[cfg(feature = "serde")]
mod serde_ {
    use super::*;

    use serde::de::{Deserialize, Deserializer, Visitor};

    /// Visitor for `&TimeNumOffsetColonStr`.
    struct StrVisitor;

    impl<'de> Visitor<'de> for StrVisitor {
        type Value = &'de TimeNumOffsetColonStr;

        #[inline]
        fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            f.write_str("RFC 3339 time-numoffset time string")
        }

        #[inline]
        fn visit_borrowed_bytes<E>(self, v: &'de [u8]) -> Result<Self::Value, E>
        where
            E: serde::de::Error,
        {
            Self::Value::try_from(v).map_err(E::custom)
        }

        #[inline]
        fn visit_borrowed_str<E>(self, v: &'de str) -> Result<Self::Value, E>
        where
            E: serde::de::Error,
        {
            Self::Value::try_from(v).map_err(E::custom)
        }
    }

    impl<'de> Deserialize<'de> for &'de TimeNumOffsetColonStr {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserializer.deserialize_any(StrVisitor)
        }
    }

    /// Visitor for `TimeNumOffsetColonString`.
    struct StringVisitor;

    impl<'de> Visitor<'de> for StringVisitor {
        type Value = TimeNumOffsetColonString;

        #[inline]
        fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            f.write_str("RFC 3339 time-numoffset time string")
        }

        #[inline]
        fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
        where
            E: serde::de::Error,
        {
            Self::Value::try_from(v).map_err(E::custom)
        }

        #[inline]
        fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
        where
            E: serde::de::Error,
        {
            Self::Value::try_from(v).map_err(E::custom)
        }
    }

    impl<'de> Deserialize<'de> for TimeNumOffsetColonString {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserializer.deserialize_any(StringVisitor)
        }
    }
}

#[cfg(test)]
mod tests {
    #[cfg(feature = "serde")]
    use super::*;

    use super::validate_bytes as s_validate;

    #[cfg(feature = "serde")]
    use serde_test::{assert_de_tokens, assert_tokens, Token};

    #[test]
    fn validate_bytes() {
        assert!(s_validate(b"+00:00").is_ok());
        assert!(s_validate(b"+00:30").is_ok());
        assert!(s_validate(b"+00:59").is_ok());
        assert!(s_validate(b"+12:00").is_ok());
        assert!(s_validate(b"+12:30").is_ok());
        assert!(s_validate(b"+12:59").is_ok());
        assert!(s_validate(b"+23:00").is_ok());
        assert!(s_validate(b"+23:30").is_ok());
        assert!(s_validate(b"+23:59").is_ok());
        assert!(s_validate(b"-00:00").is_ok());
        assert!(s_validate(b"-00:30").is_ok());
        assert!(s_validate(b"-00:59").is_ok());
        assert!(s_validate(b"-12:00").is_ok());
        assert!(s_validate(b"-12:30").is_ok());
        assert!(s_validate(b"-12:59").is_ok());
        assert!(s_validate(b"-23:00").is_ok());
        assert!(s_validate(b"-23:30").is_ok());
        assert!(s_validate(b"-23:59").is_ok());

        assert!(s_validate(b"Z").is_err());
        assert!(s_validate(b"+24:00").is_err());
        assert!(s_validate(b"-24:00").is_err());
        assert!(s_validate(b"+23:60").is_err());
        assert!(s_validate(b"-23:60").is_err());
        assert!(s_validate(b"00:00").is_err());
    }

    #[cfg(feature = "serde")]
    #[test]
    fn ser_de_str() {
        let raw: &'static str = "-12:34";
        assert_tokens(
            &TimeNumOffsetColonStr::from_str(raw).unwrap(),
            &[Token::BorrowedStr(raw)],
        );
    }

    #[cfg(feature = "serde")]
    #[test]
    fn ser_de_string() {
        let raw: &'static str = "-12:34";
        assert_tokens(
            &TimeNumOffsetColonString::try_from(raw).unwrap(),
            &[Token::Str(raw)],
        );
    }

    #[cfg(feature = "serde")]
    #[test]
    fn de_bytes_slice() {
        let raw: &'static [u8; 6] = b"-12:34";
        assert_de_tokens(
            &TimeNumOffsetColonStr::from_bytes(raw).unwrap(),
            &[Token::BorrowedBytes(raw)],
        );
    }

    #[cfg(feature = "serde")]
    #[test]
    fn de_bytes() {
        let raw: &'static [u8; 6] = b"-12:34";
        assert_de_tokens(
            &TimeNumOffsetColonString::try_from(&raw[..]).unwrap(),
            &[Token::Bytes(raw)],
        );
    }
}