add iter to README

Author: ModProg

README.md

@@ -45,6 +45,40 @@ write(
 assert_eq!(buf, format!("{:+05}", 12));
 ```
 
+# `i` iter format
+
+The feature `iter` enables an additional format trait `i`, it allows to
+format a list of values with a format string and an optional join
+expression.
+
+The syntax is `{list:i(the format string, '{it}' is the array element)(the
+optional join)}`, an empty join can also be omitted `{list:i({it})}`. Should
+you need to use `)` inside your format string or join, you can add `#`
+similar to rust's [raw string](https://doc.rust-lang.org/reference/tokens.html#raw-string-literals).
+
+It is also possible to only iterate a sub-slice specified through a range
+before the format string, i.e. `{list:i1..4({it})}`. For open ranges range
+bounds can also be omitted. To index from the end, you can use negative
+range bounds.
+
+A `Formattable` implementing iter is created using `Formattable::iter`:
+
+```rs
+// HashMap macro
+use collection_literals::hash;
+use interpolator::{format, Formattable};
+// Needs to be a slice of references so because `Formattable::display` expects a
+// reference
+let items = [&"hello", &"hi", &"hey"].map(Formattable::display);
+let items = Formattable::iter(&items);
+let format_str = "Greetings: {items:i..-1(`{it}`)(, )} and {items:i-1..(`{it}`)}";
+assert_eq!(
+    format(format_str, &hash!("items" => items))?,
+    "Greetings: `hello`, `hi` and `hey`"
+);
+# return Ok::<(), interpolator::Error>(())
+```
+
 # Features
 By default only `Display` is supported, the rest of the
 [formatting traits](https://doc.rust-lang.org/std/fmt/index.html#formatting-traits)
@@ -53,3 +87,4 @@ can be enabled through the following features.
 - `debug` enables `?`, `x?` and `X?` trait specifiers
 - `number` enables `x`, `X`, `b`, `o`, `e` and `E` trait specifiers
 - `pointer` enables `p` trait specifiers
+- `iter` enables `i` trait specifier

src/lib.rs

@@ -30,9 +30,11 @@ format a list of values with a format string and an optional join
 expression.
 
 The syntax is `{list:i(the format string, '{it}' is the array element)(the
-optional join)}`, an empty join can also be omitted `{list:i({it})}`. Should
-you need to use `)` inside your format string or join, you can add `#`
-similar to rust's [raw string](https://doc.rust-lang.org/reference/tokens.html#raw-string-literals).
+optional join)}`, an empty join can also be omitted `{list:i({it})}`.
+
+Should you need to use `)` inside your format string or join, you can add `#`
+similar to rust's [raw string](https://doc.rust-lang.org/reference/tokens.html#raw-string-literals)
+(i.e. `#(({it}))#`).
 
 It is also possible to only iterate a sub-slice specified through a range
 before the format string, i.e. `{list:i1..4({it})}`. For open ranges range
@@ -68,6 +70,7 @@ assert_eq!(
 //! - `debug` enables `?`, `x?` and `X?` trait specifiers
 //! - `number` enables `x`, `X`, `b`, `o`, `e` and `E` trait specifiers
 //! - `pointer` enables `p` trait specifiers
+//! - `iter` enables [`i`](#i-iter-format) trait specifier
 #![warn(clippy::pedantic, missing_docs)]
 #![allow(
     clippy::wildcard_imports,