From 934d63eb409446836a3b5f62cfe6f0460a1a2657 Mon Sep 17 00:00:00 2001
From: Raymond Hettinger <python@rcn.com>
Date: Sun, 31 Jul 2005 01:33:10 +0000
Subject: [PATCH] Comment on the set_swap_bodies() helper function.

---
 Objects/setobject.c | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Objects/setobject.c b/Objects/setobject.c
index e922b6ef539..a279ec2a5ce 100644
--- a/Objects/setobject.c
+++ b/Objects/setobject.c
@@ -793,6 +793,19 @@ set_len(PyObject *so)
 	return ((PySetObject *)so)->used;
 }
 
+/* set_swap_bodies() switches the contents of any two sets by moving their
+   internal data pointers and, if needed, copying the internal smalltables.
+   Semantically equivalent to:
+
+     t=set(a); a.clear(); a.update(b); b.clear(); b.update(t); del t
+
+   The function always succeeds and it leaves both objects in a stable state.
+   Useful for creating temporary frozensets from sets for membership testing 
+   in __contains__(), discard(), and remove().  Also useful for operations
+   that update in-place (by allowing an intermediate result to be swapped 
+   into one of original the inputs).
+*/
+
 static void
 set_swap_bodies(PySetObject *a, PySetObject *b)
 {