From a6d0f39cb4df4e211e8e529c629a162a11fc616c Mon Sep 17 00:00:00 2001
From: Petro31 <35082313+Petro31@users.noreply.github.com>
Date: Tue, 27 Aug 2024 08:42:17 -0400
Subject: [PATCH] Add zip template documentation (#33934)

* Add zip template documentation

* Update source/_docs/configuration/templating.markdown

Co-authored-by: Stefan Agner <stefan@agner.ch>

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Co-authored-by: Stefan Agner <stefan@agner.ch>
---
 .../_docs/configuration/templating.markdown   | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown
index ae43aeed336..5c59113e367 100644
--- a/source/_docs/configuration/templating.markdown
+++ b/source/_docs/configuration/templating.markdown
@@ -1091,6 +1091,38 @@ While Jinja natively supports the conversion of an iterable to a `list`, it does
 
 Note that, in Home Assistant, to convert a value to a `list`, a `string`, an `int`, or a `float`, Jinja has built-in functions with names that correspond to each type.
 
+### Iterating multiple objects
+
+The `zip()` function can be used to iterate over multiple collections in one operation.
+
+{% raw %}
+
+```text
+{% set names = ['Living Room', 'Dining Room'] %}
+{% set entities = ['sensor.living_room_temperature', 'sensor.dining_room_temperature'] %}
+{% for name, entity in zip(names, entities) %}
+  The {{ name }} temperature is {{ states(entity) }}
+{% endfor %}
+```
+
+{% endraw %}
+
+`zip()` can also unzip lists.
+
+{% raw %}
+
+```text
+{% set information = [
+  ('Living Room', 'sensor.living_room_temperature'),
+  ('Dining Room', 'sensor.dining_room_temperature')
+] %}
+{% set names, entities = zip(*information) %}
+The names are {{ names | join(', ') }}
+The entities are {{ entities | join(', ') }}
+```
+
+{% endraw %}
+
 ### Functions and filters to process raw data
 
 These functions are used to process raw value's in a `bytes` format to values in a native Python type or vice-versa.