Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstdtypes.tex @ 35074:f89cbe69db63 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #1215887: String and list methods documentation deeply hidden Make doc on specific types easier to find by listing them in the headings for the abstract types.
author Raymond Hettinger <python@rcn.com>
date Tue, 14 Jun 2005 08:47:19 +0000
parents 5e511ddef48b
children 5d977d7cc335
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
1 \section{Built-in Types \label{types}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3 The following sections describe the standard types that are built into
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
4 the interpreter. Historically, Python's built-in types have differed
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
5 from user-defined types because it was not possible to use the built-in
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
6 types as the basis for object-oriented inheritance. With the 2.2
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
7 release this situation has started to change, although the intended
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
8 unification of user-defined and built-in types is as yet far from
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
9 complete.
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
10
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
11 The principal built-in types are numerics, sequences, mappings, files
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
12 classes, instances and exceptions.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 \indexii{built-in}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 Some operations are supported by several object types; in particular,
31298
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for
Guido van Rossum <guido@python.org>
parents: 31286
diff changeset
16 practically all objects can be compared, tested for truth value,
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for
Guido van Rossum <guido@python.org>
parents: 31286
diff changeset
17 and converted to a string (with the \code{`\textrm{\ldots}`} notation,
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for
Guido van Rossum <guido@python.org>
parents: 31286
diff changeset
18 the equivalent \function{repr()} function, or the slightly different
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for
Guido van Rossum <guido@python.org>
parents: 31286
diff changeset
19 \function{str()} function). The latter
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for
Guido van Rossum <guido@python.org>
parents: 31286
diff changeset
20 function is implicitly used when an object is written by the
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
21 \keyword{print}\stindex{print} statement.
28909
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant
Fred Drake <fdrake@acm.org>
parents: 28606
diff changeset
22 (Information on \ulink{\keyword{print} statement}{../ref/print.html}
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant
Fred Drake <fdrake@acm.org>
parents: 28606
diff changeset
23 and other language statements can be found in the
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant
Fred Drake <fdrake@acm.org>
parents: 28606
diff changeset
24 \citetitle[../ref/ref.html]{Python Reference Manual} and the
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant
Fred Drake <fdrake@acm.org>
parents: 28606
diff changeset
25 \citetitle[../tut/tut.html]{Python Tutorial}.)
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
28909
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant
Fred Drake <fdrake@acm.org>
parents: 28606
diff changeset
28 \subsection{Truth Value Testing\label{truth}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
30 Any object can be tested for truth value, for use in an \keyword{if} or
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
31 \keyword{while} condition or as operand of the Boolean operations below.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 The following values are considered false:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \stindex{if}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34 \stindex{while}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 \indexii{truth}{value}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 \indexii{Boolean}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 \index{false}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 \begin{itemize}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 \item \code{None}
24631
110c6edaf62f Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24599
diff changeset
42 \withsubitem{(Built-in object)}{\ttindex{None}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
44 \item \code{False}
24631
110c6edaf62f Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24599
diff changeset
45 \withsubitem{(Built-in object)}{\ttindex{False}}
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
46
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
47 \item zero of any numeric type, for example, \code{0}, \code{0L},
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
48 \code{0.0}, \code{0j}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
50 \item any empty sequence, for example, \code{''}, \code{()}, \code{[]}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
52 \item any empty mapping, for example, \code{\{\}}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 \item instances of user-defined classes, if the class defines a
24631
110c6edaf62f Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24599
diff changeset
55 \method{__nonzero__()} or \method{__len__()} method, when that
110c6edaf62f Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24599
diff changeset
56 method returns the integer zero or \class{bool} value
110c6edaf62f Clarify that the bool instances are acceptable return values from
Fred Drake <fdrake@acm.org>
parents: 24599
diff changeset
57 \code{False}.\footnote{Additional
24227
8a67f28a42a5 Clarify the return value of __nonzero__(): It *must* be an integer.
Fred Drake <fdrake@acm.org>
parents: 23860
diff changeset
58 information on these special methods may be found in the
8a67f28a42a5 Clarify the return value of __nonzero__(): It *must* be an integer.
Fred Drake <fdrake@acm.org>
parents: 23860
diff changeset
59 \citetitle[../ref/ref.html]{Python Reference Manual}.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 \end{itemize}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 All other values are considered true --- so objects of many types are
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 always true.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 \index{true}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 Operations and built-in functions that have a Boolean result always
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
68 return \code{0} or \code{False} for false and \code{1} or \code{True}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
69 for true, unless otherwise stated. (Important exception: the Boolean
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
70 operations \samp{or}\opindex{or} and \samp{and}\opindex{and} always
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
71 return one of their operands.)
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
72 \index{False}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
73 \index{True}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74
35074
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
75 \subsection{Boolean Operations ---
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
76 \keyword{and}, \keyword{or}, \keyword{not}
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
77 \label{boolean}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 These are the Boolean operations, ordered by ascending priority:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \indexii{Boolean}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
83 \lineiii{\var{x} or \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
84 {if \var{x} is false, then \var{y}, else \var{x}}{(1)}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
85 \lineiii{\var{x} and \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
86 {if \var{x} is false, then \var{x}, else \var{y}}{(1)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 \hline
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
88 \lineiii{not \var{x}}
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
89 {if \var{x} is false, then \code{True}, else \code{False}}{(2)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 \opindex{and}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 \opindex{or}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 \opindex{not}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 These only evaluate their second argument if needed for their outcome.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 \item[(2)]
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
104 \samp{not} has a lower priority than non-Boolean operators, so
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
105 \code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} ==
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
106 \var{b})}, and \code{\var{a} == not \var{b}} is a syntax error.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
111 \subsection{Comparisons \label{comparisons}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 Comparison operations are supported by all objects. They all have the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 same priority (which is higher than that of the Boolean operations).
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
115 Comparisons can be chained arbitrarily; for example, \code{\var{x} <
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
116 \var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
117 \var{y} <= \var{z}}, except that \var{y} is evaluated only once (but
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
118 in both cases \var{z} is not evaluated at all when \code{\var{x} <
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
119 \var{y}} is found to be false).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \indexii{chaining}{comparisons}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 This table summarizes the comparison operations:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 \begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 \lineiii{<}{strictly less than}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 \lineiii{<=}{less than or equal}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \lineiii{>}{strictly greater than}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 \lineiii{>=}{greater than or equal}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 \lineiii{==}{equal}{}
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
130 \lineiii{!=}{not equal}{(1)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 \lineiii{<>}{not equal}{(1)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 \lineiii{is}{object identity}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 \lineiii{is not}{negated object identity}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135 \indexii{operator}{comparison}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136 \opindex{==} % XXX *All* others have funny characters < ! >
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137 \opindex{is}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 \opindex{is not}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 \code{<>} and \code{!=} are alternate spellings for the same operator.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
147 \code{!=} is the preferred spelling; \code{<>} is obsolescent.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150
29343
e4f70e602598 Patch #744238: Explain that different string types also may compare equal.
Martin v. Löwis <martin@v.loewis.de>
parents: 29067
diff changeset
151 Objects of different types, except different numeric types and different string types, never
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 compare equal; such objects are ordered consistently but arbitrarily
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 (so that sorting a heterogeneous array yields a consistent result).
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
154 Furthermore, some types (for example, file objects) support only a
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
155 degenerate notion of comparison where any two objects of that type are
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
156 unequal. Again, such objects are ordered arbitrarily but
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
157 consistently. The \code{<}, \code{<=}, \code{>} and \code{>=}
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
158 operators will raise a \exception{TypeError} exception when any operand
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
159 is a complex number.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
160 \indexii{object}{numeric}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 \indexii{objects}{comparing}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
163 Instances of a class normally compare as non-equal unless the class
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
164 \withsubitem{(instance method)}{\ttindex{__cmp__()}}
14485
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
165 defines the \method{__cmp__()} method. Refer to the
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
166 \citetitle[../ref/customization.html]{Python Reference Manual} for
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
167 information on the use of this method to effect object comparisons.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
169 \strong{Implementation note:} Objects of different types except
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
170 numbers are ordered by their type names; objects of the same types
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
171 that don't support proper comparison are ordered by their address.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
172
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
173 Two more operations with the same syntactic priority,
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
174 \samp{in}\opindex{in} and \samp{not in}\opindex{not in}, are supported
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
175 only by sequence types (below).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177
35074
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
178 \subsection{Numeric Types ---
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
179 \class{int}, \class{float}, \class{long}, \class{complex}
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
180 \label{typesnumeric}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
182 There are four distinct numeric types: \dfn{plain integers},
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
183 \dfn{long integers},
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 \dfn{floating point numbers}, and \dfn{complex numbers}.
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
185 In addition, Booleans are a subtype of plain integers.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 Plain integers (also just called \dfn{integers})
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
187 are implemented using \ctype{long} in C, which gives them at least 32
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 bits of precision. Long integers have unlimited precision. Floating
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
189 point numbers are implemented using \ctype{double} in C. All bets on
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 their precision are off unless you happen to know the machine you are
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 working with.
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
192 \obindex{numeric}
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
193 \obindex{Boolean}
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
194 \obindex{integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
195 \obindex{long integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
196 \obindex{floating point}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
197 \obindex{complex number}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
198 \indexii{C}{language}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
200 Complex numbers have a real and imaginary part, which are each
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
201 implemented using \ctype{double} in C. To extract these parts from
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
202 a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 Numbers are created by numeric literals or as the result of built-in
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 functions and operators. Unadorned integer literals (including hex
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
206 and octal numbers) yield plain integers unless the value they denote
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
207 is too large to be represented as a plain integer, in which case
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
208 they yield a long integer. Integer literals with an
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
209 \character{L} or \character{l} suffix yield long integers
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
210 (\character{L} is preferred because \samp{1l} looks too much like
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
211 eleven!). Numeric literals containing a decimal point or an exponent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
212 sign yield floating point numbers. Appending \character{j} or
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
213 \character{J} to a numeric literal yields a complex number with a
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
214 zero real part. A complex numeric literal is the sum of a real and
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
215 an imaginary part.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 \indexii{numeric}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 \indexii{integer}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 \indexiii{long}{integer}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 \indexii{floating point}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 \indexii{complex number}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 \indexii{hexadecimal}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 \indexii{octal}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224 Python fully supports mixed arithmetic: when a binary arithmetic
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 operator has operands of different numeric types, the operand with the
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
226 ``narrower'' type is widened to that of the other, where plain
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
227 integer is narrower than long integer is narrower than floating point is
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
228 narrower than complex.
10520
7ee1e3134147 Fixed latex2html weirdness with footnotes.
Fred Drake <fdrake@acm.org>
parents: 10241
diff changeset
229 Comparisons between numbers of mixed type use the same rule.\footnote{
7ee1e3134147 Fixed latex2html weirdness with footnotes.
Fred Drake <fdrake@acm.org>
parents: 10241
diff changeset
230 As a consequence, the list \code{[1, 2]} is considered equal
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
231 to \code{[1.0, 2.0]}, and similarly for tuples.
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
232 } The constructors \function{int()}, \function{long()}, \function{float()},
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
233 and \function{complex()} can be used
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
234 to produce numbers of a specific type.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 \index{arithmetic}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 \bifuncindex{int}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 \bifuncindex{long}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 \bifuncindex{float}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 \bifuncindex{complex}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
241 All numeric types (except complex) support the following operations,
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
242 sorted by ascending priority (operations in the same box have the same
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243 priority; all numeric operations have a higher priority than
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244 comparison operations):
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
247 \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
248 \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
252 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 \lineiii{-\var{x}}{\var{x} negated}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255 \lineiii{+\var{x}}{\var{x} unchanged}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
256 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
257 \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260 \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261 \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
10147
3ac7f0066375 Document <complex #>.conjugate().
Fred Drake <fdrake@acm.org>
parents: 9558
diff changeset
262 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
35074
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
263 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} // \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264 \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
266 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
267 \indexiii{operations on}{numeric}{types}
10147
3ac7f0066375 Document <complex #>.conjugate().
Fred Drake <fdrake@acm.org>
parents: 9558
diff changeset
268 \withsubitem{(complex number method)}{\ttindex{conjugate()}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
272 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
273
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
274 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
275 For (plain or long) integer division, the result is an integer.
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
276 The result is always rounded towards minus infinity: 1/2 is 0,
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
277 (-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
278 is a long integer if either operand is a long integer, regardless of
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
279 the numeric value.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
280 \indexii{integer}{division}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
281 \indexiii{long}{integer}{division}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
282
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
283 \item[(2)]
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
284 Conversion from floating point to (long or plain) integer may round or
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
285 truncate as in C; see functions \function{floor()} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
286 \function{ceil()} in the \refmodule{math}\refbimodindex{math} module
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
287 for well-defined conversions.
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
288 \withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
289 \indexii{numeric}{conversions}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
290 \indexii{C}{language}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
291
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
292 \item[(3)]
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
293 See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
294 description.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
295
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
296 \item[(4)]
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
297 Complex floor division operator, modulo operator, and \function{divmod()}.
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
298
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
299 \deprecated{2.3}{Instead convert to float using \function{abs()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
300 if appropriate.}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
301
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 % XXXJH exceptions: overflow (when? what operations?) zerodivision
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304
10241
f138ba72bf2d Update description of what modules "look like" when printed.
Fred Drake <fdrake@acm.org>
parents: 10156
diff changeset
305 \subsubsection{Bit-string Operations on Integer Types \label{bitstring-ops}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306 \nodename{Bit-string Operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308 Plain and long integer types support additional operations that make
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309 sense only for bit-strings. Negative numbers are treated as their 2's
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 complement value (for long integers, this assumes a sufficiently large
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311 number of bits that no overflow occurs during the operation).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
312
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
313 The priorities of the binary bit-wise operations are all lower than
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
314 the numeric operations and higher than the comparisons; the unary
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 operation \samp{\~} has the same priority as the other unary numeric
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
316 operations (\samp{+} and \samp{-}).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
317
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318 This table lists the bit-string operations sorted in ascending
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
319 priority (operations in the same box have the same priority):
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
323 \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
324 \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
33970
023801332395 Fix SF bug #1061770: Manual typesets bit-shift operators as guillemet
Fred Drake <fdrake@acm.org>
parents: 33899
diff changeset
325 % The empty groups below prevent conversion to guillemets.
023801332395 Fix SF bug #1061770: Manual typesets bit-shift operators as guillemet
Fred Drake <fdrake@acm.org>
parents: 33899
diff changeset
326 \lineiii{\var{x} <{}< \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
023801332395 Fix SF bug #1061770: Manual typesets bit-shift operators as guillemet
Fred Drake <fdrake@acm.org>
parents: 33899
diff changeset
327 \lineiii{\var{x} >{}> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
328 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
329 \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
330 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
331 \indexiii{operations on}{integer}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
332 \indexii{bit-string}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
333 \indexii{shifting}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
334 \indexii{masking}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
339 \item[(1)] Negative shift counts are illegal and cause a
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 \exception{ValueError} to be raised.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341 \item[(2)] A left shift by \var{n} bits is equivalent to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342 multiplication by \code{pow(2, \var{n})} without overflow check.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
343 \item[(3)] A right shift by \var{n} bits is equivalent to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
344 division by \code{pow(2, \var{n})} without overflow check.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
347
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
348 \subsection{Iterator Types \label{typeiter}}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
349
17663
d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version
Fred Drake <fdrake@acm.org>
parents: 17658
diff changeset
350 \versionadded{2.2}
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
351 \index{iterator protocol}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
352 \index{protocol!iterator}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
353 \index{sequence!iteration}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
354 \index{container!iteration over}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
355
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
356 Python supports a concept of iteration over containers. This is
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
357 implemented using two distinct methods; these are used to allow
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
358 user-defined classes to support iteration. Sequences, described below
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
359 in more detail, always support the iteration methods.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
360
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
361 One method needs to be defined for container objects to provide
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
362 iteration support:
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
363
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
364 \begin{methoddesc}[container]{__iter__}{}
18839
ab8aa4302109 Typo fix.
Greg Ward <gward@python.net>
parents: 18829
diff changeset
365 Return an iterator object. The object is required to support the
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
366 iterator protocol described below. If a container supports
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
367 different types of iteration, additional methods can be provided to
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
368 specifically request iterators for those iteration types. (An
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
369 example of an object supporting multiple forms of iteration would be
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
370 a tree structure which supports both breadth-first and depth-first
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
371 traversal.) This method corresponds to the \member{tp_iter} slot of
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
372 the type structure for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
373 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
374
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
375 The iterator objects themselves are required to support the following
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
376 two methods, which together form the \dfn{iterator protocol}:
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
377
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
378 \begin{methoddesc}[iterator]{__iter__}{}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
379 Return the iterator object itself. This is required to allow both
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
380 containers and iterators to be used with the \keyword{for} and
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
381 \keyword{in} statements. This method corresponds to the
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
382 \member{tp_iter} slot of the type structure for Python objects in
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
383 the Python/C API.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
384 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
385
17663
d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version
Fred Drake <fdrake@acm.org>
parents: 17658
diff changeset
386 \begin{methoddesc}[iterator]{next}{}
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
387 Return the next item from the container. If there are no further
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
388 items, raise the \exception{StopIteration} exception. This method
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
389 corresponds to the \member{tp_iternext} slot of the type structure
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
390 for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
391 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
392
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
393 Python defines several iterator objects to support iteration over
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
394 general and specific sequence types, dictionaries, and other more
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
395 specialized forms. The specific types are not important beyond their
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
396 implementation of the iterator protocol.
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
397
24253
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
398 The intention of the protocol is that once an iterator's
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
399 \method{next()} method raises \exception{StopIteration}, it will
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
400 continue to do so on subsequent calls. Implementations that
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
401 do not obey this property are deemed broken. (This constraint
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
402 was added in Python 2.3; in Python 2.2, various iterators are
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
403 broken according to this rule.)
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent
Guido van Rossum <guido@python.org>
parents: 24227
diff changeset
404
29590
8807e901c526 SF bug #696777: How to make a class iterable using a member generator.
Raymond Hettinger <python@rcn.com>
parents: 29516
diff changeset
405 Python's generators provide a convenient way to implement the
8807e901c526 SF bug #696777: How to make a class iterable using a member generator.
Raymond Hettinger <python@rcn.com>
parents: 29516
diff changeset
406 iterator protocol. If a container object's \method{__iter__()}
8807e901c526 SF bug #696777: How to make a class iterable using a member generator.
Raymond Hettinger <python@rcn.com>
parents: 29516
diff changeset
407 method is implemented as a generator, it will automatically
8807e901c526 SF bug #696777: How to make a class iterable using a member generator.
Raymond Hettinger <python@rcn.com>
parents: 29516
diff changeset
408 return an iterator object (technically, a generator object)
8807e901c526 SF bug #696777: How to make a class iterable using a member generator.
Raymond Hettinger <python@rcn.com>
parents: 29516
diff changeset
409 supplying the \method{__iter__()} and \method{next()} methods.
8807e901c526 SF bug #696777: How to make a class iterable using a member generator.
Raymond Hettinger <python@rcn.com>
parents: 29516
diff changeset
410
17658
d6498b1ef50d Added section describing the iterator protocol.
Fred Drake <fdrake@acm.org>
parents: 17616
diff changeset
411
35074
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
412 \subsection{Sequence Types ---
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
413 \class{str}, \class{unicode}, \class{list},
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
414 \class{tuple}, \class{buffer}, \class{xrange}
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
415 \label{typesseq}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
416
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
417 There are six sequence types: strings, Unicode strings, lists,
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
418 tuples, buffers, and xrange objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
419
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
420 String literals are written in single or double quotes:
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
421 \code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
422 \citetitle[../ref/strings.html]{Python Reference Manual} for more about
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
423 string literals. Unicode strings are much like strings, but are
34296
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 34078
diff changeset
424 specified in the syntax using a preceding \character{u} character:
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
425 \code{u'abc'}, \code{u"def"}. Lists are constructed with square brackets,
11463
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
426 separating items with commas: \code{[a, b, c]}. Tuples are
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
427 constructed by the comma operator (not within square brackets), with
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
428 or without enclosing parentheses, but an empty tuple must have the
30375
4aa84a8b1fe4 Fix spacing markup and other sundries.
Raymond Hettinger <python@rcn.com>
parents: 30250
diff changeset
429 enclosing parentheses, such as \code{a, b, c} or \code{()}. A single
4aa84a8b1fe4 Fix spacing markup and other sundries.
Raymond Hettinger <python@rcn.com>
parents: 30250
diff changeset
430 item tuple must have a trailing comma, such as \code{(d,)}.
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
431 \obindex{sequence}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
432 \obindex{string}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
433 \obindex{Unicode}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
434 \obindex{tuple}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
435 \obindex{list}
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
436
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
437 Buffer objects are not directly supported by Python syntax, but can be
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
438 created by calling the builtin function
25393
f559e97a41be Remove spurious period.
Fred Drake <fdrake@acm.org>
parents: 24902
diff changeset
439 \function{buffer()}.\bifuncindex{buffer} They don't support
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
440 concatenation or repetition.
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
441 \obindex{buffer}
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
442
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
443 Xrange objects are similar to buffers in that there is no specific
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
444 syntax to create them, but they are created using the \function{xrange()}
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
445 function.\bifuncindex{xrange} They don't support slicing,
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
446 concatenation or repetition, and using \code{in}, \code{not in},
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
447 \function{min()} or \function{max()} on them is inefficient.
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
448 \obindex{xrange}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
449
18395
1d0d3e6a3201 List constraints on xrange() objects.
Guido van Rossum <guido@python.org>
parents: 18391
diff changeset
450 Most sequence types support the following operations. The \samp{in} and
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
451 \samp{not in} operations have the same priorities as the comparison
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
452 operations. The \samp{+} and \samp{*} operations have the same
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
453 priority as the corresponding numeric operations.\footnote{They must
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
454 have since the parser can't tell the type of the operands.}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
455
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
456 This table lists the sequence operations sorted in ascending priority
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
457 (operations in the same box have the same priority). In the table,
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
458 \var{s} and \var{t} are sequences of the same type; \var{n}, \var{i}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
459 and \var{j} are integers:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
460
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
461 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
33688
af300403edb8 SF patch #1041364: True/False instead of 1/0 in libstdtypes.tex
Raymond Hettinger <python@rcn.com>
parents: 33448
diff changeset
462 \lineiii{\var{x} in \var{s}}{\code{True} if an item of \var{s} is equal to \var{x}, else \code{False}}{(1)}
af300403edb8 SF patch #1041364: True/False instead of 1/0 in libstdtypes.tex
Raymond Hettinger <python@rcn.com>
parents: 33448
diff changeset
463 \lineiii{\var{x} not in \var{s}}{\code{False} if an item of \var{s} is
af300403edb8 SF patch #1041364: True/False instead of 1/0 in libstdtypes.tex
Raymond Hettinger <python@rcn.com>
parents: 33448
diff changeset
464 equal to \var{x}, else \code{True}}{(1)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
465 \hline
32974
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
466 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{(6)}
24598
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
467 \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(2)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
468 \hline
24598
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
469 \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(3)}
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
470 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(3), (4)}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
471 \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(3), (5)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
472 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
473 \lineiii{len(\var{s})}{length of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
474 \lineiii{min(\var{s})}{smallest item of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
475 \lineiii{max(\var{s})}{largest item of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
476 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
477 \indexiii{operations on}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
478 \bifuncindex{len}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
479 \bifuncindex{min}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
480 \bifuncindex{max}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
481 \indexii{concatenation}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
482 \indexii{repetition}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
483 \indexii{subscript}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
484 \indexii{slice}{operation}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
485 \indexii{extended slice}{operation}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
486 \opindex{in}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
487 \opindex{not in}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
488
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
489 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
490 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
491
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
492 \begin{description}
24598
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
493 \item[(1)] When \var{s} is a string or Unicode string object the
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
494 \code{in} and \code{not in} operations act like a substring test. In
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
495 Python versions before 2.3, \var{x} had to be a string of length 1.
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
496 In Python 2.3 and beyond, \var{x} may be a string of any length.
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
497
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
498 \item[(2)] Values of \var{n} less than \code{0} are treated as
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
499 \code{0} (which yields an empty sequence of the same type as
19529
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
500 \var{s}). Note also that the copies are shallow; nested structures
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
501 are not copied. This often haunts new Python programmers; consider:
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
502
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
503 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
504 >>> lists = [[]] * 3
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
505 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
506 [[], [], []]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
507 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
508 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
509 [[3], [3], [3]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
510 \end{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
511
33899
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
512 What has happened is that \code{[[]]} is a one-element list containing
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
513 an empty list, so all three elements of \code{[[]] * 3} are (pointers to)
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
514 this single empty list. Modifying any of the elements of \code{lists}
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
515 modifies this single list. You can create a list of different lists this
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
516 way:
19529
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
517
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
518 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
519 >>> lists = [[] for i in range(3)]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
520 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
521 >>> lists[1].append(5)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
522 >>> lists[2].append(7)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
523 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
524 [[3], [5], [7]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so
Fred Drake <fdrake@acm.org>
parents: 19243
diff changeset
525 \end{verbatim}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
526
24598
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
527 \item[(3)] If \var{i} or \var{j} is negative, the index is relative to
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
528 the end of the string: \code{len(\var{s}) + \var{i}} or
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
529 \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
530 still \code{0}.
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
531
24598
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a
Barry Warsaw <barry@python.org>
parents: 24459
diff changeset
532 \item[(4)] The slice of \var{s} from \var{i} to \var{j} is defined as
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
533 the sequence of items with index \var{k} such that \code{\var{i} <=
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
534 \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
535 \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted,
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
536 use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
537 \var{i} is greater than or equal to \var{j}, the slice is empty.
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
538
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
539 \item[(5)] The slice of \var{s} from \var{i} to \var{j} with step
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
540 \var{k} is defined as the sequence of items with index
33899
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
541 \code{\var{x} = \var{i} + \var{n}*\var{k}} such that
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
542 $0 \leq n < \frac{j-i}{k}$. In other words, the indices
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
543 are \code{i}, \code{i+k}, \code{i+2*k}, \code{i+3*k} and so on, stopping when
eb979c3f14ba Mistakes in the "sequence types" page:
Armin Rigo <arigo@tunes.org>
parents: 33688
diff changeset
544 \var{j} is reached (but never including \var{j}). If \var{i} or \var{j}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
545 is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If
30250
830c0cd8fdb2 SF patch #797180: Bug 792656: slicing explained
Raymond Hettinger <python@rcn.com>
parents: 30095
diff changeset
546 \var{i} or \var{j} are omitted then they become ``end'' values
830c0cd8fdb2 SF patch #797180: Bug 792656: slicing explained
Raymond Hettinger <python@rcn.com>
parents: 30095
diff changeset
547 (which end depends on the sign of \var{k}). Note, \var{k} cannot
830c0cd8fdb2 SF patch #797180: Bug 792656: slicing explained
Raymond Hettinger <python@rcn.com>
parents: 30095
diff changeset
548 be zero.
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
549
32974
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
550 \item[(6)] If \var{s} and \var{t} are both strings, some Python
32975
9b188158181f Typo fix; use 'in-place' instead of 'inplace'
Andrew M. Kuchling <amk@amk.ca>
parents: 32974
diff changeset
551 implementations such as CPython can usually perform an in-place optimization
32974
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
552 for assignments of the form \code{\var{s}=\var{s}+\var{t}} or
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
553 \code{\var{s}+=\var{t}}. When applicable, this optimization makes
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
554 quadratic run-time much less likely. This optimization is both version
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
555 and implementation dependent. For performance sensitive code, it is
34296
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 34078
diff changeset
556 preferable to use the \method{str.join()} method which assures consistent
32974
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
557 linear concatenation performance across versions and implementations.
32975
9b188158181f Typo fix; use 'in-place' instead of 'inplace'
Andrew M. Kuchling <amk@amk.ca>
parents: 32974
diff changeset
558 \versionchanged[Formerly, string concatenation never occurred in-place]{2.4}
32974
fb6ffd290cfb SF patch #980695: efficient string concatenation
Raymond Hettinger <python@rcn.com>
parents: 32951
diff changeset
559
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
560 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
561
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
562
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
563 \subsubsection{String Methods \label{string-methods}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
564
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
565 These are the string methods which both 8-bit strings and Unicode
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
566 objects support:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
567
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
568 \begin{methoddesc}[string]{capitalize}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
569 Return a copy of the string with only its first character capitalized.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
570
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
571 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
572 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
573
31021
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
574 \begin{methoddesc}[string]{center}{width\optional{, fillchar}}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
575 Return centered in a string of length \var{width}. Padding is done
31021
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
576 using the specified \var{fillchar} (default is a space).
31022
845f19b145a8 Add version changed doc for addition of fillchar to ljust/rjust/center
Neal Norwitz <nnorwitz@gmail.com>
parents: 31021
diff changeset
577 \versionchanged[Support for the \var{fillchar} argument]{2.4}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
578 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
579
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
580 \begin{methoddesc}[string]{count}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
581 Return the number of occurrences of substring \var{sub} in string
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
582 S\code{[\var{start}:\var{end}]}. Optional arguments \var{start} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
583 \var{end} are interpreted as in slice notation.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
584 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
585
21332
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
586 \begin{methoddesc}[string]{decode}{\optional{encoding\optional{, errors}}}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
587 Decodes the string using the codec registered for \var{encoding}.
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
588 \var{encoding} defaults to the default string encoding. \var{errors}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
589 may be given to set a different error handling scheme. The default is
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
590 \code{'strict'}, meaning that encoding errors raise
32459
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
591 \exception{UnicodeError}. Other possible values are \code{'ignore'},
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
592 \code{'replace'} and any other name registered via
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
593 \function{codecs.register_error}.
21332
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
594 \versionadded{2.2}
32459
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
595 \versionchanged[Support for other error handling schemes added]{2.3}
21332
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
596 \end{methoddesc}
fbbd8a4ca7a6 Added documentation for str.decode().
Fred Drake <fdrake@acm.org>
parents: 21177
diff changeset
597
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
598 \begin{methoddesc}[string]{encode}{\optional{encoding\optional{,errors}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
599 Return an encoded version of the string. Default encoding is the current
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
600 default string encoding. \var{errors} may be given to set a different
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
601 error handling scheme. The default for \var{errors} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
602 \code{'strict'}, meaning that encoding errors raise a
32459
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
603 \exception{UnicodeError}. Other possible values are \code{'ignore'},
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
604 \code{'replace'}, \code{'xmlcharrefreplace'}, \code{'backslashreplace'}
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
605 and any other name registered via \function{codecs.register_error}.
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
606 For a list of possible encodings, see section~\ref{standard-encodings}.
15332
12aec3381c94 Marc-Andre Lemburg <mal@lemburg.com> noted that the encode() string method
Fred Drake <fdrake@acm.org>
parents: 15005
diff changeset
607 \versionadded{2.0}
32459
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
608 \versionchanged[Support for \code{'xmlcharrefreplace'} and
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError
Walter Dörwald <walter@livinglogic.de>
parents: 32458
diff changeset
609 \code{'backslashreplace'} and other error handling schemes added]{2.3}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
610 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
611
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
612 \begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
613 Return \code{True} if the string ends with the specified \var{suffix},
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
614 otherwise return \code{False}. With optional \var{start}, test beginning at
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
615 that position. With optional \var{end}, stop comparing at that position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
616 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
617
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
618 \begin{methoddesc}[string]{expandtabs}{\optional{tabsize}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
619 Return a copy of the string where all tab characters are expanded
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
620 using spaces. If \var{tabsize} is not given, a tab size of \code{8}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
621 characters is assumed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
622 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
623
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
624 \begin{methoddesc}[string]{find}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
625 Return the lowest index in the string where substring \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
626 found, such that \var{sub} is contained in the range [\var{start},
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
627 \var{end}). Optional arguments \var{start} and \var{end} are
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
628 interpreted as in slice notation. Return \code{-1} if \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
629 not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
630 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
631
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
632 \begin{methoddesc}[string]{index}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
633 Like \method{find()}, but raise \exception{ValueError} when the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
634 substring is not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
635 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
636
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
637 \begin{methoddesc}[string]{isalnum}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
638 Return true if all characters in the string are alphanumeric and there
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
639 is at least one character, false otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
640
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
641 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
642 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
643
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
644 \begin{methoddesc}[string]{isalpha}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
645 Return true if all characters in the string are alphabetic and there
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
646 is at least one character, false otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
647
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
648 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
649 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
650
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
651 \begin{methoddesc}[string]{isdigit}{}
30707
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings.
Martin v. Löwis <martin@v.loewis.de>
parents: 30705
diff changeset
652 Return true if all characters in the string are digits and there
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings.
Martin v. Löwis <martin@v.loewis.de>
parents: 30705
diff changeset
653 is at least one character, false otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
654
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
655 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
656 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
657
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
658 \begin{methoddesc}[string]{islower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
659 Return true if all cased characters in the string are lowercase and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
660 there is at least one cased character, false otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
661
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
662 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
663 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
664
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
665 \begin{methoddesc}[string]{isspace}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
666 Return true if there are only whitespace characters in the string and
30707
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings.
Martin v. Löwis <martin@v.loewis.de>
parents: 30705
diff changeset
667 there is at least one character, false otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
668
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
669 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
670 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
671
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
672 \begin{methoddesc}[string]{istitle}{}
30707
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings.
Martin v. Löwis <martin@v.loewis.de>
parents: 30705
diff changeset
673 Return true if the string is a titlecased string and there is at least one
30810
2cba0de70df6 Add list.sorted() classmethod.
Raymond Hettinger <python@rcn.com>
parents: 30750
diff changeset
674 character, for example uppercase characters may only follow uncased
30707
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings.
Martin v. Löwis <martin@v.loewis.de>
parents: 30705
diff changeset
675 characters and lowercase characters only cased ones. Return false
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings.
Martin v. Löwis <martin@v.loewis.de>
parents: 30705
diff changeset
676 otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
677
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
678 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
679 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
680
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
681 \begin{methoddesc}[string]{isupper}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
682 Return true if all cased characters in the string are uppercase and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
683 there is at least one cased character, false otherwise.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
684
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
685 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
686 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
687
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
688 \begin{methoddesc}[string]{join}{seq}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
689 Return a string which is the concatenation of the strings in the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
690 sequence \var{seq}. The separator between elements is the string
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
691 providing this method.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
692 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
693
31021
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
694 \begin{methoddesc}[string]{ljust}{width\optional{, fillchar}}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
695 Return the string left justified in a string of length \var{width}.
31021
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
696 Padding is done using the specified \var{fillchar} (default is a
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
697 space). The original string is returned if
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
698 \var{width} is less than \code{len(\var{s})}.
31022
845f19b145a8 Add version changed doc for addition of fillchar to ljust/rjust/center
Neal Norwitz <nnorwitz@gmail.com>
parents: 31021
diff changeset
699 \versionchanged[Support for the \var{fillchar} argument]{2.4}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
700 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
701
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
702 \begin{methoddesc}[string]{lower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
703 Return a copy of the string converted to lowercase.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
704
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
705 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
706 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
707
23017
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string
Fred Drake <fdrake@acm.org>
parents: 22994
diff changeset
708 \begin{methoddesc}[string]{lstrip}{\optional{chars}}
34975
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
709 Return a copy of the string with leading characters removed. The
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
710 \var{chars} argument is a string specifying the set of characters
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
711 to be removed. If omitted or \code{None}, the \var{chars} argument
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
712 defaults to removing whitespace. The \var{chars} argument is not
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
713 a prefix; rather, all combinations of its values are stripped:
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
714 \begin{verbatim}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
715 >>> ' spacious '.lstrip()
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
716 'spacious '
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
717 >>> 'www.example.com'.lstrip('cmowz.')
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
718 'example.com'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
719 \end{verbatim}
26259
60d809a25bae Document that a minor feature was added in 2.2.2. ;-(
Fred Drake <fdrake@acm.org>
parents: 26161
diff changeset
720 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
721 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
722
30750
1d92ecdf2bb1 Avoid confusing name for the 3rd argument to str.replace().
Fred Drake <fdrake@acm.org>
parents: 30737
diff changeset
723 \begin{methoddesc}[string]{replace}{old, new\optional{, count}}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
724 Return a copy of the string with all occurrences of substring
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
725 \var{old} replaced by \var{new}. If the optional argument
30750
1d92ecdf2bb1 Avoid confusing name for the 3rd argument to str.replace().
Fred Drake <fdrake@acm.org>
parents: 30737
diff changeset
726 \var{count} is given, only the first \var{count} occurrences are
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
727 replaced.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
728 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
729
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
730 \begin{methoddesc}[string]{rfind}{sub \optional{,start \optional{,end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
731 Return the highest index in the string where substring \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
732 found, such that \var{sub} is contained within s[start,end]. Optional
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
733 arguments \var{start} and \var{end} are interpreted as in slice
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
734 notation. Return \code{-1} on failure.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
735 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
736
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
737 \begin{methoddesc}[string]{rindex}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
738 Like \method{rfind()} but raises \exception{ValueError} when the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
739 substring \var{sub} is not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
740 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
741
31021
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
742 \begin{methoddesc}[string]{rjust}{width\optional{, fillchar}}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
743 Return the string right justified in a string of length \var{width}.
31021
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
744 Padding is done using the specified \var{fillchar} (default is a space).
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods.
Raymond Hettinger <python@rcn.com>
parents: 31008
diff changeset
745 The original string is returned if
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
746 \var{width} is less than \code{len(\var{s})}.
31022
845f19b145a8 Add version changed doc for addition of fillchar to ljust/rjust/center
Neal Norwitz <nnorwitz@gmail.com>
parents: 31021
diff changeset
747 \versionchanged[Support for the \var{fillchar} argument]{2.4}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
748 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
749
31206
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
750 \begin{methoddesc}[string]{rsplit}{\optional{sep \optional{,maxsplit}}}
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
751 Return a list of the words in the string, using \var{sep} as the
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31199
diff changeset
752 delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
753 splits are done, the \emph{rightmost} ones. If \var{sep} is not specified
34491
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
754 or \code{None}, any whitespace string is a separator. Except for splitting
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
755 from the right, \method{rsplit()} behaves like \method{split()} which
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
756 is described in detail below.
31199
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31022
diff changeset
757 \versionadded{2.4}
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31022
diff changeset
758 \end{methoddesc}
504943c89193 Add rsplit method for str and unicode builtin types.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31022
diff changeset
759
23017
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string
Fred Drake <fdrake@acm.org>
parents: 22994
diff changeset
760 \begin{methoddesc}[string]{rstrip}{\optional{chars}}
34975
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
761 Return a copy of the string with trailing characters removed. The
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
762 \var{chars} argument is a string specifying the set of characters
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
763 to be removed. If omitted or \code{None}, the \var{chars} argument
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
764 defaults to removing whitespace. The \var{chars} argument is not
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
765 a suffix; rather, all combinations of its values are stripped:
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
766 \begin{verbatim}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
767 >>> ' spacious '.rstrip()
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
768 ' spacious'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
769 >>> 'mississippi'.rstrip('ipz')
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
770 'mississ'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
771 \end{verbatim}
26259
60d809a25bae Document that a minor feature was added in 2.2.2. ;-(
Fred Drake <fdrake@acm.org>
parents: 26161
diff changeset
772 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
773 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
774
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
775 \begin{methoddesc}[string]{split}{\optional{sep \optional{,maxsplit}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
776 Return a list of the words in the string, using \var{sep} as the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
777 delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
33411
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
778 splits are done. (thus, the list will have at most \code{\var{maxsplit}+1}
34508
13176ed52e65 SF bug #1108303: fix .split() maxsplit doc
Raymond Hettinger <python@rcn.com>
parents: 34491
diff changeset
779 elements). If \var{maxsplit} is not specified, then there
33411
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
780 is no limit on the number of splits (all possible splits are made).
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
781 Consecutive delimiters are not grouped together and are
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
782 deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')}
33412
c09318b0090d Add missing close parenthesis.
Raymond Hettinger <python@rcn.com>
parents: 33411
diff changeset
783 returns \samp{['1', '', '2']}). The \var{sep} argument may consist of
33411
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
784 multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns
33412
c09318b0090d Add missing close parenthesis.
Raymond Hettinger <python@rcn.com>
parents: 33411
diff changeset
785 \samp{['1', '2', '3']}). Splitting an empty string with a specified
34917
6bdc3426d411 Correct swapped descriptions of empty string splits.
Raymond Hettinger <python@rcn.com>
parents: 34898
diff changeset
786 separator returns \samp{['']}.
33411
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
787
136b388569a0 SF bug #901654: split method documentation can be improved
Raymond Hettinger <python@rcn.com>
parents: 33102
diff changeset
788 If \var{sep} is not specified or is \code{None}, a different splitting
34491
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
789 algorithm is applied. First, whitespace characters (spaces, tabs,
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
790 newlines, returns, and formfeeds) are stripped from both ends. Then,
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
791 words are separated by arbitrary length strings of whitespace
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
792 characters. Consecutive whitespace delimiters are treated as a single
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
793 delimiter (\samp{'1 2 3'.split()} returns \samp{['1', '2', '3']}).
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method
Raymond Hettinger <python@rcn.com>
parents: 34296
diff changeset
794 Splitting an empty string or a string consisting of just whitespace
34917
6bdc3426d411 Correct swapped descriptions of empty string splits.
Raymond Hettinger <python@rcn.com>
parents: 34898
diff changeset
795 returns an empty list.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
796 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
797
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
798 \begin{methoddesc}[string]{splitlines}{\optional{keepends}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
799 Return a list of the lines in the string, breaking at line
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
800 boundaries. Line breaks are not included in the resulting list unless
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
801 \var{keepends} is given and true.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
802 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
803
23017
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string
Fred Drake <fdrake@acm.org>
parents: 22994
diff changeset
804 \begin{methoddesc}[string]{startswith}{prefix\optional{,
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string
Fred Drake <fdrake@acm.org>
parents: 22994
diff changeset
805 start\optional{, end}}}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
806 Return \code{True} if string starts with the \var{prefix}, otherwise
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
807 return \code{False}. With optional \var{start}, test string beginning at
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
808 that position. With optional \var{end}, stop comparing string at that
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
809 position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
810 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
811
23017
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string
Fred Drake <fdrake@acm.org>
parents: 22994
diff changeset
812 \begin{methoddesc}[string]{strip}{\optional{chars}}
34975
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
813 Return a copy of the string with the leading and trailing characters
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
814 removed. The \var{chars} argument is a string specifying the set of
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
815 characters to be removed. If omitted or \code{None}, the \var{chars}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
816 argument defaults to removing whitespace. The \var{chars} argument is not
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
817 a prefix or suffix; rather, all combinations of its values are stripped:
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
818 \begin{verbatim}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
819 >>> ' spacious '.strip()
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
820 'spacious'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
821 >>> 'www.example.com'.strip('cmowz.')
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
822 'example'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement
Raymond Hettinger <python@rcn.com>
parents: 34969
diff changeset
823 \end{verbatim}
26259
60d809a25bae Document that a minor feature was added in 2.2.2. ;-(
Fred Drake <fdrake@acm.org>
parents: 26161
diff changeset
824 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
825 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
826
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
827 \begin{methoddesc}[string]{swapcase}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
828 Return a copy of the string with uppercase characters converted to
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
829 lowercase and vice versa.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
830
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
831 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
832 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
833
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
834 \begin{methoddesc}[string]{title}{}
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
835 Return a titlecased version of the string: words start with uppercase
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
836 characters, all remaining cased characters are lowercase.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
837
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
838 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
839 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
840
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
841 \begin{methoddesc}[string]{translate}{table\optional{, deletechars}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
842 Return a copy of the string where all characters occurring in the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
843 optional argument \var{deletechars} are removed, and the remaining
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
844 characters have been mapped through the given translation table, which
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
845 must be a string of length 256.
29893
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
846
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
847 For Unicode objects, the \method{translate()} method does not
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
848 accept the optional \var{deletechars} argument. Instead, it
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
849 returns a copy of the \var{s} where all characters have been mapped
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
850 through the given translation table which must be a mapping of
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
851 Unicode ordinals to Unicode ordinals, Unicode strings or \code{None}.
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
852 Unmapped characters are left untouched. Characters mapped to \code{None}
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
853 are deleted. Note, a more flexible approach is to create a custom
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
854 character mapping codec using the \refmodule{codecs} module (see
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate()
Raymond Hettinger <python@rcn.com>
parents: 29590
diff changeset
855 \module{encodings.cp1251} for an example).
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
856 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
857
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
858 \begin{methoddesc}[string]{upper}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
859 Return a copy of the string converted to uppercase.
32214
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
860
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749.
Martin v. Löwis <martin@v.loewis.de>
parents: 32197
diff changeset
861 For 8-bit strings, this method is locale-dependent.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
862 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
863
23045
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241
Walter Dörwald <walter@livinglogic.de>
parents: 23017
diff changeset
864 \begin{methoddesc}[string]{zfill}{width}
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241
Walter Dörwald <walter@livinglogic.de>
parents: 23017
diff changeset
865 Return the numeric string left filled with zeros in a string
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241
Walter Dörwald <walter@livinglogic.de>
parents: 23017
diff changeset
866 of length \var{width}. The original string is returned if
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241
Walter Dörwald <walter@livinglogic.de>
parents: 23017
diff changeset
867 \var{width} is less than \code{len(\var{s})}.
26260
b327ffcfe9b7 Better note that str.zfill() was added in 2.2.2 as well. ;-(
Fred Drake <fdrake@acm.org>
parents: 26259
diff changeset
868 \versionadded{2.2.2}
23045
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241
Walter Dörwald <walter@livinglogic.de>
parents: 23017
diff changeset
869 \end{methoddesc}
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241
Walter Dörwald <walter@livinglogic.de>
parents: 23017
diff changeset
870
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
871
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
872 \subsubsection{String Formatting Operations \label{typesseq-strings}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
873
21177
7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments
Fred Drake <fdrake@acm.org>
parents: 21163
diff changeset
874 \index{formatting, string (\%{})}
21542
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
875 \index{interpolation, string (\%{})}
14552
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
876 \index{string!formatting}
21542
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
877 \index{string!interpolation}
14552
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
878 \index{printf-style formatting}
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
879 \index{sprintf-style formatting}
21177
7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments
Fred Drake <fdrake@acm.org>
parents: 21163
diff changeset
880 \index{\protect\%{} formatting}
21542
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
881 \index{\protect\%{} interpolation}
14552
a8d1c030b19f Add some index entries to make it easier to find information on
Fred Drake <fdrake@acm.org>
parents: 14520
diff changeset
882
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
883 String and Unicode objects have one unique built-in operation: the
21542
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
884 \code{\%} operator (modulo). This is also known as the string
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
885 \emph{formatting} or \emph{interpolation} operator. Given
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
886 \code{\var{format} \% \var{values}} (where \var{format} is a string or
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
887 Unicode object), \code{\%} conversion specifications in \var{format}
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
888 are replaced with zero or more elements of \var{values}. The effect
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
889 is similar to the using \cfunction{sprintf()} in the C language. If
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
890 \var{format} is a Unicode object, or if any of the objects being
5d4135609efc Added index entries similar to some recommended by Skip, and used the word
Fred Drake <fdrake@acm.org>
parents: 21332
diff changeset
891 converted using the \code{\%s} conversion are Unicode objects, the
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
892 result will also be a Unicode object.
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
893
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
894 If \var{format} requires a single argument, \var{values} may be a
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
895 single non-tuple object.\footnote{To format only a tuple you
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
896 should therefore provide a singleton tuple whose only element
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
897 is the tuple to be formatted.} Otherwise, \var{values} must be a tuple with
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
898 exactly the number of items specified by the format string, or a
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
899 single mapping object (for example, a dictionary).
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
900
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
901 A conversion specifier contains two or more characters and has the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
902 following components, which must occur in this order:
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
903
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
904 \begin{enumerate}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
905 \item The \character{\%} character, which marks the start of the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
906 specifier.
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
907 \item Mapping key (optional), consisting of a parenthesised sequence
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
908 of characters (for example, \code{(somename)}).
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
909 \item Conversion flags (optional), which affect the result of some
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
910 conversion types.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
911 \item Minimum field width (optional). If specified as an
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
912 \character{*} (asterisk), the actual width is read from the
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
913 next element of the tuple in \var{values}, and the object to
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
914 convert comes after the minimum field width and optional
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
915 precision.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
916 \item Precision (optional), given as a \character{.} (dot) followed
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
917 by the precision. If specified as \character{*} (an
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
918 asterisk), the actual width is read from the next element of
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
919 the tuple in \var{values}, and the value to convert comes after
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
920 the precision.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
921 \item Length modifier (optional).
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
922 \item Conversion type.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
923 \end{enumerate}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
924
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
925 When the right argument is a dictionary (or other mapping type), then
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
926 the formats in the string \emph{must} include a parenthesised mapping key into
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
927 that dictionary inserted immediately after the \character{\%}
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
928 character. The mapping key selects the value to be formatted from the
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
929 mapping. For example:
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
930
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
931 \begin{verbatim}
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
932 >>> print '%(language)s has %(#)03d quote types.' % \
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
933 {'language': "Python", "#": 2}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
934 Python has 002 quote types.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
935 \end{verbatim}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
936
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
937 In this case no \code{*} specifiers may occur in a format (since they
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
938 require a sequential parameter list).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
939
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
940 The conversion flag characters are:
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
941
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
942 \begin{tableii}{c|l}{character}{Flag}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
943 \lineii{\#}{The value conversion will use the ``alternate form''
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
944 (where defined below).}
27919
4b5c2e025c5e Fix SF bug #687655, String formatting conversions misleading
Neal Norwitz <nnorwitz@gmail.com>
parents: 27225
diff changeset
945 \lineii{0}{The conversion will be zero padded for numeric values.}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
946 \lineii{-}{The converted value is left adjusted (overrides
25906
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
947 the \character{0} conversion if both are given).}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
948 \lineii{{~}}{(a space) A blank should be left before a positive number
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
949 (or empty string) produced by a signed conversion.}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
950 \lineii{+}{A sign character (\character{+} or \character{-}) will
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
951 precede the conversion (overrides a "space" flag).}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
952 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
953
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
954 The length modifier may be \code{h}, \code{l}, and \code{L} may be
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
955 present, but are ignored as they are not necessary for Python.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
956
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
957 The conversion types are:
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
958
25906
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
959 \begin{tableiii}{c|l|c}{character}{Conversion}{Meaning}{Notes}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
960 \lineiii{d}{Signed integer decimal.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
961 \lineiii{i}{Signed integer decimal.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
962 \lineiii{o}{Unsigned octal.}{(1)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
963 \lineiii{u}{Unsigned decimal.}{}
34296
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 34078
diff changeset
964 \lineiii{x}{Unsigned hexadecimal (lowercase).}{(2)}
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 34078
diff changeset
965 \lineiii{X}{Unsigned hexadecimal (uppercase).}{(2)}
25906
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
966 \lineiii{e}{Floating point exponential format (lowercase).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
967 \lineiii{E}{Floating point exponential format (uppercase).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
968 \lineiii{f}{Floating point decimal format.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
969 \lineiii{F}{Floating point decimal format.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
970 \lineiii{g}{Same as \character{e} if exponent is greater than -4 or
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
971 less than precision, \character{f} otherwise.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
972 \lineiii{G}{Same as \character{E} if exponent is greater than -4 or
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
973 less than precision, \character{F} otherwise.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
974 \lineiii{c}{Single character (accepts integer or single character
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
975 string).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
976 \lineiii{r}{String (converts any python object using
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
977 \function{repr()}).}{(3)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
978 \lineiii{s}{String (converts any python object using
27225
5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and
Raymond Hettinger <python@rcn.com>
parents: 27036
diff changeset
979 \function{str()}).}{(4)}
25906
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
980 \lineiii{\%}{No argument is converted, results in a \character{\%}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
981 character in the result.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
982 \end{tableiii}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
983
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
984 \noindent
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
985 Notes:
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
986 \begin{description}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
987 \item[(1)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
988 The alternate form causes a leading zero (\character{0}) to be
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
989 inserted between left-hand padding and the formatting of the
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
990 number if the leading character of the result is not already a
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
991 zero.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
992 \item[(2)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
993 The alternate form causes a leading \code{'0x'} or \code{'0X'}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
994 (depending on whether the \character{x} or \character{X} format
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
995 was used) to be inserted between left-hand padding and the
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
996 formatting of the number if the leading character of the result is
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
997 not already a zero.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
998 \item[(3)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
999 The \code{\%r} conversion was added in Python 2.0.
27225
5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and
Raymond Hettinger <python@rcn.com>
parents: 27036
diff changeset
1000 \item[(4)]
5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and
Raymond Hettinger <python@rcn.com>
parents: 27036
diff changeset
1001 If the object or format provided is a \class{unicode} string,
5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and
Raymond Hettinger <python@rcn.com>
parents: 27036
diff changeset
1002 the resulting string will also be \class{unicode}.
25906
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag.
Fred Drake <fdrake@acm.org>
parents: 25393
diff changeset
1003 \end{description}
16285
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1004
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1005 % XXX Examples?
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1006
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1007 Since Python strings have an explicit length, \code{\%s} conversions
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1008 do not assume that \code{'\e0'} is the end of the string.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1009
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1010 For safety reasons, floating point precisions are clipped to 50;
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1011 \code{\%f} conversions for numbers whose absolute value is over 1e25
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1012 are replaced by \code{\%g} conversions.\footnote{
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1013 These numbers are fairly arbitrary. They are intended to
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1014 avoid printing endless strings of meaningless digits without hampering
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1015 correct use and without having to know the exact precision of floating
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1016 point values on a particular machine.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1017 } All other errors raise exceptions.
15e0c10092bb Massively improved documentation for string formatting operations,
Fred Drake <fdrake@acm.org>
parents: 15926
diff changeset
1018
21163
7b6879714b74 Make no assumption about how modules are built when referring to them; this
Fred Drake <fdrake@acm.org>
parents: 21159
diff changeset
1019 Additional string operations are defined in standard modules
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1020 \refmodule{string}\refstmodindex{string}\ and
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1021 \refmodule{re}.\refstmodindex{re}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1022
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
1023
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
1024 \subsubsection{XRange Type \label{typesseq-xrange}}
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
1025
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1026 The \class{xrange}\obindex{xrange} type is an immutable sequence which
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1027 is commonly used for looping. The advantage of the \class{xrange}
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1028 type is that an \class{xrange} object will always take the same amount
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1029 of memory, no matter the size of the range it represents. There are
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1030 no consistent performance advantages.
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
1031
26592
0c646baeec58 Update comments about the performance of xrange().
Raymond Hettinger <python@rcn.com>
parents: 26514
diff changeset
1032 XRange objects have very little behavior: they only support indexing,
0c646baeec58 Update comments about the performance of xrange().
Raymond Hettinger <python@rcn.com>
parents: 26514
diff changeset
1033 iteration, and the \function{len()} function.
13967
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
1034
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach
Fred Drake <fdrake@acm.org>
parents: 13933
diff changeset
1035
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1036 \subsubsection{Mutable Sequence Types \label{typesseq-mutable}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1037
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1038 List objects support additional operations that allow in-place
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1039 modification of the object.
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1040 Other mutable sequence types (when added to the language) should
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1041 also support these operations.
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1042 Strings and tuples are immutable sequence types: such objects cannot
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1043 be modified once created.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1044 The following operations are defined on mutable sequence types (where
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1045 \var{x} is an arbitrary object):
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1046 \indexiii{mutable}{sequence}{types}
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
1047 \obindex{list}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1048
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1049 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1050 \lineiii{\var{s}[\var{i}] = \var{x}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1051 {item \var{i} of \var{s} is replaced by \var{x}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1052 \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1053 {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1054 \lineiii{del \var{s}[\var{i}:\var{j}]}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1055 {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1056 \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1057 {the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} are replaced by those of \var{t}}{(1)}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1058 \lineiii{del \var{s}[\var{i}:\var{j}:\var{k}]}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1059 {removes the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} from the list}{}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1060 \lineiii{\var{s}.append(\var{x})}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1061 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(2)}
9318
8a26e55e18b8 Document the new list.extend() method. Interesting enough, the
Barry Warsaw <barry@python.org>
parents: 9083
diff changeset
1062 \lineiii{\var{s}.extend(\var{x})}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1063 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(3)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1064 \lineiii{\var{s}.count(\var{x})}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1065 {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
29516
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1066 \lineiii{\var{s}.index(\var{x}\optional{, \var{i}\optional{, \var{j}}})}
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1067 {return smallest \var{k} such that \code{\var{s}[\var{k}] == \var{x}} and
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1068 \code{\var{i} <= \var{k} < \var{j}}}{(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1069 \lineiii{\var{s}.insert(\var{i}, \var{x})}
28606
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be
Guido van Rossum <guido@python.org>
parents: 28337
diff changeset
1070 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{(5)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1071 \lineiii{\var{s}.pop(\optional{\var{i}})}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1072 {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(6)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1073 \lineiii{\var{s}.remove(\var{x})}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1074 {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1075 \lineiii{\var{s}.reverse()}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1076 {reverses the items of \var{s} in place}{(7)}
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1077 \lineiii{\var{s}.sort(\optional{\var{cmp}\optional{,
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1078 \var{key}\optional{, \var{reverse}}}})}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1079 {sort the items of \var{s} in place}{(7), (8), (9), (10)}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1080 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1081 \indexiv{operations on}{mutable}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1082 \indexiii{operations on}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1083 \indexiii{operations on}{list}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1084 \indexii{subscript}{assignment}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1085 \indexii{slice}{assignment}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1086 \indexii{extended slice}{assignment}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1087 \stindex{del}
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1088 \withsubitem{(list method)}{
11183
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
1089 \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()}
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
1090 \ttindex{insert()}\ttindex{pop()}\ttindex{remove()}\ttindex{reverse()}
9523
ed6cacddc6c6 Fix indexing of func_code attribute; this is on a function, not a code
Fred Drake <fdrake@acm.org>
parents: 9461
diff changeset
1091 \ttindex{sort()}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1092 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1093 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1094 \begin{description}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1095 \item[(1)] \var{t} must have the same length as the slice it is
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1096 replacing.
23778
245224d1b8c9 This is my nearly two year old patch
Michael W. Hudson <mwh@python.net>
parents: 23515
diff changeset
1097
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1098 \item[(2)] The C implementation of Python has historically accepted
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1099 multiple parameters and implicitly joined them into a tuple; this
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1100 no longer works in Python 2.0. Use of this misfeature has been
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1101 deprecated since Python 1.4.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
1102
34573
19327db75d1c SF bug #1119700: list extend() accepts args besides lists
Raymond Hettinger <python@rcn.com>
parents: 34508
diff changeset
1103 \item[(3)] \var{x} can be any iterable object.
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1104
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1105 \item[(4)] Raises \exception{ValueError} when \var{x} is not found in
29516
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1106 \var{s}. When a negative index is passed as the second or third parameter
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1107 to the \method{index()} method, the list length is added, as for slice
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1108 indices. If it is still negative, it is truncated to zero, as for
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1109 slice indices. \versionchanged[Previously, \method{index()} didn't
d761ff55b3be Updated documentation for the new slice arguments for list.index().
Walter Dörwald <walter@livinglogic.de>
parents: 29343
diff changeset
1110 have arguments for specifying start and stop positions]{2.3}
11183
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is
Fred Drake <fdrake@acm.org>
parents: 11100
diff changeset
1111
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1112 \item[(5)] When a negative index is passed as the first parameter to
28606
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be
Guido van Rossum <guido@python.org>
parents: 28337
diff changeset
1113 the \method{insert()} method, the list length is added, as for slice
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be
Guido van Rossum <guido@python.org>
parents: 28337
diff changeset
1114 indices. If it is still negative, it is truncated to zero, as for
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be
Guido van Rossum <guido@python.org>
parents: 28337
diff changeset
1115 slice indices. \versionchanged[Previously, all negative indices
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be
Guido van Rossum <guido@python.org>
parents: 28337
diff changeset
1116 were truncated to zero]{2.3}
20701
5f6850d1f9e8 Explain what [].insert() does when the target index is negative.
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
1117
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1118 \item[(6)] The \method{pop()} method is only supported by the list and
13777
b3903e05017f Stop lying about [].pop() being experimental! There is no backing it out
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
1119 array types. The optional argument \var{i} defaults to \code{-1},
b3903e05017f Stop lying about [].pop() being experimental! There is no backing it out
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
1120 so that by default the last item is removed and returned.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
1121
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1122 \item[(7)] The \method{sort()} and \method{reverse()} methods modify the
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
1123 list in place for economy of space when sorting or reversing a large
18829
1bc1fdf1482b trivial rewording in footnote 5.
Skip Montanaro <skip@pobox.com>
parents: 18416
diff changeset
1124 list. To remind you that they operate by side effect, they don't return
1bc1fdf1482b trivial rewording in footnote 5.
Skip Montanaro <skip@pobox.com>
parents: 18416
diff changeset
1125 the sorted or reversed list.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
1126
31210
c06b570adf12 Guido grants a Christmas wish:
Raymond Hettinger <python@rcn.com>
parents: 31206
diff changeset
1127 \item[(8)] The \method{sort()} method takes optional arguments for
33448
5570fae1f01c Typo fix: 'comparisions' is not a word
Andrew M. Kuchling <amk@amk.ca>
parents: 33412
diff changeset
1128 controlling the comparisons.
30697
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1129
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1130 \var{cmp} specifies a custom comparison function of two arguments
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1131 (list items) which should return a negative, zero or positive number
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1132 depending on whether the first argument is considered smaller than,
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1133 equal to, or larger than the second argument:
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1134 \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1135 \function{cmp}(x.lower(), y.lower())}
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1136
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1137 \var{key} specifies a function of one argument that is used to
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1138 extract a comparison key from each list element:
34078
4b601bd346a4 Backport minor documentation fixups.
Raymond Hettinger <python@rcn.com>
parents: 34029
diff changeset
1139 \samp{\var{key}=\function{str.lower}}
30697
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1140
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1141 \var{reverse} is a boolean value. If set to \code{True}, then the
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1142 list elements are sorted as if each comparison were reversed.
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1143
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1144 In general, the \var{key} and \var{reverse} conversion processes are
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1145 much faster than specifying an equivalent \var{cmp} function. This is
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1146 because \var{cmp} is called multiple times for each list element while
30737
38b0b7d41936 markup fixes; this would not format
Fred Drake <fdrake@acm.org>
parents: 30707
diff changeset
1147 \var{key} and \var{reverse} touch each element only once.
30697
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1148
28337
90f17c374f59 - added example of using a comparison function with list.sort(), and
Fred Drake <fdrake@acm.org>
parents: 28211
diff changeset
1149 \versionchanged[Support for \code{None} as an equivalent to omitting
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1150 \var{cmp} was added]{2.3}
28337
90f17c374f59 - added example of using a comparison function with list.sort(), and
Fred Drake <fdrake@acm.org>
parents: 28211
diff changeset
1151
30737
38b0b7d41936 markup fixes; this would not format
Fred Drake <fdrake@acm.org>
parents: 30707
diff changeset
1152 \versionchanged[Support for \var{key} and \var{reverse} was added]{2.4}
28337
90f17c374f59 - added example of using a comparison function with list.sort(), and
Fred Drake <fdrake@acm.org>
parents: 28211
diff changeset
1153
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1154 \item[(9)] Starting with Python 2.3, the \method{sort()} method is
31210
c06b570adf12 Guido grants a Christmas wish:
Raymond Hettinger <python@rcn.com>
parents: 31206
diff changeset
1155 guaranteed to be stable. A sort is stable if it guarantees not to
30697
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1156 change the relative order of elements that compare equal --- this is
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1157 helpful for sorting in multiple passes (for example, sort by
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse.
Raymond Hettinger <python@rcn.com>
parents: 30413
diff changeset
1158 department, then by salary grade).
26161
dd10d97d329a SF patch 637176: list.sort crasher
Tim Peters <tim.peters@gmail.com>
parents: 25906
diff changeset
1159
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1160 \item[(10)] While a list is being sorted, the effect of attempting to
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1161 mutate, or even inspect, the list is undefined. The C
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1162 implementation of Python 2.3 and newer makes the list appear empty
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1163 for the duration, and raises \exception{ValueError} if it can detect
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1164 that the list has been mutated during a sort.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1165 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1166
35074
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
1167 \subsection{Set Types ---
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
1168 \class{set}, \class{frozenset}
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
1169 \label{types-set}}
31008
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1170 \obindex{set}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1171
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1172 A \dfn{set} object is an unordered collection of immutable values.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1173 Common uses include membership testing, removing duplicates from a sequence,
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1174 and computing mathematical operations such as intersection, union, difference,
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1175 and symmetric difference.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1176 \versionadded{2.4}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1177
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1178 Like other collections, sets support \code{\var{x} in \var{set}},
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1179 \code{len(\var{set})}, and \code{for \var{x} in \var{set}}. Being an
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1180 unordered collection, sets do not record element position or order of
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1181 insertion. Accordingly, sets do not support indexing, slicing, or
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1182 other sequence-like behavior.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1183
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1184 There are currently two builtin set types, \class{set} and \class{frozenset}.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1185 The \class{set} type is mutable --- the contents can be changed using methods
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1186 like \method{add()} and \method{remove()}. Since it is mutable, it has no
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1187 hash value and cannot be used as either a dictionary key or as an element of
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1188 another set. The \class{frozenset} type is immutable and hashable --- its
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1189 contents cannot be altered after is created; however, it can be used as
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1190 a dictionary key or as an element of another set.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1191
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1192 Instances of \class{set} and \class{frozenset} provide the following operations:
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1193
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1194 \begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1195 \lineiii{len(\var{s})}{}{cardinality of set \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1196
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1197 \hline
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1198 \lineiii{\var{x} in \var{s}}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1199 {test \var{x} for membership in \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1200 \lineiii{\var{x} not in \var{s}}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1201 {test \var{x} for non-membership in \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1202 \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1203 {test whether every element in \var{s} is in \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1204 \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1205 {test whether every element in \var{t} is in \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1206
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1207 \hline
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1208 \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1209 {new set with elements from both \var{s} and \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1210 \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1211 {new set with elements common to \var{s} and \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1212 \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1213 {new set with elements in \var{s} but not in \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1214 \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1215 {new set with elements in either \var{s} or \var{t} but not both}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1216 \lineiii{\var{s}.copy()}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1217 {new set with a shallow copy of \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1218 \end{tableiii}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1219
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1220 Note, the non-operator versions of \method{union()}, \method{intersection()},
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1221 \method{difference()}, and \method{symmetric_difference()},
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1222 \method{issubset()}, and \method{issuperset()} methods will accept any
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1223 iterable as an argument. In contrast, their operator based counterparts
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1224 require their arguments to be sets. This precludes error-prone constructions
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1225 like \code{set('abc') \&\ 'cbs'} in favor of the more readable
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1226 \code{set('abc').intersection('cbs')}.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1227
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1228 Both \class{set} and \class{frozenset} support set to set comparisons.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1229 Two sets are equal if and only if every element of each set is contained in
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1230 the other (each is a subset of the other).
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1231 A set is less than another set if and only if the first set is a proper
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1232 subset of the second set (is a subset, but is not equal).
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1233 A set is greater than another set if and only if the first set is a proper
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1234 superset of the second set (is a superset, but is not equal).
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1235
34296
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos
Raymond Hettinger <python@rcn.com>
parents: 34078
diff changeset
1236 Instances of \class{set} are compared to instances of \class{frozenset} based
32795
46e0431c9701 SF bug #995983 and #995987: Documentation nits.
Raymond Hettinger <python@rcn.com>
parents: 32459
diff changeset
1237 on their members. For example, \samp{set('abc') == frozenset('abc')} returns
46e0431c9701 SF bug #995983 and #995987: Documentation nits.
Raymond Hettinger <python@rcn.com>
parents: 32459
diff changeset
1238 \code{True}.
46e0431c9701 SF bug #995983 and #995987: Documentation nits.
Raymond Hettinger <python@rcn.com>
parents: 32459
diff changeset
1239
31008
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1240 The subset and equality comparisons do not generalize to a complete
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1241 ordering function. For example, any two disjoint sets are not equal and
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1242 are not subsets of each other, so \emph{all} of the following return
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1243 \code{False}: \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1244 \code{\var{a}>\var{b}}.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1245 Accordingly, sets do not implement the \method{__cmp__} method.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1246
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1247 Since sets only define partial ordering (subset relationships), the output
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1248 of the \method{list.sort()} method is undefined for lists of sets.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1249
34898
fbcb1da480dd SF bug #1179957: Missing def'n of equality for set element
Raymond Hettinger <python@rcn.com>
parents: 34573
diff changeset
1250 Set elements are like dictionary keys; they need to define both
fbcb1da480dd SF bug #1179957: Missing def'n of equality for set element
Raymond Hettinger <python@rcn.com>
parents: 34573
diff changeset
1251 \method{__hash__} and \method{__eq__} methods.
fbcb1da480dd SF bug #1179957: Missing def'n of equality for set element
Raymond Hettinger <python@rcn.com>
parents: 34573
diff changeset
1252
32795
46e0431c9701 SF bug #995983 and #995987: Documentation nits.
Raymond Hettinger <python@rcn.com>
parents: 32459
diff changeset
1253 Binary operations that mix \class{set} instances with \class{frozenset}
46e0431c9701 SF bug #995983 and #995987: Documentation nits.
Raymond Hettinger <python@rcn.com>
parents: 32459
diff changeset
1254 return the type of the first operand. For example:
46e0431c9701 SF bug #995983 and #995987: Documentation nits.
Raymond Hettinger <python@rcn.com>
parents: 32459
diff changeset
1255 \samp{frozenset('ab') | set('bc')} returns an instance of \class{frozenset}.
31008
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1256
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1257 The following table lists operations available for \class{set}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1258 that do not apply to immutable instances of \class{frozenset}:
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1259
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1260 \begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1261 \lineiii{\var{s}.update(\var{t})}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1262 {\var{s} |= \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1263 {return set \var{s} with elements added from \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1264 \lineiii{\var{s}.intersection_update(\var{t})}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1265 {\var{s} \&= \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1266 {return set \var{s} keeping only elements also found in \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1267 \lineiii{\var{s}.difference_update(\var{t})}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1268 {\var{s} -= \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1269 {return set \var{s} after removing elements found in \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1270 \lineiii{\var{s}.symmetric_difference_update(\var{t})}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1271 {\var{s} \textasciicircum= \var{t}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1272 {return set \var{s} with elements from \var{s} or \var{t}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1273 but not both}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1274
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1275 \hline
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1276 \lineiii{\var{s}.add(\var{x})}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1277 {add element \var{x} to set \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1278 \lineiii{\var{s}.remove(\var{x})}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1279 {remove \var{x} from set \var{s}; raises KeyError if not present}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1280 \lineiii{\var{s}.discard(\var{x})}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1281 {removes \var{x} from set \var{s} if present}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1282 \lineiii{\var{s}.pop()}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1283 {remove and return an arbitrary element from \var{s}; raises
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1284 \exception{KeyError} if empty}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1285 \lineiii{\var{s}.clear()}{}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1286 {remove all elements from set \var{s}}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1287 \end{tableiii}
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1288
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1289 Note, the non-operator versions of the \method{update()},
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1290 \method{intersection_update()}, \method{difference_update()}, and
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1291 \method{symmetric_difference_update()} methods will accept any iterable
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1292 as an argument.
4224d807911c * Checkin remaining documentation
Raymond Hettinger <python@rcn.com>
parents: 30813
diff changeset
1293
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1294
35074
f89cbe69db63 SF bug #1215887: String and list methods documentation deeply hidden
Raymond Hettinger <python@rcn.com>
parents: 34975
diff changeset
1295 \subsection{Mapping Types --- class{dict} \label{typesmapping}}
15005
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
1296 \obindex{mapping}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is
Fred Drake <fdrake@acm.org>
parents: 14710
diff changeset
1297 \obindex{dictionary}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1298
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1299 A \dfn{mapping} object maps immutable values to
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1300 arbitrary objects. Mappings are mutable objects. There is currently
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1301 only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1302 almost arbitrary values. Only values containing lists, dictionaries
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1303 or other mutable types (that are compared by value rather than by
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1304 object identity) may not be used as keys.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1305 Numeric types used for keys obey the normal rules for numeric
30413
53f1c32ee69d SF bug #804280: fromkeys is not listed in index
Raymond Hettinger <python@rcn.com>
parents: 30375
diff changeset
1306 comparison: if two numbers compare equal (such as \code{1} and
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1307 \code{1.0}) then they can be used interchangeably to index the same
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1308 dictionary entry.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1309
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1310 Dictionaries are created by placing a comma-separated list of
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1311 \code{\var{key}: \var{value}} pairs within braces, for example:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1312 \code{\{'jack': 4098, 'sjoerd': 4127\}} or
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1313 \code{\{4098: 'jack', 4127: 'sjoerd'\}}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1314
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1315 The following operations are defined on mappings (where \var{a} and
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1316 \var{b} are mappings, \var{k} is a key, and \var{v} and \var{x} are
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1317 arbitrary objects):
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1318 \indexiii{operations on}{mapping}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1319 \indexiii{operations on}{dictionary}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1320 \stindex{del}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1321 \bifuncindex{len}
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1322 \withsubitem{(dictionary method)}{
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1323 \ttindex{clear()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1324 \ttindex{copy()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1325 \ttindex{has_key()}
30413
53f1c32ee69d SF bug #804280: fromkeys is not listed in index
Raymond Hettinger <python@rcn.com>
parents: 30375
diff changeset
1326 \ttindex{fromkeys()}
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1327 \ttindex{items()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1328 \ttindex{keys()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1329 \ttindex{update()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1330 \ttindex{values()}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1331 \ttindex{get()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1332 \ttindex{setdefault()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1333 \ttindex{pop()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1334 \ttindex{popitem()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1335 \ttindex{iteritems()}
29067
04065c4a1c6b Missing parenthesis found by texcheck.py
Raymond Hettinger <python@rcn.com>
parents: 29065
diff changeset
1336 \ttindex{iterkeys()}
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1337 \ttindex{itervalues()}}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1338
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1339 \begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1340 \lineiii{len(\var{a})}{the number of items in \var{a}}{}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1341 \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)}
13764
fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
1342 \lineiii{\var{a}[\var{k}] = \var{v}}
fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about
Fred Drake <fdrake@acm.org>
parents: 13222
diff changeset
1343 {set \code{\var{a}[\var{k}]} to \var{v}}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1344 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1345 \lineiii{del \var{a}[\var{k}]}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1346 {remove \code{\var{a}[\var{k}]} from \var{a}}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1347 {(1)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1348 \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1349 \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
17616
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1350 \lineiii{\var{a}.has_key(\var{k})}
30095
e3c9b48de60a SF bug #775836: change 0,1 to False,True in dict.has_key doc
Raymond Hettinger <python@rcn.com>
parents: 29893
diff changeset
1351 {\code{True} if \var{a} has a key \var{k}, else \code{False}}
17594
bf94af396b1e Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents: 16778
diff changeset
1352 {}
17616
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1353 \lineiii{\var{k} \code{in} \var{a}}
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1354 {Equivalent to \var{a}.has_key(\var{k})}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1355 {(2)}
17594
bf94af396b1e Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents: 16778
diff changeset
1356 \lineiii{\var{k} not in \var{a}}
17616
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not
Guido van Rossum <guido@python.org>
parents: 17612
diff changeset
1357 {Equivalent to \code{not} \var{a}.has_key(\var{k})}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1358 {(2)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1359 \lineiii{\var{a}.items()}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1360 {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1361 {(3)}
18085
7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these
Fred Drake <fdrake@acm.org>
parents: 17966
diff changeset
1362 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)}
31616
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1363 \lineiii{\var{a}.update(\optional{\var{b}})}
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1364 {updates (and overwrites) key/value pairs from \var{b}}
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1365 {(9)}
26437
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class
Raymond Hettinger <python@rcn.com>
parents: 26260
diff changeset
1366 \lineiii{\var{a}.fromkeys(\var{seq}\optional{, \var{value}})}
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class
Raymond Hettinger <python@rcn.com>
parents: 26260
diff changeset
1367 {Creates a new dictionary with keys from \var{seq} and values set to \var{value}}
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class
Raymond Hettinger <python@rcn.com>
parents: 26260
diff changeset
1368 {(7)}
18085
7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these
Fred Drake <fdrake@acm.org>
parents: 17966
diff changeset
1369 \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(3)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1370 \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
17603
d638e419c304 Fix a number of minor markup errors.
Fred Drake <fdrake@acm.org>
parents: 17594
diff changeset
1371 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1372 else \var{x}}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1373 {(4)}
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1374 \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
17603
d638e419c304 Fix a number of minor markup errors.
Fred Drake <fdrake@acm.org>
parents: 17594
diff changeset
1375 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1376 else \var{x} (also setting it)}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1377 {(5)}
28211
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1378 \lineiii{\var{a}.pop(\var{k}\optional{, \var{x}})}
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1379 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1380 else \var{x} (and remove k)}
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1381 {(8)}
15522
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1382 \lineiii{\var{a}.popitem()}
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1383 {remove and return an arbitrary (\var{key}, \var{value}) pair}
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1384 {(6)}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1385 \lineiii{\var{a}.iteritems()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1386 {return an iterator over (\var{key}, \var{value}) pairs}
24902
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1387 {(2), (3)}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1388 \lineiii{\var{a}.iterkeys()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1389 {return an iterator over the mapping's keys}
24902
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1390 {(2), (3)}
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1391 \lineiii{\var{a}.itervalues()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1392 {return an iterator over the mapping's values}
24902
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1393 {(2), (3)}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1394 \end{tableiii}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1395
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1396 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1397 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1398 \begin{description}
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1399 \item[(1)] Raises a \exception{KeyError} exception if \var{k} is not
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1400 in the map.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1401
17966
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1402 \item[(2)] \versionadded{2.2}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues()
Fred Drake <fdrake@acm.org>
parents: 17663
diff changeset
1403
34029
81a1f754d32c Clarify the ordering of dictionary keys.
Raymond Hettinger <python@rcn.com>
parents: 33970
diff changeset
1404 \item[(3)] Keys and values are listed in an arbitrary order which is
81a1f754d32c Clarify the ordering of dictionary keys.
Raymond Hettinger <python@rcn.com>
parents: 33970
diff changeset
1405 non-random, varies across Python implementations, and depends on the
81a1f754d32c Clarify the ordering of dictionary keys.
Raymond Hettinger <python@rcn.com>
parents: 33970
diff changeset
1406 dictionary's history of insertions and deletions.
81a1f754d32c Clarify the ordering of dictionary keys.
Raymond Hettinger <python@rcn.com>
parents: 33970
diff changeset
1407 If \method{items()}, \method{keys()}, \method{values()},
24902
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1408 \method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1409 are called with no intervening modifications to the dictionary, the
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1410 lists will directly correspond. This allows the creation of
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1411 \code{(\var{value}, \var{key})} pairs using \function{zip()}:
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1412 \samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1413 relationship holds for the \method{iterkeys()} and
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1414 \method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1415 \var{a}.iterkeys())} provides the same value for \code{pairs}.
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1416 Another way to create the same list is \samp{pairs = [(v, k) for (k,
f57d6db423f2 Extend some comments on the order of values in the returns from
Fred Drake <fdrake@acm.org>
parents: 24631
diff changeset
1417 v) in \var{a}.iteritems()]}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1418
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1419 \item[(4)] Never raises an exception if \var{k} is not in the map,
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
1420 instead it returns \var{x}. \var{x} is optional; when \var{x} is not
10968
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments
Fred Drake <fdrake@acm.org>
parents: 10785
diff changeset
1421 provided and \var{k} is not in the map, \code{None} is returned.
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1422
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1423 \item[(5)] \function{setdefault()} is like \function{get()}, except
13894
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly
Guido van Rossum <guido@python.org>
parents: 13780
diff changeset
1424 that if \var{k} is missing, \var{x} is both returned and inserted into
33003
b5dcfe7a4159 Point out that the setdefault defaults the value to None. Inspired by
Michael W. Hudson <mwh@python.net>
parents: 32975
diff changeset
1425 the dictionary as the value of \var{k}. \var{x} defaults to \var{None}.
15522
aaa54752e4ba "Documentation" for {}.popitem().
Guido van Rossum <guido@python.org>
parents: 15463
diff changeset
1426
18286
bc05a95242a3 Remove the restriction on a mapping's .update() method.
Barry Warsaw <barry@python.org>
parents: 18085
diff changeset
1427 \item[(6)] \function{popitem()} is useful to destructively iterate
34969
672e5f65172c SF bug #1209671: dict.popitem documentation should mention empty dict case
Raymond Hettinger <python@rcn.com>
parents: 34917
diff changeset
1428 over a dictionary, as often used in set algorithms. If the dictionary
672e5f65172c SF bug #1209671: dict.popitem documentation should mention empty dict case
Raymond Hettinger <python@rcn.com>
parents: 34917
diff changeset
1429 is empty, calling \function{popitem()} raises a \exception{KeyError}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1430
26437
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class
Raymond Hettinger <python@rcn.com>
parents: 26260
diff changeset
1431 \item[(7)] \function{fromkeys()} is a class method that returns a
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class
Raymond Hettinger <python@rcn.com>
parents: 26260
diff changeset
1432 new dictionary. \var{value} defaults to \code{None}. \versionadded{2.3}
28211
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1433
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1434 \item[(8)] \function{pop()} raises a \exception{KeyError} when no default
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop
Raymond Hettinger <python@rcn.com>
parents: 28171
diff changeset
1435 value is given and the key is not found. \versionadded{2.3}
26437
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class
Raymond Hettinger <python@rcn.com>
parents: 26260
diff changeset
1436
31616
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1437 \item[(9)] \function{update()} accepts either another mapping object
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1438 or an iterable of key/value pairs (as a tuple or other iterable of
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1439 length two). If keyword arguments are specified, the mapping is
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1440 then is updated with those key/value pairs:
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1441 \samp{d.update(red=1, blue=2)}.
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1442 \versionchanged[Allowed the argument to be an iterable of key/value
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_
Raymond Hettinger <python@rcn.com>
parents: 31357
diff changeset
1443 pairs and allowed keyword arguments]{2.4}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1444
31631
228d264c5fbb SF Patch #912462: Relocate \end tag to the right place.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31616
diff changeset
1445 \end{description}
228d264c5fbb SF Patch #912462: Relocate \end tag to the right place.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 31616
diff changeset
1446
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1447 \subsection{File Objects
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1448 \label{bltin-file-objects}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1449
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1450 File objects\obindex{file} are implemented using C's \code{stdio}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1451 package and can be created with the built-in constructor
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1452 \function{file()}\bifuncindex{file} described in section
20764
37b8d92e12f5 Mention the new file() builtin in the section on file objects.
Tim Peters <tim.peters@gmail.com>
parents: 20701
diff changeset
1453 \ref{built-in-funcs}, ``Built-in Functions.''\footnote{\function{file()}
37b8d92e12f5 Mention the new file() builtin in the section on file objects.
Tim Peters <tim.peters@gmail.com>
parents: 20701
diff changeset
1454 is new in Python 2.2. The older built-in \function{open()} is an
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1455 alias for \function{file()}.} File objects are also returned
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1456 by some other built-in functions and methods, such as
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1457 \function{os.popen()} and \function{os.fdopen()} and the
9461
9ffd604807c2 Don't describe something as "below"; that won't make sense for the
Fred Drake <fdrake@acm.org>
parents: 9318
diff changeset
1458 \method{makefile()} method of socket objects.
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1459 \refstmodindex{os}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1460 \refbimodindex{socket}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1461
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1462 When a file operation fails for an I/O-related reason, the exception
9558
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
1463 \exception{IOError} is raised. This includes situations where the
fa867d8ee7eb Remove some remaining {\rm ...} constructs.
Fred Drake <fdrake@acm.org>
parents: 9523
diff changeset
1464 operation is not defined for some reason, like \method{seek()} on a tty
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1465 device or writing a file opened for reading.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1466
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1467 Files have the following methods:
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1468
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1469
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1470 \begin{methoddesc}[file]{close}{}
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1471 Close the file. A closed file cannot be read or written any more.
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1472 Any operation which requires that the file be open will raise a
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1473 \exception{ValueError} after the file has been closed. Calling
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1474 \method{close()} more than once is allowed.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1475 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1476
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1477 \begin{methoddesc}[file]{flush}{}
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1478 Flush the internal buffer, like \code{stdio}'s
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1479 \cfunction{fflush()}. This may be a no-op on some file-like
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1480 objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1481 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1482
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1483 \begin{methoddesc}[file]{fileno}{}
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1484 \index{file descriptor}
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1485 \index{descriptor, file}
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1486 Return the integer ``file descriptor'' that is used by the
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1487 underlying implementation to request I/O operations from the
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1488 operating system. This can be useful for other, lower level
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1489 interfaces that use file descriptors, such as the
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1490 \refmodule{fcntl}\refbimodindex{fcntl} module or
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1491 \function{os.read()} and friends. \note{File-like objects
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1492 which do not have a real file descriptor should \emph{not} provide
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1493 this method!}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1494 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1495
24599
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1496 \begin{methoddesc}[file]{isatty}{}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1497 Return \code{True} if the file is connected to a tty(-like) device, else
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1498 \code{False}. \note{If a file-like object is not associated
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1499 with a real file, this method should \emph{not} be implemented.}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1500 \end{methoddesc}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1501
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1502 \begin{methoddesc}[file]{next}{}
30413
53f1c32ee69d SF bug #804280: fromkeys is not listed in index
Raymond Hettinger <python@rcn.com>
parents: 30375
diff changeset
1503 A file object is its own iterator, for example \code{iter(\var{f})} returns
24599
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1504 \var{f} (unless \var{f} is closed). When a file is used as an
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1505 iterator, typically in a \keyword{for} loop (for example,
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1506 \code{for line in f: print line}), the \method{next()} method is
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1507 called repeatedly. This method returns the next input line, or raises
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1508 \exception{StopIteration} when \EOF{} is hit. In order to make a
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1509 \keyword{for} loop the most efficient way of looping over the lines of
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1510 a file (a very common operation), the \method{next()} method uses a
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1511 hidden read-ahead buffer. As a consequence of using a read-ahead
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1512 buffer, combining \method{next()} with other file methods (like
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1513 \method{readline()}) does not work right. However, using
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1514 \method{seek()} to reposition the file to an absolute position will
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1515 flush the read-ahead buffer.
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1516 \versionadded{2.3}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1517 \end{methoddesc}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1518
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1519 \begin{methoddesc}[file]{read}{\optional{size}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1520 Read at most \var{size} bytes from the file (less if the read hits
10606
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1521 \EOF{} before obtaining \var{size} bytes). If the \var{size}
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1522 argument is negative or omitted, read all data until \EOF{} is
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1523 reached. The bytes are returned as a string object. An empty
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1524 string is returned when \EOF{} is encountered immediately. (For
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1525 certain files, like ttys, it makes sense to continue reading after
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1526 an \EOF{} is hit.) Note that this method may call the underlying
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious
Fred Drake <fdrake@acm.org>
parents: 10520
diff changeset
1527 C function \cfunction{fread()} more than once in an effort to
26672
8dd25a6f5913 Fixed bug
Gustavo Niemeyer <gustavo@niemeyer.net>
parents: 26592
diff changeset
1528 acquire as close to \var{size} bytes as possible. Also note that
8dd25a6f5913 Fixed bug
Gustavo Niemeyer <gustavo@niemeyer.net>
parents: 26592
diff changeset
1529 when in non-blocking mode, less data than what was requested may
8dd25a6f5913 Fixed bug
Gustavo Niemeyer <gustavo@niemeyer.net>
parents: 26592
diff changeset
1530 be returned, even if no \var{size} parameter was given.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1531 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1532
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1533 \begin{methoddesc}[file]{readline}{\optional{size}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1534 Read one entire line from the file. A trailing newline character is
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1535 kept in the string (but may be absent when a file ends with an
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1536 incomplete line).\footnote{
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1537 The advantage of leaving the newline on is that
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1538 returning an empty string is then an unambiguous \EOF{}
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1539 indication. It is also possible (in cases where it might
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1540 matter, for example, if you
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1541 want to make an exact copy of a file while scanning its lines)
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1542 to tell whether the last line of a file ended in a newline
13933
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some
Fred Drake <fdrake@acm.org>
parents: 13894
diff changeset
1543 or not (yes this happens!).
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1544 } If the \var{size} argument is present and
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1545 non-negative, it is a maximum byte count (including the trailing
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1546 newline) and an incomplete line may be returned.
23860
63ee31bb25f3 Make a start at describing the results of class/type unification
Steve Holden <steve@holdenweb.com>
parents: 23847
diff changeset
1547 An empty string is returned \emph{only} when \EOF{} is encountered
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1548 immediately. \note{Unlike \code{stdio}'s \cfunction{fgets()}, the
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1549 returned string contains null characters (\code{'\e 0'}) if they
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1550 occurred in the input.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1551 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1552
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1553 \begin{methoddesc}[file]{readlines}{\optional{sizehint}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1554 Read until \EOF{} using \method{readline()} and return a list containing
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1555 the lines thus read. If the optional \var{sizehint} argument is
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20767
diff changeset
1556 present, instead of reading up to \EOF, whole lines totalling
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1557 approximately \var{sizehint} bytes (possibly after rounding up to an
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1558 internal buffer size) are read. Objects implementing a file-like
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1559 interface may choose to ignore \var{sizehint} if it cannot be
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1560 implemented, or cannot be implemented efficiently.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1561 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1562
15926
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!)
Guido van Rossum <guido@python.org>
parents: 15896
diff changeset
1563 \begin{methoddesc}[file]{xreadlines}{}
24599
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and
Guido van Rossum <guido@python.org>
parents: 24598
diff changeset
1564 This method returns the same thing as \code{iter(f)}.
17612
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation.
Fred Drake <fdrake@acm.org>
parents: 17603
diff changeset
1565 \versionadded{2.1}
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1566 \deprecated{2.3}{Use \samp{for \var{line} in \var{file}} instead.}
15926
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!)
Guido van Rossum <guido@python.org>
parents: 15896
diff changeset
1567 \end{methoddesc}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!)
Guido van Rossum <guido@python.org>
parents: 15896
diff changeset
1568
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1569 \begin{methoddesc}[file]{seek}{offset\optional{, whence}}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1570 Set the file's current position, like \code{stdio}'s \cfunction{fseek()}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1571 The \var{whence} argument is optional and defaults to \code{0}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1572 (absolute file positioning); other values are \code{1} (seek
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1573 relative to the current position) and \code{2} (seek relative to the
15731
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1574 file's end). There is no return value. Note that if the file is
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1575 opened for appending (mode \code{'a'} or \code{'a+'}), any
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1576 \method{seek()} operations will be undone at the next write. If the
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1577 file is only opened for writing in append mode (mode \code{'a'}),
a06415994cb5 Added information about the interaction of opening a file in append mode
Fred Drake <fdrake@acm.org>
parents: 15522
diff changeset
1578 this method is essentially a no-op, but it remains useful for files
30705
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30697
diff changeset
1579 opened in append mode with reading enabled (mode \code{'a+'}). If the
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30697
diff changeset
1580 file is opened in text mode (mode \code{'t'}), only offsets returned
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30697
diff changeset
1581 by \method{tell()} are legal. Use of other offsets causes undefined
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30697
diff changeset
1582 behavior.
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30697
diff changeset
1583
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30697
diff changeset
1584 Note that not all file objects are seekable.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1585 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1586
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1587 \begin{methoddesc}[file]{tell}{}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1588 Return the file's current position, like \code{stdio}'s
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1589 \cfunction{ftell()}.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1590 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1591
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1592 \begin{methoddesc}[file]{truncate}{\optional{size}}
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1593 Truncate the file's size. If the optional \var{size} argument is
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1594 present, the file is truncated to (at most) that size. The size
22241
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1595 defaults to the current position. The current file position is
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1596 not changed. Note that if a specified size exceeds the file's
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1597 current size, the result is platform-dependent: possibilities
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1598 include that file may remain unchanged, increase to the specified
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1599 size as if zero-filled, or increase to the specified size with
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position,
Tim Peters <tim.peters@gmail.com>
parents: 22214
diff changeset
1600 undefined new content.
30375
4aa84a8b1fe4 Fix spacing markup and other sundries.
Raymond Hettinger <python@rcn.com>
parents: 30250
diff changeset
1601 Availability: Windows, many \UNIX{} variants.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1602 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1603
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1604 \begin{methoddesc}[file]{write}{str}
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1605 Write a string to the file. There is no return value. Due to
15789
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1606 buffering, the string may not actually show up in the file until
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1607 the \method{flush()} or \method{close()} method is called.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1608 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1609
20045
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1610 \begin{methoddesc}[file]{writelines}{sequence}
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1611 Write a sequence of strings to the file. The sequence can be any
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1612 iterable object producing strings, typically a list of strings.
7b8c11739714 Generalize file.writelines() to allow iterable objects.
Tim Peters <tim.peters@gmail.com>
parents: 20031
diff changeset
1613 There is no return value.
15789
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1614 (The name is intended to match \method{readlines()};
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1615 \method{writelines()} does not add line separators.)
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1616 \end{methoddesc}
9e9556924b0a Added documentation for the xreadlines module & related changes. The
Fred Drake <fdrake@acm.org>
parents: 15731
diff changeset
1617
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1618
20031
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1619 Files support the iterator protocol. Each iteration returns the same
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1620 result as \code{\var{file}.readline()}, and iteration ends when the
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1621 \method{readline()} method returns an empty string.
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1622
e5a3f9d7766b Note that files are iterable; describe what the iterator returns.
Fred Drake <fdrake@acm.org>
parents: 19529
diff changeset
1623
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1624 File objects also offer a number of other interesting attributes.
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1625 These are not required for file-like objects, but should be
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1626 implemented if they make sense for the particular object.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1627
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1628 \begin{memberdesc}[file]{closed}
22920
2392af05f052 Update docs for bool changes by Guido around April 6
Neal Norwitz <nnorwitz@gmail.com>
parents: 22785
diff changeset
1629 bool indicating the current state of the file object. This is a
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1630 read-only attribute; the \method{close()} method changes the value.
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1631 It may not be available on all file-like objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1632 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1633
29065
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1634 \begin{memberdesc}[file]{encoding}
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1635 The encoding that this file uses. When Unicode strings are written
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1636 to a file, they will be converted to byte strings using this encoding.
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1637 In addition, when the file is connected to a terminal, the attribute
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1638 gives the encoding that the terminal is likely to use (that
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1639 information might be incorrect if the user has misconfigured the
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1640 terminal). The attribute is read-only and may not be present on
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1641 all file-like objects. It may also be \code{None}, in which case
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1642 the file uses the system default encoding for converting Unicode
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1643 strings.
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1644
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1645 \versionadded{2.3}
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1646 \end{memberdesc}
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine
Martin v. Löwis <martin@v.loewis.de>
parents: 28909
diff changeset
1647
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1648 \begin{memberdesc}[file]{mode}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1649 The I/O mode for the file. If the file was created using the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1650 \function{open()} built-in function, this will be the value of the
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1651 \var{mode} parameter. This is a read-only attribute and may not be
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1652 present on all file-like objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1653 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1654
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1655 \begin{memberdesc}[file]{name}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1656 If the file object was created using \function{open()}, the name of
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1657 the file. Otherwise, some string that indicates the source of the
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1658 file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
14685
faf3e734254d Clarify a number of issues about the file-like object API based on
Fred Drake <fdrake@acm.org>
parents: 14557
diff changeset
1659 attribute and may not be present on all file-like objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1660 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1661
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1662 \begin{memberdesc}[file]{newlines}
31282
8b62f4194a7e markup fix
Fred Drake <fdrake@acm.org>
parents: 31210
diff changeset
1663 If Python was built with the \longprogramopt{with-universal-newlines}
8b62f4194a7e markup fix
Fred Drake <fdrake@acm.org>
parents: 31210
diff changeset
1664 option to \program{configure} (the default) this read-only attribute
8b62f4194a7e markup fix
Fred Drake <fdrake@acm.org>
parents: 31210
diff changeset
1665 exists, and for files opened in
28171
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1666 universal newline read mode it keeps track of the types of newlines
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1667 encountered while reading the file. The values it can take are
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1668 \code{'\e r'}, \code{'\e n'}, \code{'\e r\e n'}, \code{None} (unknown,
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1669 no newlines read yet) or a tuple containing all the newline
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1670 types seen, to indicate that multiple
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1671 newline conventions were encountered. For files not opened in universal
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1672 newline read mode the value of this attribute will be \code{None}.
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1673 \end{memberdesc}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped
Michael W. Hudson <mwh@python.net>
parents: 27919
diff changeset
1674
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1675 \begin{memberdesc}[file]{softspace}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1676 Boolean that indicates whether a space character needs to be printed
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1677 before another value when using the \keyword{print} statement.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1678 Classes that are trying to simulate a file object should also have a
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1679 writable \member{softspace} attribute, which should be initialized to
14485
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1680 zero. This will be automatic for most classes implemented in Python
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1681 (care may be needed for objects that override attribute access); types
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1682 implemented in C will have to provide a writable
ac0246586d52 Improve a couple of references to the language reference, making them
Fred Drake <fdrake@acm.org>
parents: 14044
diff changeset
1683 \member{softspace} attribute.
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1684 \note{This attribute is not used to control the
14705
4712f5b8f279 Clarify that the softspace attribute is used by print for state management,
Fred Drake <fdrake@acm.org>
parents: 14685
diff changeset
1685 \keyword{print} statement, but to allow the implementation of
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20173
diff changeset
1686 \keyword{print} to keep track of its internal state.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1687 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1688
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1689
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1690 \subsection{Other Built-in Types \label{typesother}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1691
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1692 The interpreter supports several other kinds of objects.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1693 Most of these support only one or two operations.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1694
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1695
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1696 \subsubsection{Modules \label{typesmodules}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1697
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1698 The only special operation on a module is attribute access:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1699 \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1700 accesses a name defined in \var{m}'s symbol table. Module attributes
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1701 can be assigned to. (Note that the \keyword{import} statement is not,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1702 strictly speaking, an operation on a module object; \code{import
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1703 \var{foo}} does not require a module object named \var{foo} to exist,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1704 rather it requires an (external) \emph{definition} for a module named
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1705 \var{foo} somewhere.)
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1706
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1707 A special member of every module is \member{__dict__}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1708 This is the dictionary containing the module's symbol table.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1709 Modifying this dictionary will actually change the module's symbol
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1710 table, but direct assignment to the \member{__dict__} attribute is not
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1711 possible (you can write \code{\var{m}.__dict__['a'] = 1}, which
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1712 defines \code{\var{m}.a} to be \code{1}, but you can't write
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1713 \code{\var{m}.__dict__ = \{\}}). Modifying \member{__dict__} directly
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1714 is not recommended.
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1715
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1716 Modules built into the interpreter are written like this:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1717 \code{<module 'sys' (built-in)>}. If loaded from a file, they are
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1718 written as \code{<module 'os' from
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1719 '/usr/local/lib/python\shortversion/os.pyc'>}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1720
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1721
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1722 \subsubsection{Classes and Class Instances \label{typesobjects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1723 \nodename{Classes and Instances}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1724
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1725 See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1726 Reference Manual} for these.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1727
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1728
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1729 \subsubsection{Functions \label{typesfunctions}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1730
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1731 Function objects are created by function definitions. The only
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1732 operation on a function object is to call it:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1733 \code{\var{func}(\var{argument-list})}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1734
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1735 There are really two flavors of function objects: built-in functions
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1736 and user-defined functions. Both support the same operation (to call
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1737 the function), but the implementation is different, hence the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1738 different object types.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1739
33102
f27935b46985 This is my patch
Michael W. Hudson <mwh@python.net>
parents: 33003
diff changeset
1740 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
f27935b46985 This is my patch
Michael W. Hudson <mwh@python.net>
parents: 33003
diff changeset
1741 information.
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1742
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1743 \subsubsection{Methods \label{typesmethods}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1744 \obindex{method}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1745
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1746 Methods are functions that are called using the attribute notation.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1747 There are two flavors: built-in methods (such as \method{append()} on
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1748 lists) and class instance methods. Built-in methods are described
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1749 with the types that support them.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1750
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1751 The implementation adds two special read-only attributes to class
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1752 instance methods: \code{\var{m}.im_self} is the object on which the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1753 method operates, and \code{\var{m}.im_func} is the function
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1754 implementing the method. Calling \code{\var{m}(\var{arg-1},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1755 \var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1756 calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1757 \var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1758
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1759 Class instance methods are either \emph{bound} or \emph{unbound},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1760 referring to whether the method was accessed through an instance or a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1761 class, respectively. When a method is unbound, its \code{im_self}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1762 attribute will be \code{None} and if called, an explicit \code{self}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1763 object must be passed as the first argument. In this case,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1764 \code{self} must be an instance of the unbound method's class (or a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1765 subclass of that class), otherwise a \code{TypeError} is raised.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1766
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1767 Like function objects, methods objects support getting
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1768 arbitrary attributes. However, since method attributes are actually
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1769 stored on the underlying function object (\code{meth.im_func}),
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1770 setting method attributes on either bound or unbound methods is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1771 disallowed. Attempting to set a method attribute results in a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1772 \code{TypeError} being raised. In order to set a method attribute,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1773 you need to explicitly set it on the underlying function object:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1774
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1775 \begin{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1776 class C:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1777 def method(self):
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1778 pass
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1779
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1780 c = C()
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1781 c.method.im_func.whoami = 'my name is c'
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1782 \end{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1783
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1784 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1785 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1786
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1787
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1788 \subsubsection{Code Objects \label{bltin-code-objects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1789 \obindex{code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1790
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1791 Code objects are used by the implementation to represent
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1792 ``pseudo-compiled'' executable Python code such as a function body.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1793 They differ from function objects because they don't contain a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1794 reference to their global execution environment. Code objects are
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1795 returned by the built-in \function{compile()} function and can be
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1796 extracted from function objects through their \member{func_code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1797 attribute.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1798 \bifuncindex{compile}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1799 \withsubitem{(function object attribute)}{\ttindex{func_code}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1800
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1801 A code object can be executed or evaluated by passing it (instead of a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1802 source string) to the \keyword{exec} statement or the built-in
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1803 \function{eval()} function.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1804 \stindex{exec}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1805 \bifuncindex{eval}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1806
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1807 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1808 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1809
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1810
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1811 \subsubsection{Type Objects \label{bltin-type-objects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1812
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1813 Type objects represent the various object types. An object's type is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1814 accessed by the built-in function \function{type()}. There are no special
31286
3894654b4848 fix a variety of markup bugs
Fred Drake <fdrake@acm.org>
parents: 31282
diff changeset
1815 operations on types. The standard module \refmodule{types} defines names
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1816 for all standard built-in types.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1817 \bifuncindex{type}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1818 \refstmodindex{types}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1819
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1820 Types are written like this: \code{<type 'int'>}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1821
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1822
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1823 \subsubsection{The Null Object \label{bltin-null-object}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1824
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1825 This object is returned by functions that don't explicitly return a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1826 value. It supports no special operations. There is exactly one null
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1827 object, named \code{None} (a built-in name).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1828
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1829 It is written as \code{None}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1830
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1831
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1832 \subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1833
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1834 This object is used by extended slice notation (see the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1835 \citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1836 special operations. There is exactly one ellipsis object, named
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1837 \constant{Ellipsis} (a built-in name).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1838
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1839 It is written as \code{Ellipsis}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1840
22785
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1841 \subsubsection{Boolean Values}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1842
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1843 Boolean values are the two constant objects \code{False} and
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1844 \code{True}. They are used to represent truth values (although other
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1845 values can also be considered false or true). In numeric contexts
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1846 (for example when used as the argument to an arithmetic operator),
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1847 they behave like the integers 0 and 1, respectively. The built-in
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1848 function \function{bool()} can be used to cast any value to a Boolean,
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1849 if the value can be interpreted as a truth value (see section Truth
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1850 Value Testing above).
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1851
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1852 They are written as \code{False} and \code{True}, respectively.
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1853 \index{False}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1854 \index{True}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1855 \indexii{Boolean}{values}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in
Guido van Rossum <guido@python.org>
parents: 22241
diff changeset
1856
20767
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become
Fred Drake <fdrake@acm.org>
parents: 20764
diff changeset
1857
10156
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable
Fred Drake <fdrake@acm.org>
parents: 10147
diff changeset
1858 \subsubsection{Internal Objects \label{typesinternal}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1859
11463
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11183
diff changeset
1860 See the \citetitle[../ref/ref.html]{Python Reference Manual} for this
14044
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
1861 information. It describes stack frame objects, traceback objects, and
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange()
Fred Drake <fdrake@acm.org>
parents: 13967
diff changeset
1862 slice objects.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1863
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1864
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
1865 \subsection{Special Attributes \label{specialattrs}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1866
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1867 The implementation adds a few special read-only attributes to several
32070
b319db3869d8 add note about the __name__ read-only attribute
Fred Drake <fdrake@acm.org>
parents: 31631
diff changeset
1868 object types, where they are relevant. Some of these are not reported
b319db3869d8 add note about the __name__ read-only attribute
Fred Drake <fdrake@acm.org>
parents: 31631
diff changeset
1869 by the \function{dir()} built-in function.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1870
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1871 \begin{memberdesc}[object]{__dict__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1872 A dictionary or other mapping object used to store an
9083
bc41e86c938c Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9034
diff changeset
1873 object's (writable) attributes.
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1874 \end{memberdesc}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1875
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1876 \begin{memberdesc}[object]{__methods__}
21159
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1877 \deprecated{2.2}{Use the built-in function \function{dir()} to get a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1878 list of an object's attributes. This attribute is no longer available.}
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1879 \end{memberdesc}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1880
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1881 \begin{memberdesc}[object]{__members__}
21159
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1882 \deprecated{2.2}{Use the built-in function \function{dir()} to get a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents: 21062
diff changeset
1883 list of an object's attributes. This attribute is no longer available.}
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1884 \end{memberdesc}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1885
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1886 \begin{memberdesc}[instance]{__class__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1887 The class to which a class instance belongs.
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1888 \end{memberdesc}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1889
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1890 \begin{memberdesc}[class]{__bases__}
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1891 The tuple of base classes of a class object. If there are no base
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18395
diff changeset
1892 classes, this will be an empty tuple.
15383
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed
Fred Drake <fdrake@acm.org>
parents: 15332
diff changeset
1893 \end{memberdesc}
32070
b319db3869d8 add note about the __name__ read-only attribute
Fred Drake <fdrake@acm.org>
parents: 31631
diff changeset
1894
b319db3869d8 add note about the __name__ read-only attribute
Fred Drake <fdrake@acm.org>
parents: 31631
diff changeset
1895 \begin{memberdesc}[class]{__name__}
b319db3869d8 add note about the __name__ read-only attribute
Fred Drake <fdrake@acm.org>
parents: 31631
diff changeset
1896 The name of the class or type.
b319db3869d8 add note about the __name__ read-only attribute
Fred Drake <fdrake@acm.org>
parents: 31631
diff changeset
1897 \end{memberdesc}