literator 0.2.0

#![doc = include_str!("../README.md")]
#![no_std]
#![forbid(unsafe_code, missing_docs)]

use core::fmt::{Display, Formatter};

pub mod block;
pub mod decorate;
pub mod fmt;
pub mod join;

use block::*;
use decorate::*;
use fmt::*;
use join::*;

/// Iterator extension trait for efficient `Display`/`Debug`.
///
/// See [crate-level documentation](index.html) for more information.
pub trait Literator: Iterator {
    /// Wrap the iterator in an object implementing `Display`/`Debug` that
    /// prints each item separated by a delimiter.
    ///
    /// This does not allocate, but does consumes the iterator when
    /// `Display::fmt()`, `Debug::fmt()`, or another formatting trait is used.
    /// Subsequent uses of the same [`Join`] object will print the empty string.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let items = ["Foo", "Bar"];
    /// let joined = items.iter().join(", ").to_string();
    /// assert_eq!(joined, "Foo, Bar");
    ///
    /// // Formatting options are forwarded.
    /// let joined = format!("{:04x}", [10, 20, 30].iter().join(", "));
    /// assert_eq!(joined, "000a, 0014, 001e");
    ///
    /// let floats = format!("{:0.02}", [1.0, 2.0].iter().join(" "));
    /// assert_eq!(floats, "1.00 2.00");
    /// ```
    fn join<D>(self, delim: D) -> Join<Self, D>
    where
        Self: Sized,
        D: Display,
    {
        Join::new(self, delim)
    }

    /// Concatenate all items into a single string, using each item's `Display`
    /// or `Debug` implementation.
    ///
    /// This is equivalent to [`.join(Empty)`](Literator::join).
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::{Literator, fmt::Uppercase};
    /// let chars = ['a', 'b', 'c'];
    /// assert_eq!(
    ///     chars.iter().map(Uppercase).concat().to_string(),
    ///     "ABC",
    /// );
    /// ```
    fn concat(self) -> Join<Self, Empty>
    where
        Self: Sized,
    {
        self.join(Empty)
    }

    /// Join the items using `delim` between the first N-1 elements, and
    /// `last_delim` between the next-to-last and last items.
    ///
    /// This is the same as
    /// [`oxford_join_custom()`](Literator::oxford_join_custom), but without the
    /// special case for exactly two elements.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let recipients = ["God", "Alice and Bob", "Charlie"];
    /// assert_eq!(
    ///     recipients.iter().conjunctive_join_custom(", ", ", and ").to_string(),
    ///     "God, Alice and Bob, and Charlie"
    /// );
    /// ```
    fn conjunctive_join_custom<Delim, LastDelim>(
        self,
        delim: Delim,
        last_delim: LastDelim,
    ) -> ConjunctiveJoin<Self, Delim, LastDelim>
    where
        Self: Sized,
        Delim: Display,
        LastDelim: Display,
    {
        ConjunctiveJoin::new(self, delim, last_delim)
    }

    /// Join the items separated by `", "` between each item, except `" and "`
    /// (no comma) between the next-to-last and last items.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let fruits = ["apples", "oranges", "bananas"];
    /// assert_eq!(
    ///     fruits.iter().join_and().to_string(),
    ///     "apples, oranges and bananas",
    /// );
    /// ```
    fn join_and(self) -> ConjunctiveJoin<Self>
    where
        Self: Sized,
    {
        self.conjunctive_join_custom(", ", " and ")
    }

    /// Join the items separated by `", "` between each item, except `" or "`
    /// (no comma) between the next-to-last and last items.
    fn join_or(self) -> ConjunctiveJoin<Self>
    where
        Self: Sized,
    {
        self.conjunctive_join_custom(", ", " or ")
    }

    /// Join the items separated by `", "` between each item, except `", and "`
    /// (with comma) between the next-to-last and last items.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let fruits = ["apples", "oranges", "bananas"];
    /// assert_eq!(
    ///     fruits.iter().join_comma_and().to_string(),
    ///     "apples, oranges, and bananas",
    /// );
    /// ```
    fn join_comma_and(self) -> ConjunctiveJoin<Self>
    where
        Self: Sized,
    {
        self.conjunctive_join_custom(", ", ", and ")
    }

