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

annotate Doc/lib/libstdtypes.tex @ 25838:8540887bcec6 2.2

Backport of 2.183: Fix memory leak in add_subclass() found by NealN with valgrind.

author	Guido van Rossum <guido@python.org>
date	Fri, 18 Oct 2002 13:42:21 +0000
parents	b287bdacde39
children	6ea9eef99108

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
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	4 the interpreter. These are the numeric types, sequence types, and
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	5 several others, including types themselves. There is no explicit
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	6 Boolean type; use integers instead.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	7 \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	8 \indexii{Boolean}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	9
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	10 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	11 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	12 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	13 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	14 \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	15
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	16
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	17 \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	18
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	19 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	20 \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	21 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	22 \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	23 \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	24 \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	25 \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	26 \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	27
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	28 \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	29
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	30 \item \code{None}
24632 f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	31 \withsubitem{(Built-in object)}{\ttindex{None}}
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	32
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	33 \item \code{False}
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	34 \withsubitem{(Built-in object)}{\ttindex{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	35
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	36 \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	37 \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	38
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	39 \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	40
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	41 \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	42
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	43 \item instances of user-defined classes, if the class defines a
24632 f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	44 \method{__nonzero__()} or \method{__len__()} method, when that
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	45 method returns the integer zero or \class{bool} value
f6a97cd3ba24 Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24228 diff changeset	46 \code{False}.\footnote{Additional
24228 5b66e63d7abb Clarify the return value of __nonzero__(): It must be an integer. Fred Drake <fdrake@acm.org> parents: 23461 diff changeset	47 information on these special methods may be found in the
5b66e63d7abb Clarify the return value of __nonzero__(): It must be an integer. Fred Drake <fdrake@acm.org> parents: 23461 diff changeset	48 \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	49
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	50 \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	51
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	52 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	53 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	54 \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	55
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	56 Operations and built-in functions that have a Boolean result always
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	57 return \code{0} for false and \code{1} for true, unless otherwise
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	58 stated. (Important exception: the 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	59 \samp{or}\opindex{or} and \samp{and}\opindex{and} always return one of
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	60 their operands.)
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	61
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	62
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	63 \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	64
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	65 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	66 \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	67
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	68 \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	69 \lineiii{\var{x} or \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	70 {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	71 \lineiii{\var{x} and \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	72 {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	73 \hline
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	74 \lineiii{not \var{x}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	75 {if \var{x} is false, then \code{1}, else \code{0}}{(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	76 \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	77 \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	78 \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	79 \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	80
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	81 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	82 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	83
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	84 \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	85
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	86 \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	87 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	88
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	89 \item[(2)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	90 \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	91 \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	92 \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	93
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	94 \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	95
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	96
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	97 \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	98
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	99 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	100 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	101 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	102 \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	103 \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	104 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	105 \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	106 \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	107
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	108 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	109
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	110 \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	111 \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	112 \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	113 \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	114 \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	115 \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	116 \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	117 \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	118 \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	119 \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	120 \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	121 \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	122 \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	123 \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	124 \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	125
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	126 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	127 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	128
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	129 \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	130
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	131 \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	132 \code{<>} and \code{!=} are alternate spellings for the same operator.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	133 (I couldn't choose between \ABC{} and C! :-)
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	134 \index{ABC language@\ABC{} language}
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20767 diff changeset	135 \index{language!ABC@\ABC}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	136 \indexii{C}{language}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	137 \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	138
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	139 \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	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 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	142 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	143 (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	144 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	145 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	146 unequal. Again, such objects are ordered arbitrarily but
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	147 consistently.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	148 \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	149 \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	150
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	151 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	152 \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	153 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	154 \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	155 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	156
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	157 \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	158 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	159 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	160
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	161 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	162 \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	163 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	164
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	165
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	166 \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	167
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	168 There are four numeric types: \dfn{plain integers}, \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	169 \dfn{floating point numbers}, and \dfn{complex numbers}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	170 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	171 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	172 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	173 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	174 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	175 working with.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	176 \obindex{numeric}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	177 \obindex{integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	178 \obindex{long integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	179 \obindex{floating point}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	180 \obindex{complex number}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	181 \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	182
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	183 Complex numbers have a real and imaginary part, which are both
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	184 implemented using \ctype{double} in C. To extract these parts from
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	185 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	186
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	187 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	188 functions and operators. Unadorned integer literals (including hex
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	189 and octal numbers) yield plain integers. Integer literals with an
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	190 \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	191 (\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	192 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	193 sign yield floating point numbers. Appending \character{j} or
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	194 \character{J} to a numeric literal yields a complex number.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	195 \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	196 \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	197 \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	198 \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	199 \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	200 \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	201 \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	202
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	203 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	204 operator has operands of different numeric types, the operand with the
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	205 ``smaller'' type is converted to that of the other, where plain
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	206 integer is smaller than long integer is smaller than floating point is
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	207 smaller than complex.
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	208 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	209 As a consequence, the list \code{[1, 2]} is considered equal
11100 fa2e3d06c790 Minor markup nit. Fred Drake <fdrake@acm.org> parents: 10968 diff changeset	210 to \code{[1.0, 2.0]}, and similar for tuples.
fa2e3d06c790 Minor markup nit. Fred Drake <fdrake@acm.org> parents: 10968 diff changeset	211 } The functions \function{int()}, \function{long()}, \function{float()},
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	212 and \function{complex()} can be used
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	213 to coerce numbers to a specific type.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	214 \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	215 \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	216 \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	217 \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	218 \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	219
25586 b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	220 All numeric types (except complex) support the following operations,
b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	221 sorted by ascending priority (operations in the same box have the same
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	222 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	223 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	224
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	225 \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	226 \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	227 \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	228 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	229 \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	230 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
25586 b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	231 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	232 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	233 \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	234 \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	235 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	236 \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	237 \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	238 \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	239 \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	240 \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	241 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
25586 b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	242 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	243 \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	244 \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	245 \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	246 \indexiii{operations on}{numeric}{types}
10147 3ac7f0066375 Document <complex #>.conjugate(). Fred Drake <fdrake@acm.org> parents: 9558 diff changeset	247 \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	248
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	249 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	250 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	251 \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	252
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	253 \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	254 For (plain or long) integer division, the result is an integer.
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	255 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	256 (-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	257 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	258 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	259 \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	260 \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	261
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	262 \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	263 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	264 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	265 \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	266 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	267 \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	268 \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	269 \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	270
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	271 \item[(3)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	272 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	273 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	274
25586 b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	275 \item[(4)]
b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	276 Complex floor division operator, modulo operator, and \function{divmod()}.
b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	277
b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	278 \deprecated{2.3}{Instead convert to float using \function{abs()}
b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	279 if appropriate.}
b287bdacde39 Backport 1.94: Raymond Hettinger <python@rcn.com> parents: 25585 diff changeset	280
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 \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	282 % 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	283
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	284 \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	285 \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	286
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	287 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	288 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	289 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	290 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	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 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	293 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	294 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	295 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	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 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	298 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	299
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	300 \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	301 \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	302 \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	303 \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	304 \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	305 \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	306 \hline
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}}{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	308 \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	309 \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	310 \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	311 \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	312 \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	313
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	314 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	315 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	316 \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	317 \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	318 \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	319 \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	320 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	321 \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	322 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	323 \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	324
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	325
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	326 \subsection{Iterator Types \label{typeiter}}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	327
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	328 \versionadded{2.2}
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	329 \index{iterator protocol}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	330 \index{protocol!iterator}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	331 \index{sequence!iteration}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	332 \index{container!iteration over}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	333
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	334 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	335 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	336 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	337 in more detail, always support the iteration methods.
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 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	340 iteration support:
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	341
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	342 \begin{methoddesc}[container]{__iter__}{}
18839 ab8aa4302109 Typo fix. Greg Ward <gward@python.net> parents: 18829 diff changeset	343 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	344 iterator protocol described below. If a container supports
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	345 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	346 specifically request iterators for those iteration types. (An
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	347 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	348 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	349 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	350 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	351 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	352
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	353 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	354 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	355
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	356 \begin{methoddesc}[iterator]{__iter__}{}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	357 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	358 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	359 \keyword{in} statements. This method corresponds to the
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	360 \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	361 the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	362 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	363
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	364 \begin{methoddesc}[iterator]{next}{}
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	365 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	366 items, raise the \exception{StopIteration} exception. This method
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	367 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	368 for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	369 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	370
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	371 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	372 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	373 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	374 implementation of the iterator protocol.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	375
25585 dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	376 The intention of the protocol is that once an iterator's
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	377 \method{next()} method raises \exception{StopIteration}, it will
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	378 continue to do so on subsequent calls. Implementations that
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	379 do not obey this property are deemed broken. (This constraint
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	380 was added in Python 2.3; in Python 2.2, various iterators are
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	381 broken according to this rule.)
dae2282bc76b Backport 1.100: Discussion of Stop Iteration in the Iterator Protocol. Raymond Hettinger <python@rcn.com> parents: 24903 diff changeset	382
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	383
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	384 \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	385
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	386 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	387 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	388
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	389 Strings 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	390 \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	391 \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	392 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	393 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	394 \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	395 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	396 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	397 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	398 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	399 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	400 \obindex{sequence}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	401 \obindex{string}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	402 \obindex{Unicode}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	403 \obindex{tuple}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	404 \obindex{list}
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	405
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	406 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	407 created by calling the builtin function
23355 67bcb4f5237f Remove extra period produced by previous change. Fred Drake <fdrake@acm.org> parents: 23341 diff changeset	408 \function{buffer()}.\bifuncindex{buffer} They support concatenation
67bcb4f5237f Remove extra period produced by previous change. Fred Drake <fdrake@acm.org> parents: 23341 diff changeset	409 and repetition, but the result is a new string object rather than a
67bcb4f5237f Remove extra period produced by previous change. Fred Drake <fdrake@acm.org> parents: 23341 diff changeset	410 new buffer object.
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	411 \obindex{buffer}
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	412
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	413 Xrange objects are similar to buffers in that there is no specific
23341 55423c1abcd1 Correct information on support for repietition & concatenation for buffer Fred Drake <fdrake@acm.org> parents: 23319 diff changeset	414 syntax to create them, but they are created using the
55423c1abcd1 Correct information on support for repietition & concatenation for buffer Fred Drake <fdrake@acm.org> parents: 23319 diff changeset	415 \function{xrange()} function.\bifuncindex{xrange} They don't support
55423c1abcd1 Correct information on support for repietition & concatenation for buffer Fred Drake <fdrake@acm.org> parents: 23319 diff changeset	416 slicing or concatenation, but do support repetition, and using
55423c1abcd1 Correct information on support for repietition & concatenation for buffer Fred Drake <fdrake@acm.org> parents: 23319 diff changeset	417 \code{in}, \code{not in}, \function{min()} or \function{max()} on them
55423c1abcd1 Correct information on support for repietition & concatenation for buffer Fred Drake <fdrake@acm.org> parents: 23319 diff changeset	418 is inefficient.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	419 \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	420
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	421 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	422 \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	423 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	424 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	425 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	426
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	427 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	428 (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	429 \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	430 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	431
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	432 \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	433 \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \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	434 \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	435 equal to \var{x}, else \code{1}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	436 \hline
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{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
19529 dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	438 \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(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
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	440 \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(2)}
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	441 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(2), (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	442 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	443 \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	444 \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	445 \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	446 \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	447 \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	448 \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	449 \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	450 \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	451 \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	452 \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	453 \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	454 \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	455 \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	456 \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	457
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	458 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	459 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	460
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	461 \begin{description}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	462 \item[(1)] Values of \var{n} less than \code{0} are treated as
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	463 \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	464 \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	465 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	466
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	467 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	468 >>> lists = [[]] * 3
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	469 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	470 [[], [], []]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	471 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	472 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	473 [[3], [3], [3]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	474 \end{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	475
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	476 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	477 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	478 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	479 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	480
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	481 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	482 >>> 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	483 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	484 >>> lists[1].append(5)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	485 >>> lists[2].append(7)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	486 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	487 [[3], [5], [7]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	488 \end{verbatim}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	489
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	490 \item[(2)] 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	491 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	492 \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	493 still \code{0}.
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	494
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	495 \item[(3)] 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	496 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	497 \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	498 \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	499 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	500 \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	501 \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	502
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	503
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	504 \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	505
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	506 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	507 objects support:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	508
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	509 \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	510 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	511 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	512
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	513 \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	514 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	515 using spaces.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	516 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	517
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	518 \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	519 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	520 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	521 \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	522 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	523
21332 fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	524 \begin{methoddesc}[string]{decode}{\optional{encoding\optional{, errors}}}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	525 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	526 \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	527 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	528 \code{'strict'}, meaning that encoding errors raise
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	529 \exception{ValueError}. Other possible values are \code{'ignore'} and
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	530 \code{replace'}.
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	531 \versionadded{2.2}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	532 \end{methoddesc}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	533
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	534 \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	535 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	536 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	537 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	538 \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	539 \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	540 \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	541 \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	542 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	543
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	544 \begin{methoddesc}[string]{endswith}{suffix\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	545 Return true if the string ends with the specified \var{suffix},
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	546 otherwise return false. With optional \var{start}, test beginning at
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	547 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	548 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	549
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	550 \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	551 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	552 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	553 characters is assumed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	554 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	555
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	556 \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	557 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	558 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	559 \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	560 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	561 not found.
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]{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	565 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	566 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	567 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	568
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	569 \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	570 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	571 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	572 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	573
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	574 \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	575 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	576 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	577 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	578
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	579 \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	580 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	581 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	582
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	583 \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	584 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	585 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	586 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	587
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	588 \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	589 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	590 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	591 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	592
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	593 \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	594 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	595 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	596 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	597 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	598
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	599 \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	600 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	601 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	602 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	603
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	604 \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	605 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	606 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	607 providing this method.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	608 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	609
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	610 \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	611 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	612 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	613 \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	614 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	615
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	616 \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	617 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	618 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	619
23147 dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	620 \begin{methoddesc}[string]{lstrip}{\optional{chars}}
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	621 Return a copy of the string with leading characters removed. If
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	622 \var{chars} is omitted or \code{None}, whitespace characters are
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	623 removed. If given and not \code{None}, \var{chars} must be a string;
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	624 the characters in the string will be stripped from the beginning of
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	625 the string this method is called on.
13933 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
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	628 \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	629 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	630 \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	631 \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	632 replaced.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	633 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	634
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	635 \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	636 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	637 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	638 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	639 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	640 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	641
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	642 \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	643 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	644 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	645 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	646
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	647 \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	648 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	649 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	650 \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	651 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	652
23147 dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	653 \begin{methoddesc}[string]{rstrip}{\optional{chars}}
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	654 Return a copy of the string with trailing characters removed. If
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	655 \var{chars} is omitted or \code{None}, whitespace characters are
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	656 removed. If given and not \code{None}, \var{chars} must be a string;
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	657 the characters in the string will be stripped from the end of the
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	658 string this method is called on.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	659 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	660
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	661 \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	662 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	663 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	664 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	665 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	666 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	667
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	668 \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	669 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	670 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	671 \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	672 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	673
23147 dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	674 \begin{methoddesc}[string]{startswith}{prefix\optional{,
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	675 start\optional{, end}}}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	676 Return true if string starts with the \var{prefix}, otherwise
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	677 return false. With optional \var{start}, test string beginning at
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	678 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	679 position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	680 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	681
23147 dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	682 \begin{methoddesc}[string]{strip}{\optional{chars}}
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	683 Return a copy of the string with leading and trailing characters
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	684 removed. If \var{chars} is omitted or \code{None}, whitespace
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	685 characters are removed. If given and not \code{None}, \var{chars}
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	686 must be a string; the characters in the string will be stripped from
dbf013cc3dee backport fdrake's patch: Anthony Baxter <anthonybaxter@gmail.com> parents: 22340 diff changeset	687 the both ends of the string this method is called on.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	688 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	689
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	690 \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	691 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	692 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	693 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	694
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	695 \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	696 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	697 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	698 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	699
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	700 \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	701 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	702 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	703 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	704 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	705 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	706
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	707 \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	708 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	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
23219 b08b51dce264 Backport the following changes: Walter Dörwald <walter@livinglogic.de> parents: 23147 diff changeset	711 \begin{methoddesc}[string]{zfill}{width}
b08b51dce264 Backport the following changes: Walter Dörwald <walter@livinglogic.de> parents: 23147 diff changeset	712 Return the numeric string left filled with zeros in a string
b08b51dce264 Backport the following changes: Walter Dörwald <walter@livinglogic.de> parents: 23147 diff changeset	713 of length \var{width}. The original string is returned if
b08b51dce264 Backport the following changes: Walter Dörwald <walter@livinglogic.de> parents: 23147 diff changeset	714 \var{width} is less than \code{len(\var{s})}.
b08b51dce264 Backport the following changes: Walter Dörwald <walter@livinglogic.de> parents: 23147 diff changeset	715 \end{methoddesc}
b08b51dce264 Backport the following changes: Walter Dörwald <walter@livinglogic.de> parents: 23147 diff changeset	716
13933 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 \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	719
21177 7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments Fred Drake <fdrake@acm.org> parents: 21163 diff changeset	720 \index{formatting, string (\%{})}
21572 812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	721 \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	722 \index{string!formatting}
21572 812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	723 \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	724 \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	725 \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	726 \index{\protect\%{} formatting}
21572 812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	727 \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	728
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	729 String and Unicode objects have one unique built-in operation: the
21572 812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	730 \code{\%} operator (modulo). This is also known as the string
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	731 \emph{formatting} or \emph{interpolation} operator. Given
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	732 \code{\var{format} \% \var{values}} (where \var{format} is a string or
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	733 Unicode object), \code{\%} conversion specifications in \var{format}
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	734 are replaced with zero or more elements of \var{values}. The effect
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	735 is similar to the using \cfunction{sprintf()} in the C language. If
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	736 \var{format} is a Unicode object, or if any of the objects being
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	737 converted using the \code{\%s} conversion are Unicode objects, the
812d1543ba08 Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	738 result will be a Unicode object as well.
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	739
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	740 If \var{format} requires a single argument, \var{values} may be a
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	741 single non-tuple object. \footnote{A tuple object in this case should
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	742 be a singleton.} Otherwise, \var{values} must be a tuple with
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	743 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	744 single mapping object (for example, a dictionary).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	745
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	746 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	747 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	748
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	749 \begin{enumerate}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	750 \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	751 specifier.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	752 \item Mapping key value (optional), consisting of an identifier in
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	753 parentheses (for example, \code{(somename)}).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	754 \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	755 conversion types.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	756 \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	757 \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	758 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	759 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	760 precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	761 \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	762 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	763 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	764 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	765 the precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	766 \item Length modifier (optional).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	767 \item Conversion type.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	768 \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	769
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	770 If the right argument is a dictionary (or any kind of mapping), then
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	771 the formats in the string \emph{must} have a parenthesized key into
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	772 that dictionary inserted immediately after the \character{\%}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	773 character, and each format formats the corresponding entry from the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	774 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	775
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	776 \begin{verbatim}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	777 >>> count = 2
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	778 >>> language = 'Python'
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	779 >>> print '%(language)s has %(count)03d quote types.' % vars()
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	780 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	781 \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	782
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	783 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	784 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	785
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	786 The conversion flag characters are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	787
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	788 \begin{tableii}{c\|l}{character}{Flag}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	789 \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	790 (where defined below).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	791 \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	792 \lineii{-}{The converted value is left adjusted (overrides
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	793 \character{-}).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	794 \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	795 (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	796 \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	797 precede the conversion (overrides a "space" flag).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	798 \end{tableii}
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 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	801 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	802
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	803 The conversion types are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	804
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	805 \begin{tableii}{c\|l}{character}{Conversion}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	806 \lineii{d}{Signed integer decimal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	807 \lineii{i}{Signed integer decimal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	808 \lineii{o}{Unsigned octal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	809 \lineii{u}{Unsigned decimal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	810 \lineii{x}{Unsigned hexidecimal (lowercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	811 \lineii{X}{Unsigned hexidecimal (uppercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	812 \lineii{e}{Floating point exponential format (lowercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	813 \lineii{E}{Floating point exponential format (uppercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	814 \lineii{f}{Floating point decimal format.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	815 \lineii{F}{Floating point decimal format.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	816 \lineii{g}{Same as \character{e} if exponent is greater than -4 or
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	817 less than precision, \character{f} otherwise.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	818 \lineii{G}{Same as \character{E} if exponent is greater than -4 or
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	819 less than precision, \character{F} otherwise.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	820 \lineii{c}{Single character (accepts integer or single character
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	821 string).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	822 \lineii{r}{String (converts any python object using
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	823 \function{repr()}).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	824 \lineii{s}{String (converts any python object using
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	825 \function{str()}).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	826 \lineii{\%}{No argument is converted, results in a \character{\%}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	827 character in the result. (The complete specification is
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	828 \code{\%\%}.)}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	829 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	830
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	831 % XXX Examples?
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	832
23319 a443e5e5ece7 Add a note about when the "%r" formatting code was added. Fred Drake <fdrake@acm.org> parents: 23219 diff changeset	833 (The \code{\%r} conversion was added in Python 2.0.)
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	834
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	835 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	836 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	837
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	838 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	839 \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	840 are replaced by \code{\%g} conversions.\footnote{
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	841 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	842 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	843 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	844 point values on a particular machine.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	845 } All other errors raise exceptions.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	846
21163 7b6879714b74 Make no assumption about how modules are built when referring to them; this Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	847 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	848 \refmodule{string}\refstmodindex{string} and
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	849 \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	850
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	851
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	852 \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	853
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	854 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	855 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	856 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	857 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	858 advantages.
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	859
18391 aadd99830531 Rip out the fancy behaviors of xrange that nobody uses: repeat, slice, Guido van Rossum <guido@python.org> parents: 18286 diff changeset	860 XRange objects have very little behavior: they only support indexing
aadd99830531 Rip out the fancy behaviors of xrange that nobody uses: repeat, slice, Guido van Rossum <guido@python.org> parents: 18286 diff changeset	861 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	862
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	863
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	864 \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	865
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	866 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	867 modification of the object.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	868 These operations would be supported by other 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	869 (when added to the language) as well.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	870 Strings and tuples are immutable sequence types and such objects cannot
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	871 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	872 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	873 \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	874 \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	875 \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	876
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	877 \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	878 \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	879 {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	880 \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	881 {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	882 \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	883 {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	884 \lineiii{\var{s}.append(\var{x})}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	885 {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	886 \lineiii{\var{s}.extend(\var{x})}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	887 {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	888 \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	889 {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	890 \lineiii{\var{s}.index(\var{x})}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	891 {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	892 \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	893 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	894 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	895 \lineiii{\var{s}.pop(\optional{\var{i}})}
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	896 {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	897 \lineiii{\var{s}.remove(\var{x})}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	898 {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	899 \lineiii{\var{s}.reverse()}
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	900 {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	901 \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	902 {sort the items of \var{s} in place}{(6), (7)}
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 \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	904 \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	905 \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	906 \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	907 \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	908 \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	909 \stindex{del}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	910 \withsubitem{(list method)}{
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	911 \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	912 \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	913 \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	914 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	915 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	916 \begin{description}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	917 \item[(1)] The C implementation of Python has historically accepted
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	918 multiple parameters and implicitly joined them into a tuple; this
13222 5dd381aeb23b Update version numbering from 1.6 to 2.0. Fred Drake <fdrake@acm.org> parents: 12223 diff changeset	919 no longer works in Python 2.0. Use of this misfeature has been
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	920 deprecated since Python 1.4.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	921
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	922 \item[(2)] Raises an exception when \var{x} is not a list object. The
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	923 \method{extend()} method is experimental and not supported by
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	924 mutable sequence types other than lists.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	925
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	926 \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	927 \var{s}.
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	928
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	929 \item[(4)] When a negative index is passed as the first parameter to
5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	930 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	931 sequence.
5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	932
5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	933 \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	934 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	935 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	936
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	937 \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	938 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	939 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	940 the sorted or reversed list.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	941
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	942 \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	943 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	944 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	945 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	946 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	947 down considerably; e.g. to sort a list in reverse order it is much
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	948 faster to use calls to the methods \method{sort()} and
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	949 \method{reverse()} than to use the built-in function
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	950 \function{sort()} with a comparison function that reverses the
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	951 ordering of the elements.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	952 \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	953
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	954
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	955 \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	956 \obindex{mapping}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	957 \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	958
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	959 A \dfn{mapping} object maps values of one type (the key type) to
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	960 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	961 only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	962 almost arbitrary values. The only types of values not acceptable as
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	963 keys are values containing lists or dictionaries or other mutable
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	964 types that are compared by value rather than by 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	965 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	966 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	967 \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	968 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	969
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	970 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	971 \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	972 \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	973 \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	974
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	975 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	976 \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	977 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	978 \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	979 \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	980 \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	981 \bifuncindex{len}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	982 \withsubitem{(dictionary method)}{
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	983 \ttindex{clear()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	984 \ttindex{copy()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	985 \ttindex{has_key()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	986 \ttindex{items()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	987 \ttindex{keys()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	988 \ttindex{update()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	989 \ttindex{values()}
23461 e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693. Raymond Hettinger <python@rcn.com> parents: 23355 diff changeset	990 \ttindex{get()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693. Raymond Hettinger <python@rcn.com> parents: 23355 diff changeset	991 \ttindex{setdefault()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693. Raymond Hettinger <python@rcn.com> parents: 23355 diff changeset	992 \ttindex{popitem()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693. Raymond Hettinger <python@rcn.com> parents: 23355 diff changeset	993 \ttindex{iteritems()}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693. Raymond Hettinger <python@rcn.com> parents: 23355 diff changeset	994 \ttindex{iterkeys)}
e43aafffb03c Added missing index entries for mapping methods. Closes patch #548693. Raymond Hettinger <python@rcn.com> parents: 23355 diff changeset	995 \ttindex{itervalues()}}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	996
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	997 \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	998 \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	999 \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	1000 \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	1001 {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	1002 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1003 \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	1004 {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	1005 {(1)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1006 \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	1007 \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	1008 \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	1009 {\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	1010 {}
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	1011 \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	1012 {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	1013 {(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	1014 \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	1015 {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	1016 {(2)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1017 \lineiii{\var{a}.items()}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1018 {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	1019 {(3)}
18085 7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these Fred Drake <fdrake@acm.org> parents: 17966 diff changeset	1020 \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	1021 \lineiii{\var{a}.update(\var{b})}
13764 fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about Fred Drake <fdrake@acm.org> parents: 13222 diff changeset	1022 {\code{for k in \var{b}.keys(): \var{a}[k] = \var{b}[k]}}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1023 {}
18085 7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these Fred Drake <fdrake@acm.org> parents: 17966 diff changeset	1024 \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	1025 \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	1026 {\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	1027 else \var{x}}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1028 {(4)}
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1029 \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	1030 {\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	1031 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	1032 {(5)}
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1033 \lineiii{\var{a}.popitem()}
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1034 {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	1035 {(6)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1036 \lineiii{\var{a}.iteritems()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1037 {return an iterator over (\var{key}, \var{value}) pairs}
24903 ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1038 {(2), (3)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1039 \lineiii{\var{a}.iterkeys()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1040 {return an iterator over the mapping's keys}
24903 ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1041 {(2), (3)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1042 \lineiii{\var{a}.itervalues()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1043 {return an iterator over the mapping's values}
24903 ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1044 {(2), (3)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1045 \end{tableiii}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1046
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1047 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1048 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1049 \begin{description}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1050 \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	1051 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	1052
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1053 \item[(2)] \versionadded{2.2}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1054
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1055 \item[(3)] Keys and values are listed in random order. If
24903 ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1056 \method{items()}, \method{keys()}, \method{values()},
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1057 \method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1058 are called with no intervening modifications to the dictionary, the
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1059 lists will directly correspond. This allows the creation of
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1060 \code{(\var{value}, \var{key})} pairs using \function{zip()}:
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1061 \samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1062 relationship holds for the \method{iterkeys()} and
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1063 \method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1064 \var{a}.iterkeys())} provides the same value for \code{pairs}.
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1065 Another way to create the same list is \samp{pairs = [(v, k) for (k,
ecd4ada252bc Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24632 diff changeset	1066 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	1067
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1068 \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	1069 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	1070 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	1071
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1072 \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	1073 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	1074 the dictionary as the value of \var{k}.
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1075
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1076 \item[(6)] \function{popitem()} is useful to destructively iterate
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1077 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	1078 \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	1079
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1080
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1081 \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	1082 \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	1083
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1084 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	1085 package and can be created with the built-in constructor
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1086 \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	1087 \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	1088 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	1089 alias for \function{file()}.}
37b8d92e12f5 Mention the new file() builtin in the section on file objects. Tim Peters <tim.peters@gmail.com> parents: 20701 diff changeset	1090 They 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	1091 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	1092 \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	1093 \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	1094 \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	1095 \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	1096
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1097 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	1098 \exception{IOError} is raised. This includes situations where the
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1099 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	1100 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	1101
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1102 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	1103
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1104
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1105 \begin{methoddesc}[file]{close}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1106 Close the file. A closed file cannot be read or written anymore.
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1107 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	1108 \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	1109 \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	1110 \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	1111
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1112 \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	1113 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	1114 \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	1115 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	1116 \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	1117
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1118 \begin{methoddesc}[file]{isatty}{}
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1119 Return true if the file is connected to a tty(-like) device, else
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1120 false. \note{If a file-like object is not associated
376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1121 with a real file, this method should \emph{not} be implemented.}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1122 \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	1123
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1124 \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	1125 \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	1126 \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	1127 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	1128 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	1129 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	1130 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	1131 \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	1132 \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	1133 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	1134 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	1135 \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	1136
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1137 \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	1138 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	1139 \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	1140 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	1141 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	1142 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	1143 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	1144 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	1145 C function \cfunction{fread()} more than once in an effort to
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1146 acquire as close to \var{size} bytes as possible.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1147 \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	1148
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1149 \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	1150 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	1151 kept in the string\footnote{
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1152 The advantage of leaving the newline on is that an empty string
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1153 can be returned to mean \EOF{} without being ambiguous. Another
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1154 advantage is that (in cases where it might matter, for example. if you
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1155 want to make an exact copy of a file while scanning its lines)
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1156 you can 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	1157 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	1158 } (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	1159 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	1160 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	1161 newline) and an incomplete line may be returned.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1162 An empty string is returned when \EOF{} is hit
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1163 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	1164 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	1165 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	1166 \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	1167
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1168 \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	1169 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	1170 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	1171 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	1172 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	1173 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	1174 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	1175 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	1176 \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	1177
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1178 \begin{methoddesc}[file]{xreadlines}{}
17612 c19d6db6e99b Only document <file>.xreadlines() once; added version annotation. Fred Drake <fdrake@acm.org> parents: 17603 diff changeset	1179 Equivalent to
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation. Fred Drake <fdrake@acm.org> parents: 17603 diff changeset	1180 \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation. Fred Drake <fdrake@acm.org> parents: 17603 diff changeset	1181 (See the \refmodule{xreadlines} module for more information.)
c19d6db6e99b Only document <file>.xreadlines() once; added version annotation. Fred Drake <fdrake@acm.org> parents: 17603 diff changeset	1182 \versionadded{2.1}
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1183 \end{methoddesc}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1184
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1185 \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	1186 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	1187 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	1188 (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	1189 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	1190 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	1191 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	1192 \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	1193 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	1194 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	1195 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	1196 \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	1197
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1198 \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	1199 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	1200 \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	1201 \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	1202
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1203 \begin{methoddesc}[file]{truncate}{\optional{size}}
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1204 Truncate the file's size. If the optional \var{size} argument
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1205 present, the file is truncated to (at most) that size. The size
22340 7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1206 defaults to the current position. Availability of this function
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1207 depends on the operating system version (for example, not all
7ecc49117d7e Take Tim's work on file.truncate out of 2.2.1 again. Michael W. Hudson <mwh@python.net> parents: 22337 diff changeset	1208 \UNIX{} versions support this operation).
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	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]{write}{str}
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1212 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	1213 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	1214 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	1215 \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	1216
20045 7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1217 \begin{methoddesc}[file]{writelines}{sequence}
7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1218 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	1219 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	1220 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	1221 (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	1222 \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	1223 \end{methoddesc}
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1224
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1225
20031 e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1226 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	1227 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	1228 \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	1229
e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1230
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1231 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	1232 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	1233 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	1234
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1235 \begin{memberdesc}[file]{closed}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1236 Boolean indicating the current state of the file object. This is a
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1237 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	1238 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	1239 \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	1240
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1241 \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	1242 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	1243 \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	1244 \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	1245 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	1246 \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	1247
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1248 \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	1249 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	1250 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	1251 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	1252 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	1253 \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	1254
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1255 \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	1256 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	1257 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	1258 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	1259 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	1260 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	1261 (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	1262 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	1263 \member{softspace} attribute.
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1264 \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	1265 \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	1266 \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	1267 \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	1268
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1269
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1270 \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	1271
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1272 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	1273 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	1274
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1275
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1276 \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	1277
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1278 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	1279 \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	1280 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	1281 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	1282 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	1283 \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	1284 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	1285 \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	1286
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1287 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	1288 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	1289 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	1290 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	1291 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	1292 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	1293 \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	1294
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1295 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	1296 \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	1297 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	1298 '/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	1299
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1300
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1301 \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	1302 \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	1303
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1304 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	1305 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	1306
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1307
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1308 \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	1309
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1310 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	1311 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	1312 \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	1313
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1314 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	1315 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	1316 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	1317 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	1318
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1319 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	1320 \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	1321 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	1322 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	1323 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	1324 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	1325
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1326 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	1327 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	1328 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	1329 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	1330 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	1331 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	1332
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1333 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	1334 (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	1335 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	1336 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	1337 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	1338
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1339 \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	1340 \obindex{method}
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 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	1343 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	1344 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	1345 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	1346
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1347 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	1348 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	1349 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	1350 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	1351 \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	1352 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	1353 \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	1354
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1355 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	1356 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	1357 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	1358 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	1359 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	1360 \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	1361 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	1362
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1363 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	1364 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	1365 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	1366 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	1367 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	1368 \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	1369 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	1370
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1371 \begin{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1372 class C:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1373 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	1374 pass
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 c = C()
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1377 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	1378 \end{verbatim}
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 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	1381 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1382
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1383
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1384 \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	1385 \obindex{code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1386
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1387 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	1388 ``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	1389 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	1390 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	1391 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	1392 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	1393 attribute.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1394 \bifuncindex{compile}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1395 \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	1396
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1397 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	1398 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	1399 \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	1400 \stindex{exec}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1401 \bifuncindex{eval}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1402
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1403 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	1404 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1405
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1406
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1407 \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	1408
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1409 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	1410 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	1411 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	1412 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	1413 \bifuncindex{type}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1414 \refstmodindex{types}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1415
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1416 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	1417
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1418
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1419 \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	1420
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1421 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	1422 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	1423 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	1424
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1425 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	1426
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1427
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1428 \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	1429
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1430 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	1431 \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	1432 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	1433 \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	1434
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1435 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	1436
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1437
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1438 \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	1439
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1440 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	1441 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	1442 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	1443
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1444
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1445 \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	1446
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1447 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	1448 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	1449
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1450 \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	1451 A dictionary or other mapping object used to store an
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1452 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	1453 \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	1454
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1455 \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	1456 \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	1457 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	1458 \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	1459
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1460 \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	1461 \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	1462 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	1463 \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	1464
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1465 \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	1466 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	1467 \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	1468
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1469 \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	1470 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	1471 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	1472 \end{memberdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstdtypes.tex @ 25838:8540887bcec6 2.2