From 4914da2f04d73b0ebd8294e9dcaea508a2518709 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rados=C5=82aw=20Pikul?= <rapikul111@gmail.com>
Date: Thu, 11 Apr 2024 21:29:41 +0200
Subject: [PATCH] Adding docs for joins

---
 docs/colls.rst | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/colls.rst b/docs/colls.rst
index 7ea45be..0c5c201 100644
--- a/docs/colls.rst
+++ b/docs/colls.rst
@@ -313,6 +313,49 @@ Data manipulation
         invoke(['abc', 'def', 'b'], 'find', 'b')
         # ->[1, -1, 0]
 
+.. function:: inner_join(left,right,right_column,left_column)
+
+        Returns a list of tuples of matching rows from the two tables. The tables are expected to be lists of dictionaries, and the columns are the keys in the dictionaries.
+
+        For example::
+
+            left = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+            right = [{'id': 1, 'age': 25}, {'id': 3, 'age': 30}]
+            inner_join(left, right, 'id', 'id')
+            # -> [{'id': 1, 'name': 'Alice', 'age': 25}]
+
+.. function:: left_join(left,right,right_column,left_column)
+
+        Returns a list of tuples of matching rows from the two tables. The tables are expected to be lists of dictionaries, and the columns are the keys in the dictionaries. If a row in the left table does not have a match in the right table, the right table columns will be omitted.
+
+        For example::
+
+            left = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+            right = [{'id': 1, 'age': 25}, {'id': 3, 'age': 30}]
+            left_join(left, right, 'id', 'id')
+            # -> [{'id': 1, 'name': 'Alice', 'age': 25}, {'id': 2, 'name': 'Bob'}]
+
+.. function:: right_join(left,right,right_column,left_column)
+
+        Returns a list of tuples of matching rows from the two tables. The tables are expected to be lists of dictionaries, and the columns are the keys in the dictionaries. If a row in the right table does not have a match in the left table, the left table columns will be omitted.
+
+        For example::
+
+            left = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+            right = [{'id': 1, 'age': 25}, {'id': 3, 'age': 30}]
+            right_join(left, right, 'id', 'id')
+            # -> [{'id': 1, 'name': 'Alice', 'age': 25}, {'id': 3, 'age': 30}]
+
+.. function:: full_join(left,right,right_column,left_column)
+
+            Returns a list of tuples of matching rows from the two tables. The tables are expected to be lists of dictionaries, and the columns are the keys in the dictionaries. If a row in the left table does not have a match in the right table, the right table columns will be omitted. If a row in any of the tables does not have a match in the other table, the columns from the other table will be omitted.
+
+            For example::
+
+                left = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+                right = [{'id': 1, 'age': 25}, {'id': 3, 'age': 30}]
+                full_join(left, right, 'id', 'id')
+                # -> [{'id': 1, 'name': 'Alice', 'age': 25}, {'id': 2, 'name': 'Bob'}, {'id': 3, 'age': 30}]
 
 Content tests
 -------------