    /// Join the items separated by `", "` between each item, except `", or "`
    /// (with comma) between the next-to-last and last items.
    fn join_comma_or(self) -> ConjunctiveJoin<Self>
    where
        Self: Sized,
    {
        self.conjunctive_join_custom(", ", ", or ")
    }

    /// Join items using serial comma ("Oxford comma", "Harvard comma").
    ///
    /// Turns this iterator into an object that implements `Display` and/or
    /// `Debug`. All formatting options are forwarded to each item.
    ///
    /// - Items are formatted using `Debug` or `Display` based on whether the
    ///   returned object is formatted using `Debug` or `Display`.
    /// - When the iterator is empty (N=0), nothing is printed.
    /// - When the iterator has exactly one element (N=1), no separators are
    ///   emitted.
    /// - When the iterator has exactly two elements (N=2), the `{exactly_two}`
    ///   conjunction is the only separator (typically `" and "`, no comma).
    /// - When the iterator has three or more elements (N>=3), `{first_n}` is
    ///   written between all elements, except that `{final_delim_conjunction}`
    ///   is emitted between the next-to-last and last element, and
    ///   `exactly_two_conjunction` is unused.
    ///
    /// Note: This function does not add any spaces around the
    /// delimiters/conjunctions, which is why it takes three arguments.
    ///
    /// To get a standard Oxford list, you would call this as
    /// `iter.oxford_join_custom(", ", " and ", ", and ")`, which is what
    /// [`oxford_join_and()`](Literator::oxford_join_and) does.
    fn oxford_join_custom<Delim, ExactlyTwo, Final>(
        self,
        first_n: Delim,
        exactly_two_conjunction: ExactlyTwo,
        final_delim_conjunction: Final,
    ) -> OxfordJoin<Self, Delim, ExactlyTwo, Final>
    where
        Self: Sized,
        Delim: Display,
        ExactlyTwo: Display,
        Final: Display,
    {
        OxfordJoin::new(
            self,
            first_n,
            exactly_two_conjunction,
            final_delim_conjunction,
        )
    }

    /// Oxford join with commas and English "and".
    ///
    /// See also [`Literator::oxford_join_custom()`].
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let items = ["Parsley", "Sage", "Rosemary", "Thyme"];
    /// let line = items.iter().oxford_join_and().to_string();
    /// assert_eq!(line, "Parsley, Sage, Rosemary, and Thyme");
    ///
    /// let just_two = ["Pride", "Prejudice"];
    /// let title = just_two.iter().oxford_join_and().to_string();
    /// assert_eq!(title, "Pride and Prejudice");
    /// ```
    fn oxford_join_and(self) -> OxfordJoin<Self>
    where
        Self: Sized,
    {
        self.oxford_join_custom(", ", " and ", ", and ")
    }

    /// Oxford join with commas and English "or".
    ///
    /// See also [`Literator::oxford_join_custom()`].
    fn oxford_join_or(self) -> OxfordJoin<Self>
    where
        Self: Sized,
    {
        self.oxford_join_custom(", ", " or ", ", or ")
    }

    /// Oxford join with semicolons and English "and".
    ///
    /// See also [`Literator::oxford_join_custom()`].
    fn oxford_join_semicolon_and(self) -> OxfordJoin<Self>
    where
        Self: Sized,
    {
        self.oxford_join_custom("; ", "; and ", "; and ")
    }

    /// Oxford join with semicolons and English "or".
    ///
    /// See also [`Literator::oxford_join_custom()`].
    fn oxford_join_semicolon_or(self) -> OxfordJoin<Self>
    where
        Self: Sized,
    {
        self.oxford_join_custom("; ", "; or ", "; or ")
    }

