From a4c8e32a1f1a1eb4014a9f289360e241f942455a Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Thu, 12 Oct 2006 08:22:53 +0000
Subject: [PATCH] Bug #1565919: document set types in the Language Reference.

---
 Doc/ref/ref3.tex | 35 +++++++++++++++++++++++++++++++++++
 Misc/NEWS        |  2 ++
 2 files changed, 37 insertions(+)

diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index 9c84ed98467..618dccde8c4 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -379,6 +379,41 @@ additional example of a mutable sequence type.
 
 \end{description} % Sequences
 
+
+\item[Set types]
+These represent unordered, finite sets of unique, immutable objects.
+As such, they cannot be indexed by any subscript. However, they can be
+iterated over, and the built-in function \function{len()} returns the
+number of items in a set. Common uses for sets are
+fast membership testing, removing duplicates from a sequence, and
+computing mathematical operations such as intersection, union, difference,
+and symmetric difference.
+\bifuncindex{len}
+\obindex{set type}
+
+For set elements, the same immutability rules apply as for dictionary
+keys. Note that numeric types obey the normal rules for numeric
+comparison: if two numbers compare equal (e.g., \code{1} and
+\code{1.0}), only one of them can be contained in a set.
+
+There are currently two intrinsic set types:
+
+\begin{description}
+
+\item[Sets]
+These\obindex{set} represent a mutable set. They are created by the
+built-in \function{set()} constructor and can be modified afterwards
+by several methods, such as \method{add()}.
+
+\item[Frozen sets]
+These\obindex{frozenset} represent an immutable set. They are created by
+the built-in \function{frozenset()} constructor. As a frozenset is
+immutable and hashable, it can be used again as an element of another set,
+or as a dictionary key.
+
+\end{description} % Set types
+
+
 \item[Mappings]
 These represent finite sets of objects indexed by arbitrary index sets.
 The subscript notation \code{a[k]} selects the item indexed
diff --git a/Misc/NEWS b/Misc/NEWS
index 75ef538fa19..4a19fda83fc 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -175,6 +175,8 @@ Tests
 Documentation
 -------------
 
+- Bug #1565919: document set types in the Language Reference.
+
 - Bug #1546052: clarify that PyString_FromString(AndSize) copies the
   string pointed to by its parameter.