non-empty-str 0.12.0

//! Macros for creating non-empty strings.

/// Constructs [`NonEmptyStr`] from the given string, panicking if it is empty,
/// and then converts it into [`NonEmptyString`].
///
/// # Examples
///
/// Simple usage:
///
/// ```
/// use non_empty_str::non_empty_string;
///
/// let nekit = non_empty_string!("nekit");
/// ```
///
/// Expands to:
///
/// ```
/// use non_empty_str::non_empty_str;
///
/// let nekit = non_empty_str!("nekit").to_non_empty_string();
/// ```
///
/// See [`non_empty_str!`] for more details.
///
/// Panicking if the string is empty:
///
/// ```should_panic
/// use non_empty_str::non_empty_string;
///
/// let never = non_empty_string!("");
/// ```
///
/// [`NonEmptyStr`]: crate::str::NonEmptyStr
/// [`NonEmptyString`]: crate::string::NonEmptyString
/// [`non_empty_str!`]: crate::non_empty_str
#[macro_export]
#[cfg(any(feature = "std", feature = "alloc"))]
macro_rules! non_empty_string {
    ($string: expr) => {
        $crate::non_empty_str!($string).to_non_empty_string()
    };
}

/// Constructs [`NonEmptyStr`] from the given string, panicking if it is empty.
///
/// # Examples
///
/// Simple usage:
///
/// ```
/// use non_empty_str::non_empty_str;
///
/// let nekit = non_empty_str!("nekit");
/// ```
///
/// Panicking if the string is empty:
///
/// ```should_panic
/// use non_empty_str::non_empty_str;
///
/// let never = non_empty_str!("");
/// ```
///
/// Compilation failure when in `const` contexts:
///
/// ```compile_fail
/// use non_empty_str::non_empty_str;
///
/// let never = const { non_empty_str!("") };
/// ```
///
/// [`NonEmptyStr`]: crate::str::NonEmptyStr
#[macro_export]
macro_rules! non_empty_str {
    ($string: expr) => {
        $crate::str::NonEmptyStr::from_str($string).expect($crate::str::EMPTY_STR)
    };
}

/// Similar to [`non_empty_str!`] but for `const` contexts.
///
/// Note that the provided expression must be const-evaluatable, else the compilation will fail.
///
/// # Examples
///
/// ```
/// use non_empty_str::const_non_empty_str;
///
/// let message = const_non_empty_str!("Hello, world!");
/// ```
///
/// Failing compilation on empty strings:
///
/// ```compile_fail
/// use non_empty_str::const_non_empty_str;
///
/// let never = const_non_empty_str!("");
/// ```
///
/// [`non_empty_str!`]: crate::non_empty_str
#[macro_export]
macro_rules! const_non_empty_str {
    ($string: expr) => {
        const { $crate::non_empty_str!($string) }
    };
}