    /// Produce an iterator where each item's `Display`/`Debug` implementation
    /// is overridden by `with`.
    ///
    /// This is essentially short-hand for `.map(|item| fmt::from_fn(move |f|
    /// ...))`. See [fmt::from_fn()].
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::{Literator, fmt::Capitalize};
    /// let hex_numbers = [10, 20, 30]
    ///     .iter()
    ///     .format_each_with(|n, f| write!(f, "{n:#04x}"))
    ///     .oxford_join_and()
    ///     .to_string();
    /// assert_eq!(hex_numbers, "0x0a, 0x14, and 0x1e");
    ///
    /// // Capitalize the first item
    /// let items = ["apples", "oranges", "pears"];
    /// assert_eq!(
    ///     items
    ///         .iter()
    ///         .enumerate()
    ///         .format_each_with(|(index, thing), f| if *index == 0 {
    ///             write!(f, "{}", Capitalize(thing))
    ///         } else {
    ///             write!(f, "{thing}")
    ///         })
    ///         .oxford_join_and()
    ///         .to_string(),
    ///     "Apples, oranges, and pears",
    /// );
    /// ```
    fn format_each_with<F>(self, with: F) -> impl Iterator<Item = FormatWith<Self::Item, F>>
    where
        Self: Sized,
        F: Fn(&Self::Item, &mut Formatter) -> core::fmt::Result + Clone,
    {
        self.map(move |item| FormatWith {
            item,
            with: with.clone(),
        })
    }

    /// Capitalize the first item in the list.
    ///
    /// Due to current limitations in the standard library, this only works for
    /// `Display`, not other formatting traits.
    ///
    /// To capitalize all items, use [`.map(Capitalize)`](Capitalize) instead.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let items = ["apples", "oranges", "pears"];
    /// assert_eq!(
    ///     items
    ///         .iter()
    ///         .capitalize_first()
    ///         .oxford_join_and()
    ///         .to_string(),
    ///     "Apples, oranges, and pears",
    /// );
    /// ```
    fn capitalize_first(self) -> impl Iterator<Item: Display>
    where
        Self: Sized,
        Self::Item: Display,
    {
        self.enumerate().format_each_with(|(index, thing), f| {
            if *index == 0 {
                write!(f, "{}", Capitalize(thing))
            } else {
                thing.fmt(f)
            }
        })
    }

    /// Produce an iterator where each item's `Display`/`Debug` implementation
    /// writes a custom prefix before the item.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let numbers = 1..=5;
    /// let even_list = numbers
    ///     .into_iter()
    ///     .prefix_each_with(|n, f| if *n % 2 == 0 { write!(f, "* ") } else { Ok (()) })
    ///     .join('\n')
    ///     .to_string();
    /// assert_eq!(even_list,
    /// "1
    /// * 2
    /// 3
    /// * 4
    /// 5");
    /// ```
    fn prefix_each_with<F>(self, with: F) -> impl Iterator<Item = PrefixWith<Self::Item, F>>
    where
        F: Fn(&Self::Item, &mut Formatter) -> core::fmt::Result + Clone,
        Self: Sized,
    {
        self.map(move |item| PrefixWith {
            item,
            with: with.clone(),
        })
    }

    /// Produce an iterator where each item's `Display`/`Debug` implementation
    /// writes a custom suffix after the item.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let numbers = 1..=10;
    /// let even_list = numbers
    ///     .into_iter()
    ///     .suffix_each_with(|n, f| if *n % 2 == 0 { write!(f, " *") } else { Ok (()) })
    ///     .join('\n')
    ///     .to_string();
    /// assert_eq!(even_list, "1\n2 *\n3\n4 *\n5\n6 *\n7\n8 *\n9\n10 *");
    /// ```
    fn suffix_each_with<F>(self, with: F) -> impl Iterator<Item = SuffixWith<Self::Item, F>>
    where
        F: Fn(&Self::Item, &mut Formatter) -> core::fmt::Result + Clone,
        Self: Sized,
    {
        self.map(move |item| SuffixWith {
            item,
            with: with.clone(),
        })
    }

    /// Produce an iterator where each item's `Display`/`Debug` implementation
    /// writes `prefix` before the item.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let items = ["Milk", "Eggs", "Tampons"];
    /// let shopping_list = items.iter().prefix_each("- ").join('\n').to_string();
    /// assert_eq!(shopping_list, "- Milk\n- Eggs\n- Tampons");
    /// ```
    fn prefix_each<P>(self, prefix: P) -> impl Iterator<Item = Prefix<Self::Item, P>>
    where
        P: Display + Clone,
        Self: Sized,
    {
        self.map(move |item| Prefix {
            item,
            prefix: prefix.clone(),
        })
    }

