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 e8be7fa1d4e..443bdddbef9 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -191,6 +191,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.