cpython-lru_cache-weakref: Doc/lib/libstdtypes.tex annotate

annotate Doc/lib/libstdtypes.tex @ 27022:e2c88c451c19 legacy-trunk

Replaced imp.set_frozenmodules() cruft with proper zipimport support. This work uncovered the zipimport bug in 2.3a1 -- wish I'd had time to do this before the release :-(.

author	Just van Rossum <just@letterror.com>
date	Thu, 02 Jan 2003 13:13:01 +0000
parents	6932794817c2
children	41f7726e3e51

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,
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	16 all objects can be compared, tested for truth value, and converted to
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	17 a string (with the \code{`\textrm{\ldots}`} notation). The latter
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	18 conversion is implicitly used when an object is written by the
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	19 \keyword{print}\stindex{print} statement.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	20
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	21
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	22 \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	23
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	24 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	25 \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	26 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	27 \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	28 \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	29 \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	30 \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	31 \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	32
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	33 \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	34
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	35 \item \code{None}
24631 110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	36 \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	37
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	38 \item \code{False}
24631 110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	39 \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	40
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	41 \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	42 \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	43
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	44 \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	45
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	46 \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	47
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	48 \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	49 \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	50 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	51 \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	52 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	53 \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	54
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	55 \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	56
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	57 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	58 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	59 \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	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 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	62 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	63 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	64 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	65 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	66 \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	67 \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	68
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	69 \subsection{Boolean Operations \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	70
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	71 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	72 \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	73
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	74 \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	75 \lineiii{\var{x} or \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	76 {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	77 \lineiii{\var{x} and \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	78 {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	79 \hline
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	80 \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	81 {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	82 \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	83 \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	84 \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	85 \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	86
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	87 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	88 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	89
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	90 \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	91
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	92 \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	93 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	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 \item[(2)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	96 \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	97 \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	98 \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	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 \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	101
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	102
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	103 \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	104
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	105 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	106 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	107 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	108 \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	109 \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	110 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	111 \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	112 \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	113
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	114 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	115
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	116 \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	117 \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	118 \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	119 \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	120 \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	121 \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	122 \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	123 \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	124 \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	125 \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	126 \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	127 \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	128 \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	129 \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	130 \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	131
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	132 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	133 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	134
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	135 \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	136
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	137 \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	138 \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	139 \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	140
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	141 \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	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 Objects of different types, except different numeric types, never
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	144 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	145 (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	146 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	147 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	148 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	149 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	150 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	151 is a complex number.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	152 \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	153 \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	154
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	155 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	156 \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	157 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	158 \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	159 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	160
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	161 \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	162 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	163 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	164
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	165 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	166 \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	167 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	168
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	169
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	170 \subsection{Numeric Types \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	171
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	172 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	173 \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	174 \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	175 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	176 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	177 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	178 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	179 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	180 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	181 working with.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	182 \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	183 \obindex{Boolean}
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	184 \obindex{integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	185 \obindex{long integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	186 \obindex{floating point}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	187 \obindex{complex number}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	188 \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	189
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	190 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	191 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	192 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	193
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	194 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	195 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	196 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	197 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	198 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	199 \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	200 (\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	201 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	202 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	203 \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	204 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	205 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	206 \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	207 \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	208 \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	209 \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	210 \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	211 \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	212 \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	213
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	214 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	215 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	216 ``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	217 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	218 narrower than complex.
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	219 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	220 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	221 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	222 } The constructors \function{int()}, \function{long()}, \function{float()},
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	223 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	224 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	225 \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	226 \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	227 \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	228 \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	229 \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	230
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	231 All numeric types support the following operations, sorted by
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	232 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	233 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	234 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	235
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	236 \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	237 \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	238 \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	239 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	240 \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	241 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	242 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{}
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 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	244 \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	245 \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	246 \hline
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{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	248 \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	249 \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	250 \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	251 \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	252 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	253 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(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	254 \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	255 \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	256 \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	257 \indexiii{operations on}{numeric}{types}
10147 3ac7f0066375 Document <complex #>.conjugate(). Fred Drake <fdrake@acm.org> parents: 9558 diff changeset	258 \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	259
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	260 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	261 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	262 \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	263
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	264 \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	265 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	266 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	267 (-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	268 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	269 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	270 \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	271 \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	272
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	273 \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	274 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	275 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	276 \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	277 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	278 \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	279 \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	280 \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	281
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	282 \item[(3)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	283 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	284 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	285
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	286 \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	287 % 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	288
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	289 \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	290 \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	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 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	293 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	294 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	295 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	296
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	297 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	298 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	299 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	300 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	301
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	302 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	303 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	304
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	305 \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	306 \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	307 \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	308 \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} 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	309 \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	310 \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	311 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	312 \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	313 \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	314 \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	315 \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	316 \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	317 \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	318
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	319 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	320 Notes:
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{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	322 \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	323 \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	324 \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	325 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	326 \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	327 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	328 \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	329
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	330
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	331 \subsection{Iterator Types \label{typeiter}}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	332
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	333 \versionadded{2.2}
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	334 \index{iterator protocol}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	335 \index{protocol!iterator}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	336 \index{sequence!iteration}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	337 \index{container!iteration over}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	338
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	339 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	340 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	341 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	342 in more detail, always support the iteration methods.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	343
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	344 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	345 iteration support:
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	346
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	347 \begin{methoddesc}[container]{__iter__}{}
18839 ab8aa4302109 Typo fix. Greg Ward <gward@python.net> parents: 18829 diff changeset	348 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	349 iterator protocol described below. If a container supports
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	350 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	351 specifically request iterators for those iteration types. (An
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	352 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	353 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	354 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	355 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	356 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	357
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	358 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	359 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	360
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	361 \begin{methoddesc}[iterator]{__iter__}{}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	362 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	363 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	364 \keyword{in} statements. This method corresponds to the
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	365 \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	366 the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	367 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	368
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	369 \begin{methoddesc}[iterator]{next}{}
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	370 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	371 items, raise the \exception{StopIteration} exception. This method
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	372 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	373 for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	374 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	375
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	376 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	377 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	378 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	379 implementation of the iterator protocol.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	380
24253 62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	381 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	382 \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	383 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	384 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	385 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	386 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	387
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	388
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	389 \subsection{Sequence Types \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	390
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	391 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	392 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	393
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	394 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	395 \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	396 \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	397 string literals. Unicode strings are much like strings, but are
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	398 specified in the syntax using a preceeding \character{u} character:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	399 \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	400 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	401 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	402 or without enclosing parentheses, but an empty tuple must have the
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	403 enclosing parentheses, e.g., \code{a, b, c} or \code{()}. A single
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	404 item tuple must have a trailing comma, e.g., \code{(d,)}.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	405 \obindex{sequence}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	406 \obindex{string}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	407 \obindex{Unicode}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	408 \obindex{tuple}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	409 \obindex{list}
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	410
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	411 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	412 created by calling the builtin function
25393 f559e97a41be Remove spurious period. Fred Drake <fdrake@acm.org> parents: 24902 diff changeset	413 \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	414 concatenation or repetition.
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	415 \obindex{buffer}
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	416
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	417 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	418 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	419 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	420 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	421 \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	422 \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	423
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	424 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	425 \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	426 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	427 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	428 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	429
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	430 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	431 (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	432 \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	433 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	434
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	435 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	436 \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{(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	437 \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	438 equal to \var{x}, else \code{1}}{(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	439 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	440 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	441 \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	442 \hline
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	443 \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	444 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(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	445 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	446 \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	447 \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	448 \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	449 \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	450 \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	451 \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	452 \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	453 \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	454 \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	455 \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	456 \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	457 \indexii{slice}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	458 \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	459 \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	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 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	462 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	463
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	464 \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	465 \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	466 \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	467 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	468 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	469
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	470 \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	471 \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	472 \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	473 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	474
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	475 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	476 >>> lists = [[]] * 3
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	477 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	478 [[], [], []]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	479 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	480 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	481 [[3], [3], [3]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	482 \end{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	483
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	484 What has happened is that \code{lists} is a list containing three
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	485 copies of the list \code{[[]]} (a one-element list containing an
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	486 empty list), but the contained list is shared by each copy. You can
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	487 create a list of different lists this way:
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	488
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	489 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	490 >>> 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	491 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	492 >>> lists[1].append(5)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	493 >>> lists[2].append(7)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	494 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	495 [[3], [5], [7]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	496 \end{verbatim}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	497
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	498 \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	499 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	500 \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	501 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	502
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	503 \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	504 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	505 \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	506 \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	507 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	508 \var{i} is greater than or equal to \var{j}, the slice is empty.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	509 \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	510
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	511
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	512 \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	513
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	514 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	515 objects support:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	516
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	517 \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	518 Return a copy of the string with only its first character capitalized.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	519 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	520
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	521 \begin{methoddesc}[string]{center}{width}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	522 Return centered in a string of length \var{width}. Padding is done
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	523 using spaces.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	524 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	525
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	526 \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	527 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	528 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	529 \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	530 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	531
21332 fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	532 \begin{methoddesc}[string]{decode}{\optional{encoding\optional{, errors}}}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	533 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	534 \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	535 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	536 \code{'strict'}, meaning that encoding errors raise
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	537 \exception{ValueError}. Other possible values are \code{'ignore'} and
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	538 \code{replace'}.
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	539 \versionadded{2.2}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	540 \end{methoddesc}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	541
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	542 \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	543 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	544 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	545 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	546 \code{'strict'}, meaning that encoding errors raise a
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	547 \exception{ValueError}. Other possible values are \code{'ignore'} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	548 \code{'replace'}.
15332 12aec3381c94 Marc-Andre Lemburg <mal@lemburg.com> noted that the encode() string method Fred Drake <fdrake@acm.org> parents: 15005 diff changeset	549 \versionadded{2.0}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	550 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	551
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	552 \begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	553 Return true if the string ends with the specified \var{suffix},
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	554 otherwise return 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	555 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	556 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	557
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	558 \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	559 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	560 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	561 characters is assumed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	562 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	563
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	564 \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	565 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	566 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	567 \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	568 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	569 not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	570 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	571
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	572 \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	573 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	574 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	575 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	576
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	577 \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	578 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	579 is at least one character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	580 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	581
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	582 \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	583 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	584 is at least one character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	585 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	586
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	587 \begin{methoddesc}[string]{isdigit}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	588 Return true if there are only digit characters, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	589 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	590
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	591 \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	592 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	593 there is at least one cased character, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	594 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	595
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	596 \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	597 Return true if there are only whitespace characters in the string and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	598 the string is not empty, false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	599 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	600
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	601 \begin{methoddesc}[string]{istitle}{}
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	602 Return true if the string is a titlecased string: uppercase
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	603 characters may only follow uncased characters and lowercase characters
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	604 only cased ones. Return false otherwise.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	605 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	606
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	607 \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	608 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	609 there is at least one cased character, false otherwise.
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]{join}{seq}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	613 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	614 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	615 providing this method.
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]{ljust}{width}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	619 Return the string left justified in a string of length \var{width}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	620 Padding is done using spaces. The original string is returned if
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	621 \var{width} is less than \code{len(\var{s})}.
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]{lower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	625 Return a copy of the string converted to lowercase.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	626 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	627
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	628 \begin{methoddesc}[string]{lstrip}{\optional{chars}}
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	629 Return a copy of the string with leading characters removed. If
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	630 \var{chars} is omitted or \code{None}, whitespace characters are
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	631 removed. If given and not \code{None}, \var{chars} must be a string;
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	632 the characters in the string will be stripped from the beginning of
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	633 the string this method is called on.
26259 60d809a25bae Document that a minor feature was added in 2.2.2. ;-( Fred Drake <fdrake@acm.org> parents: 26161 diff changeset	634 \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	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]{replace}{old, new\optional{, maxsplit}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	638 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	639 \var{old} replaced by \var{new}. If the optional argument
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	640 \var{maxsplit} is given, only the first \var{maxsplit} occurrences are
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	641 replaced.
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]{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	645 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	646 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	647 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	648 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	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]{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	652 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	653 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	654 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	655
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	656 \begin{methoddesc}[string]{rjust}{width}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	657 Return the string right justified in a string of length \var{width}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	658 Padding is done using spaces. The original string is returned if
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	659 \var{width} is less than \code{len(\var{s})}.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	660 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	661
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	662 \begin{methoddesc}[string]{rstrip}{\optional{chars}}
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	663 Return a copy of the string with trailing characters removed. If
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	664 \var{chars} is omitted or \code{None}, whitespace characters are
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	665 removed. If given and not \code{None}, \var{chars} must be a string;
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	666 the characters in the string will be stripped from the end of the
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	667 string this method is called on.
26259 60d809a25bae Document that a minor feature was added in 2.2.2. ;-( Fred Drake <fdrake@acm.org> parents: 26161 diff changeset	668 \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	669 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	670
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	671 \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	672 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	673 delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	674 splits are done. If \var{sep} is not specified or \code{None}, any
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	675 whitespace string is a separator.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	676 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	677
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	678 \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	679 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	680 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	681 \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	682 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	683
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	684 \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	685 start\optional{, end}}}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	686 Return true if string starts with the \var{prefix}, otherwise
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	687 return 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	688 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	689 position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	690 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	691
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	692 \begin{methoddesc}[string]{strip}{\optional{chars}}
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	693 Return a copy of the string with leading and trailing characters
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	694 removed. If \var{chars} is omitted or \code{None}, whitespace
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	695 characters are removed. If given and not \code{None}, \var{chars}
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	696 must be a string; the characters in the string will be stripped from
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	697 the both ends of the string this method is called on.
26259 60d809a25bae Document that a minor feature was added in 2.2.2. ;-( Fred Drake <fdrake@acm.org> parents: 26161 diff changeset	698 \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	699 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	700
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	701 \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	702 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	703 lowercase and vice versa.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	704 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	705
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	706 \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	707 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	708 characters, all remaining cased characters are lowercase.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	709 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	710
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	711 \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	712 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	713 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	714 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	715 must be a string of length 256.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	716 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	717
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	718 \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	719 Return a copy of the string converted to uppercase.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	720 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	721
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	722 \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	723 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	724 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	725 \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	726 \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	727 \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	728
13933 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 \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	731
21177 7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments Fred Drake <fdrake@acm.org> parents: 21163 diff changeset	732 \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	733 \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	734 \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	735 \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	736 \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	737 \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	738 \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	739 \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	740
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	741 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	742 \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	743 \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	744 \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	745 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	746 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	747 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	748 \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	749 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	750 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	751
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	752 If \var{format} requires a single argument, \var{values} may be a
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	753 single non-tuple object. \footnote{To format only a tuple you
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	754 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	755 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	756 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	757 single mapping object (for example, a dictionary).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	758
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	759 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	760 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	761
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	762 \begin{enumerate}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	763 \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	764 specifier.
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	765 \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	766 of characters (for example, \code{(somename)}).
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	767 \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	768 conversion types.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	769 \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	770 \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	771 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	772 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	773 precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	774 \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	775 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	776 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	777 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	778 the precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	779 \item Length modifier (optional).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	780 \item Conversion type.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	781 \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	782
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	783 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	784 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	785 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	786 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	787 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	788
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	789 \begin{verbatim}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	790 >>> 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	791 {'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	792 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	793 \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	794
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	795 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	796 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	797
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	798 The conversion flag characters are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	799
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	800 \begin{tableii}{c\|l}{character}{Flag}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	801 \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	802 (where defined below).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	803 \lineii{0}{The conversion will be zero padded.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	804 \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	805 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	806 \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	807 (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	808 \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	809 precede the conversion (overrides a "space" flag).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	810 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	811
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	812 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	813 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	814
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	815 The conversion types are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	816
25906 50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	817 \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	818 \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	819 \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	820 \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	821 \lineiii{u}{Unsigned decimal.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	822 \lineiii{x}{Unsigned hexidecimal (lowercase).}{(2)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	823 \lineiii{X}{Unsigned hexidecimal (uppercase).}{(2)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	824 \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	825 \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	826 \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	827 \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	828 \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	829 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	830 \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	831 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	832 \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	833 string).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	834 \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	835 \function{repr()}).}{(3)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	836 \lineiii{s}{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	837 \function{str()}).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	838 \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	839 character in the result.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	840 \end{tableiii}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	841
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	842 \noindent
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	843 Notes:
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	844 \begin{description}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	845 \item[(1)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	846 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	847 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	848 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	849 zero.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	850 \item[(2)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	851 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	852 (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	853 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	854 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	855 not already a zero.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	856 \item[(3)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	857 The \code{\%r} conversion was added in Python 2.0.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	858 \end{description}
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	859
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	860 % XXX Examples?
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	861
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	862 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	863 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	864
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	865 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	866 \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	867 are replaced by \code{\%g} conversions.\footnote{
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	868 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	869 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	870 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	871 point values on a particular machine.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	872 } All other errors raise exceptions.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	873
21163 7b6879714b74 Make no assumption about how modules are built when referring to them; this Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	874 Additional string operations are defined in standard modules
7b6879714b74 Make no assumption about how modules are built when referring to them; this Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	875 \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	876 \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	877
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	878
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	879 \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	880
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	881 The xrange\obindex{xrange} type is an immutable sequence which is
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	882 commonly used for looping. The advantage of the xrange type is that an
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	883 xrange object will always take the same amount of memory, no matter the
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	884 size of the range it represents. There are no consistent performance
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	885 advantages.
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	886
26592 0c646baeec58 Update comments about the performance of xrange(). Raymond Hettinger <python@rcn.com> parents: 26514 diff changeset	887 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	888 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	889
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	890
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	891 \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	892
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	893 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	894 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	895 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	896 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	897 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	898 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	899 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	900 \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	901 \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	902 \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	903
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	904 \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	905 \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	906 {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	907 \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	908 {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	909 \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	910 {same as \code{\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	911 \lineiii{\var{s}.append(\var{x})}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	912 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(1)}
9318 8a26e55e18b8 Document the new list.extend() method. Interesting enough, the Barry Warsaw <barry@python.org> parents: 9083 diff changeset	913 \lineiii{\var{s}.extend(\var{x})}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	914 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(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	915 \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	916 {return number of \var{i}'s for which \code{\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	917 \lineiii{\var{s}.index(\var{x})}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	918 {return smallest \var{i} such that \code{\var{s}[\var{i}] == \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	919 \lineiii{\var{s}.insert(\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	920 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	921 if \code{\var{i} >= 0}}{(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	922 \lineiii{\var{s}.pop(\optional{\var{i}})}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	923 {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \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	924 \lineiii{\var{s}.remove(\var{x})}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	925 {same as \code{del \var{s}[\var{s}.index(\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	926 \lineiii{\var{s}.reverse()}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	927 {reverses the items of \var{s} in place}{(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	928 \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
26161 dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	929 {sort the items of \var{s} in place}{(6), (7), (8), (9)}
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 \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	931 \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	932 \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	933 \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	934 \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	935 \indexii{slice}{assignment}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	936 \stindex{del}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	937 \withsubitem{(list method)}{
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	938 \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	939 \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	940 \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	941 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	942 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	943 \begin{description}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	944 \item[(1)] The C implementation of Python historically accepted
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	945 multiple parameters and implicitly joined them into a tuple;
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	946 Use of this misfeature has been deprecated since Python 1.4,
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	947 and became an error with the introduction of Python 2.0.
23778 245224d1b8c9 This is my nearly two year old patch Michael W. Hudson <mwh@python.net> parents: 23515 diff changeset	948
26816 6932794817c2 SF Bug 645777: list.extend() works with any iterable and is no longer Raymond Hettinger <python@rcn.com> parents: 26672 diff changeset	949 \item[(2)] Raises an exception when \var{x} is not an iterable object.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	950
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	951 \item[(3)] Raises \exception{ValueError} when \var{x} is not found in
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	952 \var{s}.
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	953
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	954 \item[(4)] When a negative index is passed as the first parameter to
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	955 the \method{insert()} method, the new element is prepended to the
5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	956 sequence.
5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	957
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	958 \item[(5)] 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	959 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	960 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	961
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	962 \item[(6)] 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	963 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	964 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	965 the sorted or reversed list.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	966
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	967 \item[(7)] The \method{sort()} method takes an optional argument
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	968 specifying a comparison function of two arguments (list items) which
20173 f100793ca9af The list.sort() docs require a function that returns -1, 0 or +1. That's Tim Peters <tim.peters@gmail.com> parents: 20045 diff changeset	969 should return a negative, zero or positive number depending on whether
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	970 the first argument is considered smaller than, equal to, or larger
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	971 than the second argument. Note that this slows the sorting process
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	972 down considerably; e.g. to sort a list in reverse order it is much
24459 189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	973 faster to call method \method{sort()} followed by
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	974 \method{reverse()} than to use method
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	975 \method{sort()} with a comparison function that reverses the
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	976 ordering of the elements.
24459 189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	977
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	978 \item[(8)] Whether the \method{sort()} method is stable is not defined by
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	979 the language (a sort is stable if it guarantees not to change the
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	980 relative order of elements that compare equal). In the C
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	981 implementation of Python, sorts were stable only by accident through
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	982 Python 2.2. The C implementation of Python 2.3 introduced a stable
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	983 \method{sort()} method, but code that intends to be portable across
189eb6fa9ded Added new footnote about list.sort() stability. Repaired footnote about Tim Peters <tim.peters@gmail.com> parents: 24253 diff changeset	984 implementations and versions must not rely on stability.
26161 dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	985
dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	986 \item[(9)] While a list is being sorted, the effect of attempting to
dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	987 mutate, or even inspect, the list is undefined. The C implementation
dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	988 of Python 2.3 makes the list appear empty for the duration, and raises
dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	989 \exception{ValueError} if it can detect that the list has been
dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	990 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	991 \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	992
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	993
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	994 \subsection{Mapping Types \label{typesmapping}}
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	995 \obindex{mapping}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	996 \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	997
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	998 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	999 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	1000 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	1001 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	1002 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	1003 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	1004 Numeric types used for keys obey the normal rules for numeric
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1005 comparison: if two numbers compare equal (e.g. \code{1} and
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1006 \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	1007 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	1008
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1009 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	1010 \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	1011 \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	1012 \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	1013
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1014 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	1015 \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	1016 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	1017 \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	1018 \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	1019 \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	1020 \bifuncindex{len}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1021 \withsubitem{(dictionary method)}{
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1022 \ttindex{clear()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1023 \ttindex{copy()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1024 \ttindex{has_key()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1025 \ttindex{items()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1026 \ttindex{keys()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1027 \ttindex{update()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1028 \ttindex{values()}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1029 \ttindex{get()}}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1030
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1031 \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	1032 \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	1033 \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	1034 \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	1035 {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	1036 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1037 \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	1038 {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	1039 {(1)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1040 \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	1041 \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	1042 \lineiii{\var{a}.has_key(\var{k})}
17594 bf94af396b1e Implement, test and document "key in dict" and "key not in dict". Guido van Rossum <guido@python.org> parents: 16778 diff changeset	1043 {\code{1} if \var{a} has a key \var{k}, else \code{0}}
bf94af396b1e Implement, test and document "key in dict" and "key not in dict". Guido van Rossum <guido@python.org> parents: 16778 diff changeset	1044 {}
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	1045 \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	1046 {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	1047 {(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	1048 \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	1049 {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	1050 {(2)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1051 \lineiii{\var{a}.items()}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1052 {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	1053 {(3)}
18085 7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these Fred Drake <fdrake@acm.org> parents: 17966 diff changeset	1054 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1055 \lineiii{\var{a}.update(\var{b})}
26437 57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1056 {\code{for \var{k} in \var{b}.keys(): \var{a}[\var{k}] = \var{b}[\var{k}]}}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1057 {}
26437 57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1058 \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	1059 {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	1060 {(7)}
18085 7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these Fred Drake <fdrake@acm.org> parents: 17966 diff changeset	1061 \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	1062 \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	1063 {\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	1064 else \var{x}}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1065 {(4)}
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1066 \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	1067 {\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	1068 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	1069 {(5)}
22994 196dfa7ed348 Add Raymond Hettinger's d.pop(). See SF patch 539949. Guido van Rossum <guido@python.org> parents: 22920 diff changeset	1070 \lineiii{\var{a}.pop(\var{k})}
196dfa7ed348 Add Raymond Hettinger's d.pop(). See SF patch 539949. Guido van Rossum <guido@python.org> parents: 22920 diff changeset	1071 {remove specified \var{key} and return corresponding \var{value}}
196dfa7ed348 Add Raymond Hettinger's d.pop(). See SF patch 539949. Guido van Rossum <guido@python.org> parents: 22920 diff changeset	1072 {}
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1073 \lineiii{\var{a}.popitem()}
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1074 {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	1075 {(6)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1076 \lineiii{\var{a}.iteritems()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1077 {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	1078 {(2), (3)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1079 \lineiii{\var{a}.iterkeys()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1080 {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	1081 {(2), (3)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1082 \lineiii{\var{a}.itervalues()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1083 {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	1084 {(2), (3)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1085 \end{tableiii}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1086
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 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1088 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1089 \begin{description}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1090 \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	1091 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	1092
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1093 \item[(2)] \versionadded{2.2}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1094
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1095 \item[(3)] Keys and values are listed in random order. If
24902 f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1096 \method{items()}, \method{keys()}, \method{values()},
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1097 \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	1098 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	1099 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	1100 \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	1101 \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	1102 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	1103 \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	1104 \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	1105 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	1106 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	1107
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1108 \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	1109 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	1110 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	1111
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1112 \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	1113 that if \var{k} is missing, \var{x} is both returned and inserted into
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1114 the dictionary as the value of \var{k}.
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1115
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1116 \item[(6)] \function{popitem()} is useful to destructively iterate
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1117 over a dictionary, as often used in set algorithms.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1118
26437 57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1119 \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	1120 new dictionary. \var{value} defaults to \code{None}. \versionadded{2.3}
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1121 \end{description}
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1122
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1123
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1124 \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	1125 \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	1126
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1127 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	1128 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	1129 \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	1130 \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	1131 is new in Python 2.2. The older built-in \function{open()} is an
37b8d92e12f5 Mention the new file() builtin in the section on file objects. Tim Peters <tim.peters@gmail.com> parents: 20701 diff changeset	1132 alias for \function{file()}.}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1133 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	1134 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	1135 \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	1136 \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	1137 \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	1138 \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	1139
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1140 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	1141 \exception{IOError} is raised. This includes situations where the
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1142 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	1143 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	1144
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1145 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	1146
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1147
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1148 \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	1149 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	1150 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	1151 \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	1152 \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	1153 \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	1154
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1155 \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	1156 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	1157 \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	1158 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	1159 \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	1160
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1161 \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	1162 \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	1163 \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	1164 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	1165 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	1166 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	1167 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	1168 \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	1169 \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	1170 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	1171 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	1172 \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	1173
24599 d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1174 \begin{methoddesc}[file]{isatty}{}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1175 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	1176 \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	1177 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	1178 \end{methoddesc}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1179
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1180 \begin{methoddesc}[file]{next}{}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1181 A file object is its own iterator, i.e. \code{iter(\var{f})} returns
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1182 \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	1183 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	1184 \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	1185 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	1186 \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	1187 \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	1188 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	1189 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	1190 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	1191 \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	1192 \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	1193 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	1194 \versionadded{2.3}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1195 \end{methoddesc}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1196
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1197 \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	1198 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	1199 \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	1200 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	1201 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	1202 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	1203 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	1204 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	1205 C function \cfunction{fread()} more than once in an effort to
26672 8dd25a6f5913 Fixed bug Gustavo Niemeyer <gustavo@niemeyer.net> parents: 26592 diff changeset	1206 acquire as close to \var{size} bytes as possible. Also note that
8dd25a6f5913 Fixed bug Gustavo Niemeyer <gustavo@niemeyer.net> parents: 26592 diff changeset	1207 when in non-blocking mode, less data than what was requested may
8dd25a6f5913 Fixed bug Gustavo Niemeyer <gustavo@niemeyer.net> parents: 26592 diff changeset	1208 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	1209 \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	1210
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1211 \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	1212 Read one entire line from the file. A trailing newline character is
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	1213 kept in the string\footnote{
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1214 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	1215 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	1216 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	1217 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	1218 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	1219 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	1220 or not (yes this happens!).
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1221 } (but may be absent when a file ends with an
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1222 incomplete line). If the \var{size} argument is present and
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1223 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	1224 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	1225 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	1226 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	1227 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	1228 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	1229 \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	1230
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1231 \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	1232 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	1233 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	1234 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	1235 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	1236 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	1237 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	1238 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	1239 \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	1240
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1241 \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	1242 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	1243 \versionadded{2.1}
24599 d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1244 \deprecated{2.3}{Use \code{for line in file} instead.}
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1245 \end{methoddesc}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1246
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1247 \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	1248 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	1249 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	1250 (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	1251 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	1252 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	1253 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	1254 \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	1255 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	1256 this method is essentially a no-op, but it remains useful for files
a06415994cb5 Added information about the interaction of opening a file in append mode Fred Drake <fdrake@acm.org> parents: 15522 diff changeset	1257 opened in append mode with reading enabled (mode \code{'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	1258 \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	1259
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1260 \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	1261 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	1262 \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	1263 \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	1264
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1265 \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	1266 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	1267 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	1268 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	1269 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	1270 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	1271 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	1272 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	1273 undefined new content.
22214 e24ba04d01b0 file_truncate(): provide full "large file" support on Windows, by Tim Peters <tim.peters@gmail.com> parents: 21542 diff changeset	1274 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	1275 \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	1276
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1277 \begin{methoddesc}[file]{write}{str}
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1278 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	1279 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	1280 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	1281 \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	1282
20045 7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1283 \begin{methoddesc}[file]{writelines}{sequence}
7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1284 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	1285 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	1286 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	1287 (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	1288 \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	1289 \end{methoddesc}
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1290
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1291
20031 e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1292 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	1293 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	1294 \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	1295
e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1296
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1297 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	1298 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	1299 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	1300
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1301 \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	1302 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	1303 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	1304 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	1305 \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	1306
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1307 \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	1308 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	1309 \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	1310 \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	1311 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	1312 \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	1313
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1314 \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	1315 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	1316 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	1317 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	1318 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	1319 \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	1320
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1321 \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	1322 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	1323 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	1324 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	1325 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	1326 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	1327 (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	1328 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	1329 \member{softspace} attribute.
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1330 \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	1331 \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	1332 \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	1333 \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	1334
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1335
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1336 \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	1337
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1338 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	1339 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	1340
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1341
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1342 \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	1343
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1344 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	1345 \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	1346 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	1347 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	1348 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	1349 \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	1350 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	1351 \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	1352
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1353 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	1354 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	1355 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	1356 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	1357 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	1358 defines \code{\var{m}.a} to be \code{1}, but you can't write
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1359 \code{\var{m}.__dict__ = \{\}}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1360
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1361 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	1362 \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	1363 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	1364 '/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	1365
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1366
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1367 \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	1368 \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	1369
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1370 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	1371 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	1372
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1373
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1374 \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	1375
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1376 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	1377 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	1378 \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	1379
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1380 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	1381 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	1382 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	1383 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	1384
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1385 The implementation adds two special read-only attributes:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1386 \code{\var{f}.func_code} is a function's \dfn{code
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1387 object}\obindex{code} (see below) and \code{\var{f}.func_globals} is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1388 the dictionary used as the function's global namespace (this is the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1389 same as \code{\var{m}.__dict__} where \var{m} is the module in which
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1390 the function \var{f} was defined).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1391
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1392 Function objects also support getting and setting arbitrary
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1393 attributes, which can be used to, e.g. attach metadata to functions.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1394 Regular attribute dot-notation is used to get and set such
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1395 attributes. \emph{Note that the current implementation only supports
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1396 function attributes on user-defined functions. Function attributes on
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1397 built-in functions may be supported in the future.}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1398
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1399 Functions have another special attribute \code{\var{f}.__dict__}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1400 (a.k.a. \code{\var{f}.func_dict}) which contains the namespace used to
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1401 support function attributes. \code{__dict__} and \code{func_dict} can
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1402 be accessed directly or set to a dictionary object. A function's
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1403 dictionary cannot be deleted.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1404
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1405 \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	1406 \obindex{method}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1407
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1408 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	1409 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	1410 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	1411 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	1412
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1413 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	1414 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	1415 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	1416 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	1417 \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	1418 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	1419 \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	1420
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1421 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	1422 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	1423 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	1424 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	1425 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	1426 \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	1427 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	1428
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1429 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	1430 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	1431 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	1432 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	1433 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	1434 \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	1435 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	1436
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1437 \begin{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1438 class C:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1439 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	1440 pass
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1441
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1442 c = C()
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1443 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	1444 \end{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1445
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1446 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	1447 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1448
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1449
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1450 \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	1451 \obindex{code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1452
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1453 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	1454 ``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	1455 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	1456 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	1457 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	1458 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	1459 attribute.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1460 \bifuncindex{compile}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1461 \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	1462
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1463 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	1464 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	1465 \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	1466 \stindex{exec}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1467 \bifuncindex{eval}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1468
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1469 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	1470 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1471
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1472
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1473 \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	1474
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1475 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	1476 accessed by the built-in function \function{type()}. There are no special
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1477 operations on types. The standard module \module{types} defines names
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1478 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	1479 \bifuncindex{type}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1480 \refstmodindex{types}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1481
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1482 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	1483
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1484
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1485 \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	1486
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1487 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	1488 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	1489 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	1490
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1491 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	1492
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1493
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1494 \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	1495
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1496 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	1497 \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	1498 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	1499 \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	1500
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1501 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	1502
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	1503 \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	1504
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1505 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	1506 \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	1507 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	1508 (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	1509 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	1510 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	1511 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	1512 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	1513
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1514 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	1515 \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	1516 \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	1517 \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	1518
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1519
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1520 \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	1521
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1522 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	1523 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	1524 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	1525
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1526
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1527 \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	1528
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1529 The implementation adds a few special read-only attributes to several
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1530 object types, where they are relevant:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1531
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1532 \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	1533 A dictionary or other mapping object used to store an
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1534 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	1535 \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	1536
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1537 \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	1538 \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	1539 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	1540 \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	1541
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1542 \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	1543 \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	1544 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	1545 \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	1546
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1547 \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	1548 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	1549 \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	1550
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1551 \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	1552 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	1553 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	1554 \end{memberdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstdtypes.tex @ 27022:e2c88c451c19 legacy-trunk