    /// Produce an iterator where each item's `Display`/`Debug` implementation
    /// writes `suffix` after the item.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let words = ["Fresh", "Innovative", "Placemaking", "Disposable duvets", "Growth hacking"];
    /// let message = words.iter().suffix_each('.').join(' ').to_string();
    /// assert_eq!(message, "Fresh. Innovative. Placemaking. Disposable duvets. Growth hacking.");
    /// ```
    fn suffix_each<S>(self, suffix: S) -> impl Iterator<Item = Suffix<Self::Item, S>>
    where
        S: Display + Clone,
        Self: Sized,
    {
        self.map(move |item| Suffix {
            item,
            suffix: suffix.clone(),
        })
    }

    /// Produce an iterator where each item's `Display`/`Debug` implementation
    /// writes `prefix` before and `suffix` after the item.
    ///
    /// This is shorthand for `.suffix_each(suffix).prefix_each(prefix)`.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let items = ["Foo", "Bar"];
    /// let list = items.iter().surround_each('(', ')').concat().to_string();
    /// assert_eq!(list, "(Foo)(Bar)");
    /// ```
    fn surround_each<P, S>(
        self,
        prefix: P,
        suffix: S,
    ) -> impl Iterator<Item = Prefix<Suffix<Self::Item, S>, P>>
    where
        P: Display + Clone,
        S: Display + Clone,
        Self: Sized,
    {
        self.suffix_each(suffix).prefix_each(prefix)
    }

    /// Print each item prefixed by indentation, where each level of indentation
    /// is 4 spaces, and suffix each item with a newline.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let numbers = format!("\n{}", [1, 2, 3].iter().prefix_each("- ").indent(1).concat());
    /// assert_eq!(numbers, "
    ///     - 1
    ///     - 2
    ///     - 3
    /// ");
    /// ```
    fn indent(
        self,
        level: usize,
    ) -> impl Iterator<Item = Prefix<Suffix<Self::Item, char>, Repeat<&'static str>>>
    where
        Self: Sized,
    {
        self.indent_custom(level, "    ", '\n')
    }

    /// Print each item with custom indentation.
    fn indent_custom<P, S>(
        self,
        level: usize,
        indentation: P,
        newline: S,
    ) -> impl Iterator<Item = Prefix<Suffix<Self::Item, S>, Repeat<P>>>
    where
        P: Display + Clone,
        S: Display + Clone,
        Self: Sized,
    {
        self.surround_each(repeat(indentation, level), newline)
    }

    /// Print items in a block surrounded by `open` and `close`, indented by `inner_level`.
    ///
    /// When there are zero items, the open and close tokens are printed without
    /// any spacing or newline.
    ///
    /// When there are one or more items: A newline is added after the open
    /// token, and each item is printed with default indentation (four spaces
    /// per level) on a separate line, and the closing delimiter is placed on a
    /// separate line with indentation corresponding to `inner_level-1`.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// # use std::collections::BTreeMap;
    /// let empty: &[i32] = &[];
    /// assert_eq!(empty.iter().indented_block('{', '}', 1).to_string(), "{}");
    ///
    /// let two = &[1, 2];
    /// assert_eq!(format!("\n{}", two.iter().indented_block('{', '}', 1)), "
    /// {
    ///     1
    ///     2
    /// }");
    ///
    /// let map = BTreeMap::from_iter([("hello", 123), ("world", 456)]);
    /// assert_eq!(
    ///     format!("\n{}", map
    ///         .iter()
    ///         .format_each_with(|(key, value), f| write!(f, "{key}: {value},"))
    ///         .indented_block('{', '}', 1)),
    ///     "
    /// {
    ///     hello: 123,
    ///     world: 456,
    /// }");
    /// ```
    fn indented_block<Open, Close>(
        self,
        open: Open,
        close: Close,
        inner_level: usize,
    ) -> IndentedBlock<Self, Open, Close, &'static str, char>
    where
        Self: Sized,
        Open: Display,
        Close: Display,
    {
        self.indented_block_custom(open, close, inner_level, "    ", '\n')
    }

    /// Same as [`indented_block()`](Literator::indented_block), but with custom
    /// indentation and newline tokens.
    ///
    /// `indentation` is printed for each indentation level. `newline` is
    /// printed after each item, as well as after `open`.
    fn indented_block_custom<Open, Close, Indentation, Newline>(
        self,
        open: Open,
        close: Close,
        inner_level: usize,
        indentation: Indentation,
        newline: Newline,
    ) -> IndentedBlock<Self, Open, Close, Indentation, Newline>
    where
        Self: Sized,
        Open: Display,
        Close: Display,
        Indentation: Display,
        Newline: Display,
    {
        IndentedBlock::new(self, open, close, indentation, newline, inner_level)
    }

