From 805bd64041829f01cfb09d16425788acd6d62aee Mon Sep 17 00:00:00 2001
From: Antoine Gallix <7696611+antoine-gallix@users.noreply.github.com>
Date: Fri, 18 Jul 2025 23:09:21 +0300
Subject: [PATCH] Simpler and more complete example

In my opinion the original example was illustrating an specific application of the function, but not the essential.

The new example shows:
- syntax for projection on one key
- syntax for projection on multiple keys
- result of a key not in the target; that is, nothing.
---
 docs/colls.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/colls.rst b/docs/colls.rst
index 7ea45be..922541c 100644
--- a/docs/colls.rst
+++ b/docs/colls.rst
@@ -167,9 +167,13 @@ Dict utils
 
     Returns a dict containing only those entries in ``mapping`` whose key is in ``keys``.
 
-    Most useful to shrink some common data or options to predefined subset. One particular case is constructing a dict of used variables::
-
-        merge(project(__builtins__, names), project(globals(), names))
+        d={"a":1,"b":2,"c":3}
+        project(d,"a")
+        # -> {"a":1}
+        project(d,("a","b"))
+        # -> {'a': 1, 'b': 2}
+        project(d,("a","x"))
+        # -> {"a":1}
 
 
 .. function:: omit(mapping, keys)