    /// Print items in a block surrounded by `open` and `close`, where items are
    /// delimited by `delim`.
    ///
    /// When there are zero items, the open and close tokens are printed without
    /// any spacing, but when there are one or more items, a space is added
    /// after the opening token and before the closing token. This is what
    /// distinguishes `inline_block()` from simply using `join(delim)`
    /// surrounded by the open/close tokens.
    ///
    /// # Example
    ///
    /// ```
    /// # use literator::Literator;
    /// let empty: &[i32] = &[];
    /// assert_eq!(empty.iter().inline_block('[', ',', ']').to_string(), "[]");
    ///
    /// let one = &[1];
    /// assert_eq!(one.iter().inline_block('[', ',', ']').to_string(), "[ 1 ]");
    ///
    /// let two = &[1, 2];
    /// assert_eq!(two.iter().inline_block('[', ", ", ']').to_string(), "[ 1, 2 ]");
    /// ```
    fn inline_block<P, D, S>(self, open: P, delim: D, close: S) -> InlineBlock<Self, P, D, S>
    where
        Self: Sized,
        P: Display,
        D: Display,
        S: Display,
    {
        InlineBlock::new(self, open, delim, close)
    }
}

impl<I: Iterator> Literator for I {}

macro_rules! impl_fmt_trait {
    ($trait:ident) => {
        impl<D, I> core::fmt::$trait for Join<I, D>
        where
            I: Iterator<Item: core::fmt::$trait>,
            D: Display,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.do_fmt(f, core::fmt::$trait::fmt)
            }
        }

        impl<I, D, L> core::fmt::$trait for ConjunctiveJoin<I, D, L>
        where
            I: Iterator<Item: core::fmt::$trait>,
            D: Display,
            L: Display,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.do_fmt(f, core::fmt::$trait::fmt)
            }
        }

        impl<I, D1, D2, D3> core::fmt::$trait for OxfordJoin<I, D1, D2, D3>
        where
            I: Iterator<Item: core::fmt::$trait>,
            D1: Display,
            D2: Display,
            D3: Display,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.do_fmt(f, core::fmt::$trait::fmt)
            }
        }

        impl<I, Open, Delim, Close> core::fmt::$trait for InlineBlock<I, Open, Delim, Close>
        where
            I: Iterator<Item: core::fmt::$trait>,
            Open: Display,
            Delim: Display,
            Close: Display,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.do_fmt(f, core::fmt::$trait::fmt)
            }
        }

        impl<I, Open, Close, Indentation, Newline> core::fmt::$trait
            for IndentedBlock<I, Open, Close, Indentation, Newline>
        where
            I: Iterator<Item: core::fmt::$trait>,
            Open: Display,
            Close: Display,
            Indentation: Display,
            Newline: Display,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.do_fmt(f, core::fmt::$trait::fmt)
            }
        }

        impl<T: core::fmt::$trait, P: Display> core::fmt::$trait for Prefix<T, P> {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                write!(f, "{}", self.prefix)?;
                self.item.fmt(f)
            }
        }

        impl<T: core::fmt::$trait, S: Display> core::fmt::$trait for Suffix<T, S> {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.item.fmt(f)?;
                write!(f, "{}", self.suffix)
            }
        }

        impl<T, F> core::fmt::$trait for PrefixWith<T, F>
        where
            T: core::fmt::$trait,
            F: Fn(&T, &mut Formatter) -> core::fmt::Result,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                (self.with)(&self.item, f)?;
                self.item.fmt(f)
            }
        }

        impl<T, F> core::fmt::$trait for SuffixWith<T, F>
        where
            T: core::fmt::$trait,
            F: Fn(&T, &mut Formatter) -> core::fmt::Result,
        {
            fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
                self.item.fmt(f)?;
                (self.with)(&self.item, f)
            }
        }
    };
}

impl_fmt_trait!(Display);
impl_fmt_trait!(Debug);
impl_fmt_trait!(LowerHex);
impl_fmt_trait!(LowerExp);
impl_fmt_trait!(UpperHex);
impl_fmt_trait!(UpperExp);
impl_fmt_trait!(Octal);
impl_fmt_trait!(Pointer);
impl_fmt_trait!(Binary);