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

annotate Doc/lib/libstdtypes.tex @ 17581:c1937faabb23 2.1

Added support for optional explanation parameter to the \versionadded macro. Refactored do_cmd_versionadded() and do_cmd_versionchanged() to do most of the work in a helper function, with the do_cmd_*() wrappers just supplying a portion of the replacement text.

author	Fred Drake <fdrake@acm.org>
date	Wed, 18 Apr 2001 17:29:14 +0000
parents	68bd96e426e3
children	4d7fb24fe795 bf94af396b1e

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}
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	31 \withsubitem{(Built-in object)}{\ttindex{None}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	32
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	33 \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	34 \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	35
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	36 \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	37
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	38 \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	39
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	40 \item instances of user-defined classes, if the class defines a
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	41 \method{__nonzero__()} or \method{__len__()} method, when that
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	42 method returns zero.\footnote{Additional information on these
14485 ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	43 special methods may be found in the \citetitle[../ref/ref.html]{Python
ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	44 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	45
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	46 \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	47
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	48 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	49 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	50 \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	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 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	53 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	54 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	55 \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	56 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	57
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	58
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	59 \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	60
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	61 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	62 \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	63
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	64 \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	65 \lineiii{\var{x} or \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	66 {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	67 \lineiii{\var{x} and \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	68 {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	69 \hline
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	70 \lineiii{not \var{x}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	71 {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	72 \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	73 \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	74 \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	75 \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	76
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	77 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	78 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	79
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	80 \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	81
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	82 \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	83 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	84
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	85 \item[(2)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	86 \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	87 \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	88 \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	89
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	90 \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	91
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	92
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	93 \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	94
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	95 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	96 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	97 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	98 \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	99 \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	100 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	101 \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	102 \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	103
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	104 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	105
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	106 \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	107 \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	108 \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	109 \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	110 \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	111 \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	112 \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	113 \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	114 \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	115 \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	116 \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	117 \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	118 \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	119 \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	120 \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	121
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	122 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	123 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	124
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	125 \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	126
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	127 \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	128 \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	129 (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	130 \index{ABC language@\ABC{} language}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	131 \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	132 \indexii{C}{language}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	133 \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	134
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	135 \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	136
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	137 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	138 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	139 (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	140 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	141 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	142 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	143 consistently.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	144 \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	145 \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	146
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	147 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	148 \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	149 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	150 \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	151 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	152
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	153 \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	154 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	155 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	156
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	157 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	158 \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	159 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	160
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	161
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	162 \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	163
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	164 There are four numeric types: \dfn{plain integers}, \dfn{long integers},
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	165 \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	166 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	167 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	168 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	169 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	170 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	171 working with.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	172 \obindex{numeric}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	173 \obindex{integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	174 \obindex{long integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	175 \obindex{floating point}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	176 \obindex{complex number}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	177 \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	178
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	179 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	180 implemented using \ctype{double} in C. To extract these parts from
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	181 a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
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 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	184 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	185 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	186 \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	187 (\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	188 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	189 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	190 \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	191 \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	192 \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	193 \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	194 \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	195 \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	196 \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	197 \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	198
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	199 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	200 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	201 ``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	202 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	203 smaller than complex.
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	204 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	205 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	206 to \code{[1.0, 2.0]}, and similar for tuples.
fa2e3d06c790 Minor markup nit. Fred Drake <fdrake@acm.org> parents: 10968 diff changeset	207 } The functions \function{int()}, \function{long()}, \function{float()},
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	208 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	209 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	210 \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	211 \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	212 \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	213 \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	214 \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	215
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	216 All numeric types support the following operations, sorted by
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	217 ascending priority (operations in the same box 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	218 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	219 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	220
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	221 \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	222 \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	223 \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	224 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	225 \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	226 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
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}}{remainder of \code{\var{x} / \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{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	230 \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	231 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	232 \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	233 \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	234 \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	235 \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	236 \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	237 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{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	238 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)}
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{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	240 \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	241 \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	242 \indexiii{operations on}{numeric}{types}
10147 3ac7f0066375 Document <complex #>.conjugate(). Fred Drake <fdrake@acm.org> parents: 9558 diff changeset	243 \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	244
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	245 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	246 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	247 \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	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 \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	250 For (plain or long) integer division, the result is an integer.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	251 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	252 (-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	253 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	254 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	255 \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	256 \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	257
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	258 \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	259 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	260 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	261 \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	262 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	263 \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	264 \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	265 \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	266
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	267 \item[(3)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	268 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	269 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	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 \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	272 % 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	273
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	274 \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	275 \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	276
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	277 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	278 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	279 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	280 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	281
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	282 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	283 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	284 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	285 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	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 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	288 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	289
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	290 \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	291 \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	292 \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	293 \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	294 \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	295 \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	296 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	297 \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	298 \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	299 \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	300 \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	301 \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	302 \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	303
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	304 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	305 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	306 \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	307 \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	308 \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	309 \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	310 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	311 \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	312 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	313 \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	314
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	315
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	316 \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	317
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	318 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	319 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	320
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	321 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	322 \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	323 \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	324 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	325 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	326 \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	327 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	328 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	329 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	330 enclosing parentheses, e.g., \code{a, b, c} or \code{()}. A single
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	331 item tuple must have a trailing comma, e.g., \code{(d,)}. Buffers are
14710 ac6df0494c58 Fixed a number of small problems reported by Detlef Lannert Fred Drake <fdrake@acm.org> parents: 14705 diff changeset	332 not directly supported by Python syntax, but can be created by calling the
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	333 builtin function \function{buffer()}.\bifuncindex{buffer} XRanges
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	334 objects are similar to buffers in that there is no specific syntax to
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	335 create them, but they are created using the \function{xrange()}
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	336 function.\bifuncindex{xrange}
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	337 \obindex{sequence}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	338 \obindex{string}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	339 \obindex{Unicode}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	340 \obindex{buffer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	341 \obindex{tuple}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	342 \obindex{list}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	343 \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	344
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	345 Sequence types support the following operations. The \samp{in} and
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	346 \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	347 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	348 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	349 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	350
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	351 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	352 (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	353 \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	354 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	355
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	356 \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	357 \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	358 \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	359 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	360 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	361 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	362 \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} 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	363 \hline
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	364 \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	365 \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	366 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	367 \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	368 \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	369 \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	370 \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	371 \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	372 \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	373 \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	374 \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	375 \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	376 \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	377 \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	378 \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	379 \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	380 \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	381
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	382 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	383 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	384
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	385 \begin{description}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	386 \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	387 \code{0} (which yields an empty sequence of the same type as
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	388 \var{s}).
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	389
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	390 \item[(2)] If \var{i} or \var{j} is negative, the index is relative to
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	391 the end of the string, i.e., \code{len(\var{s}) + \var{i}} or
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	392 \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	393 still \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	394
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	395 \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	396 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	397 \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	398 \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	399 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	400 \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	401 \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	402
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	403
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	404 \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	405
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	406 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	407 objects support:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	408
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	409 \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	410 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	411 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	412
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	413 \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	414 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	415 using spaces.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	416 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	417
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	418 \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	419 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	420 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	421 \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	422 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	423
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	424 \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	425 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	426 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	427 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	428 \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	429 \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	430 \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	431 \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	432 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	433
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	434 \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	435 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	436 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	437 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	438 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	439
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	440 \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	441 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	442 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	443 characters is assumed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	444 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	445
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	446 \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	447 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	448 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	449 \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	450 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	451 not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	452 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	453
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	454 \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	455 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	456 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	457 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	458
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	459 \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	460 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	461 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	462 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	463
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	464 \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	465 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	466 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	467 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	468
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	469 \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	470 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	471 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	472
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	473 \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	474 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	475 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	476 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	477
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	478 \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	479 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	480 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	481 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	482
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	483 \begin{methoddesc}[string]{istitle}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	484 Return true if the string is a titlecased string, i.e.\ uppercase
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	485 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	486 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	487 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	488
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	489 \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	490 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	491 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	492 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	493
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	494 \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	495 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	496 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	497 providing this method.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	498 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	499
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	500 \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	501 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	502 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	503 \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	504 \end{methoddesc}
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 \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	507 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	508 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	509
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	510 \begin{methoddesc}[string]{lstrip}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	511 Return a copy of the string with leading whitespace removed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	512 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	513
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	514 \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	515 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	516 \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	517 \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	518 replaced.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	519 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	520
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	521 \begin{methoddesc}[string]{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	522 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	523 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	524 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	525 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	526 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	527
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	528 \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	529 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	530 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	531 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	532
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	533 \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	534 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	535 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	536 \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	537 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	538
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	539 \begin{methoddesc}[string]{rstrip}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	540 Return a copy of the string with trailing whitespace removed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	541 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	542
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	543 \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	544 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	545 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	546 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	547 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	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]{splitlines}{\optional{keepends}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	551 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	552 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	553 \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	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]{startswith}{prefix\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 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	558 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	559 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	560 position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	561 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	562
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	563 \begin{methoddesc}[string]{strip}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	564 Return a copy of the string with leading and trailing whitespace
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	565 removed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	566 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	567
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	568 \begin{methoddesc}[string]{swapcase}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	569 Return a copy of the string with 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	570 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	571 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	572
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	573 \begin{methoddesc}[string]{title}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	574 Return a titlecased version of, i.e.\ words start with uppercase
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	575 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	576 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	577
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	578 \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	579 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	580 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	581 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	582 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	583 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	584
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	585 \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	586 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	587 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	588
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	589
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	590 \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	591
14552 a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	592 \index{formatting, string}
a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	593 \index{string!formatting}
a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	594 \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	595 \index{sprintf-style formatting}
a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	596
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	597 String and Unicode objects have one unique built-in operation: the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	598 \code{\%} operator (modulo). Given \code{\var{format} \%
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	599 \var{values}} (where \var{format} is a string or Unicode object),
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	600 \code{\%} conversion specifications in \var{format} are replaced with
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	601 zero or more elements of \var{values}. The effect is similar to the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	602 using \cfunction{sprintf()} in the C language. If \var{format} is a
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	603 Unicode object, or if any of the objects being converted using the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	604 \code{\%s} conversion are Unicode objects, the result will be a
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	605 Unicode object as well.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	606
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	607 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	608 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	609 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	610 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	611 single mapping object (for example, a dictionary).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	612
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	613 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	614 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	615
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	616 \begin{enumerate}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	617 \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	618 specifier.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	619 \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	620 parentheses (for example, \code{(somename)}).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	621 \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	622 conversion types.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	623 \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	624 \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	625 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	626 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	627 precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	628 \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	629 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	630 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	631 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	632 the precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	633 \item Length modifier (optional).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	634 \item Conversion type.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	635 \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	636
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	637 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	638 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	639 that dictionary inserted immediately after the \character{\%}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	640 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	641 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	642
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	643 \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	644 >>> 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	645 >>> 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	646 >>> 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	647 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	648 \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	649
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	650 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	651 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	652
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	653 The conversion flag characters are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	654
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	655 \begin{tableii}{c\|l}{character}{Flag}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	656 \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	657 (where defined below).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	658 \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	659 \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	660 \character{-}).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	661 \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	662 (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	663 \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	664 precede the conversion (overrides a "space" flag).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	665 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	666
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	667 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	668 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	669
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	670 The conversion types are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	671
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	672 \begin{tableii}{c\|l}{character}{Conversion}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	673 \lineii{d}{Signed integer decimal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	674 \lineii{i}{Signed integer decimal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	675 \lineii{o}{Unsigned octal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	676 \lineii{u}{Unsigned decimal.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	677 \lineii{x}{Unsigned hexidecimal (lowercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	678 \lineii{X}{Unsigned hexidecimal (uppercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	679 \lineii{e}{Floating point exponential format (lowercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	680 \lineii{E}{Floating point exponential format (uppercase).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	681 \lineii{f}{Floating point decimal format.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	682 \lineii{F}{Floating point decimal format.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	683 \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	684 less than precision, \character{f} otherwise.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	685 \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	686 less than precision, \character{F} otherwise.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	687 \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	688 string).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	689 \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	690 \function{repr()}).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	691 \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	692 \function{str()}).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	693 \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	694 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	695 \code{\%\%}.)}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	696 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	697
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	698 % XXX Examples?
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	699
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	700
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	701 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	702 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	703
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	704 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	705 \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	706 are replaced by \code{\%g} conversions.\footnote{
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	707 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	708 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	709 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	710 point values on a particular machine.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	711 } All other errors raise exceptions.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	712
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	713 Additional string operations are defined in standard module
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	714 \refmodule{string} and in built-in module \refmodule{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	715 \refstmodindex{string}
8882 b28b84e6a429 re is standard, not built-in. Fred Drake <fdrake@acm.org> parents: 8734 diff changeset	716 \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	717
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	718
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	719 \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	720
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	721 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	722 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	723 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	724 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	725 advantages.
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	726
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	727 XRange objects behave like tuples, and offer a single method:
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	728
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	729 \begin{methoddesc}[xrange]{tolist}{}
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	730 Return a list object which represents the same values as the xrange
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	731 object.
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	732 \end{methoddesc}
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	733
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	734
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	735 \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	736
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	737 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	738 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	739 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	740 (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	741 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	742 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	743 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	744 \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	745 \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	746 \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	747
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	748 \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	749 \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	750 {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	751 \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	752 {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	753 \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	754 {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	755 \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	756 {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	757 \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	758 {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	759 \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	760 {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	761 \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	762 {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	763 \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	764 {same as \code{\var{s}[\var{i}:\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	765 if \code{\var{i} >= 0}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	766 \lineiii{\var{s}.pop(\optional{\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	767 {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(4)}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	768 \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	769 {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	770 \lineiii{\var{s}.reverse()}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	771 {reverses the items of \var{s} in place}{(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	772 \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	773 {sort the items of \var{s} in place}{(5), (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	774 \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	775 \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	776 \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	777 \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	778 \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	779 \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	780 \stindex{del}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	781 \withsubitem{(list method)}{
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	782 \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	783 \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	784 \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	785 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	786 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	787 \begin{description}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	788 \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	789 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	790 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	791 deprecated since Python 1.4.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	792
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	793 \item[(2)] Raises an exception when \var{x} is not a list object. The
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	794 \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	795 mutable sequence types other than lists.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	796
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	797 \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	798 \var{s}.
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	799
13780 e20fe0052680 fixing a minor spelling mistake Peter Schneider-Kamp <nowonder@nowonder.de> parents: 13777 diff changeset	800 \item[(4)] 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	801 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	802 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	803
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	804 \item[(5)] The \method{sort()} and \method{reverse()} methods modify the
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	805 list in place for economy of space when sorting or reversing a large
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	806 list. They don't return the sorted or reversed list to remind you
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	807 of this side effect.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	808
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	809 \item[(6)] 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	810 specifying a comparison function of two arguments (list items) which
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	811 should return \code{-1}, \code{0} or \code{1} depending on whether
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	812 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	813 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	814 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	815 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	816 \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	817 \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	818 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	819 \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	820
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	821
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	822 \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	823 \obindex{mapping}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	824 \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	825
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	826 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	827 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	828 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	829 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	830 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	831 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	832 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	833 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	834 \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	835 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	836
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	837 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	838 \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	839 \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	840 \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	841
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	842 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	843 \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	844 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	845 \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	846 \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	847 \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	848 \bifuncindex{len}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	849 \withsubitem{(dictionary method)}{
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	850 \ttindex{clear()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	851 \ttindex{copy()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	852 \ttindex{has_key()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	853 \ttindex{items()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	854 \ttindex{keys()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	855 \ttindex{update()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	856 \ttindex{values()}
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	857 \ttindex{get()}}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	858
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	859 \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	860 \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	861 \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	862 \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	863 {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	864 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	865 \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	866 {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	867 {(1)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	868 \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	869 \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	870 \lineiii{\var{a}.has_key(\var{k})}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	871 {\code{1} if \var{a} has a key \var{k}, else \code{0}}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	872 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	873 \lineiii{\var{a}.items()}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	874 {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	875 {(2)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	876 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	877 \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	878 {\code{for k in \var{b}.keys(): \var{a}[k] = \var{b}[k]}}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	879 {(3)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	880 \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	881 \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	882 {\code{\var{a}[\var{k}]} if \code{\var{a}.has_key(\var{k})},
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	883 else \var{x}}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	884 {(4)}
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	885 \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	886 {\code{\var{a}[\var{k}]} if \code{\var{a}.has_key(\var{k})},
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	887 else \var{x} (also setting it)}
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	888 {(5)}
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	889 \lineiii{\var{a}.popitem()}
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	890 {remove and return an arbitrary (\var{key}, \var{value}) pair}
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	891 {(6)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	892 \end{tableiii}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	893
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	894 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	895 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	896 \begin{description}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	897 \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	898 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	899
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	900 \item[(2)] Keys and values are listed in random order. If
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	901 \method{keys()} and \method{values()} are called with no intervening
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	902 modifications to the dictionary, the two lists will directly
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	903 correspond. This allows the creation of \code{(\var{value},
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	904 \var{key})} pairs using \function{map()}: \samp{pairs = map(None,
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	905 \var{a}.values(), \var{a}.keys())}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	906
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	907 \item[(3)] \var{b} must be of the same type as \var{a}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	908
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	909 \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	910 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	911 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	912
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	913 \item[(5)] \function{setdefault()} is like \function{get()}, except
77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	914 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	915 the dictionary as the value of \var{k}.
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	916
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	917 \item[(6)] \function{popitem()} is useful to destructively iterate
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	918 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	919 \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	920
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	921
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	922 \subsection{Other Built-in Types \label{typesother}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	923
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	924 The interpreter supports several other kinds of objects.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	925 Most of these support only one or two operations.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	926
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	927
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	928 \subsubsection{Modules \label{typesmodules}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	929
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	930 The only special operation on a module is attribute access:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	931 \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	932 accesses a name defined in \var{m}'s symbol table. Module attributes
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	933 can be assigned to. (Note that the \keyword{import} statement is not,
9034 182c9cbdf053 spoking --> speaking Fred Drake <fdrake@acm.org> parents: 8882 diff changeset	934 strictly speaking, an operation on a module object; \code{import
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	935 \var{foo}} does not require a module object named \var{foo} to exist,
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	936 rather it requires an (external) \emph{definition} for a module named
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	937 \var{foo} somewhere.)
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	938
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	939 A special member of every module is \member{__dict__}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	940 This is the dictionary containing the module's symbol table.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	941 Modifying this dictionary will actually change the module's symbol
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	942 table, but direct assignment to the \member{__dict__} attribute is not
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 possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	944 defines \code{\var{m}.a} to be \code{1}, but you can't write
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	945 \code{\var{m}.__dict__ = \{\}}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	946
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	947 Modules built into the interpreter are written like this:
f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	948 \code{<module 'sys' (built-in)>}. If loaded from a file, they are
14557 a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14552 diff changeset	949 written as \code{<module 'os' from
a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14552 diff changeset	950 '/usr/local/lib/python\shortversion/os.pyc'>}.
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	951
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
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	953 \subsubsection{Classes and Class Instances \label{typesobjects}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	954 \nodename{Classes and Instances}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	955
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	956 See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	957 Reference Manual} for these.
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
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	959
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	960 \subsubsection{Functions \label{typesfunctions}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	961
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	962 Function objects are created by function definitions. The only
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	963 operation on a function object is to call it:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	964 \code{\var{func}(\var{argument-list})}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	965
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	966 There are really two flavors of function objects: built-in functions
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	967 and user-defined functions. Both support the same operation (to call
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	968 the function), but the implementation is different, hence the
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	969 different object types.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	970
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	971 The implementation adds two special read-only attributes:
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{\var{f}.func_code} is a function's \dfn{code
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	973 object}\obindex{code} (see below) and \code{\var{f}.func_globals} is
14520 addaba991077 When referring to namespaces, always say "namespaces" instead of Fred Drake <fdrake@acm.org> parents: 14485 diff changeset	974 the dictionary used as the function's global namespace (this is the
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	975 same as \code{\var{m}.__dict__} where \var{m} is the module in which
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	976 the function \var{f} was defined).
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	977
15892 8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	978 Function objects also support getting and setting arbitrary
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	979 attributes, which can be used to, e.g. attach metadata to functions.
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	980 Regular attribute dot-notation is used to get and set such
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	981 attributes. \emph{Note that the current implementation only supports
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	982 function attributes on functions written in Python. Function
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	983 attributes on built-ins may be supported in the future.}
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	984
16778 68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	985 Functions have another special attribute \code{\var{f}.__dict__}
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	986 (a.k.a. \code{\var{f}.func_dict}) which contains the namespace used to
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	987 support function attributes. \code{__dict__} can be accessed
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	988 directly, set to a dictionary object, or \code{None}. It can also be
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	989 deleted (but the following two lines are equivalent):
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	990
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	991 \begin{verbatim}
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	992 del func.__dict__
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	993 func.__dict__ = None
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	994 \end{verbatim}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	995
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	996 \subsubsection{Methods \label{typesmethods}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	997 \obindex{method}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	998
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	999 Methods are functions that are called using the attribute notation.
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1000 There are two flavors: built-in methods (such as \method{append()} 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	1001 lists) and class instance methods. Built-in methods are described
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1002 with the types that support them.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1003
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1004 The implementation adds two special read-only attributes to class
9034 182c9cbdf053 spoking --> speaking Fred Drake <fdrake@acm.org> parents: 8882 diff changeset	1005 instance methods: \code{\var{m}.im_self} is the object on which the
182c9cbdf053 spoking --> speaking Fred Drake <fdrake@acm.org> parents: 8882 diff changeset	1006 method operates, and \code{\var{m}.im_func} is the function
182c9cbdf053 spoking --> speaking Fred Drake <fdrake@acm.org> parents: 8882 diff changeset	1007 implementing the method. Calling \code{\var{m}(\var{arg-1},
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1008 \var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
9034 182c9cbdf053 spoking --> speaking Fred Drake <fdrake@acm.org> parents: 8882 diff changeset	1009 calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1010 \var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1011
15892 8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1012 Class instance methods are either \emph{bound} or \emph{unbound},
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1013 referring to whether the method was accessed through an instance or a
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1014 class, respectively. When a method is unbound, its \code{im_self}
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1015 attribute will be \code{None} and if called, an explicit \code{self}
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1016 object must be passed as the first argument. In this case,
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1017 \code{self} must be an instance of the unbound method's class (or a
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1018 subclass of that class), otherwise a \code{TypeError} is raised.
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1019
16778 68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1020 Like function objects, methods objects support getting
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1021 arbitrary attributes. However, since method attributes are actually
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1022 stored on the underlying function object (i.e. \code{meth.im_func}),
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1023 setting method attributes on either bound or unbound methods is
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1024 disallowed. Attempting to set a method attribute results in a
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1025 \code{TypeError} being raised. In order to set a method attribute,
68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1026 you need to explicitly set it on the underlying function object:
15892 8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1027
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1028 \begin{verbatim}
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1029 class C:
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1030 def method(self):
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1031 pass
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1032
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1033 c = C()
16778 68bd96e426e3 Updates to the semantics of function and method attributes. Barry Warsaw <barry@python.org> parents: 16285 diff changeset	1034 c.method.im_func.whoami = 'my name is c'
15892 8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1035 \end{verbatim}
8ef31a039a96 Document function attributes for both the function type and the method Barry Warsaw <barry@python.org> parents: 15789 diff changeset	1036
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1037 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1038 information.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1039
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1040
bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1041 \subsubsection{Code Objects \label{bltin-code-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	1042 \obindex{code}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1043
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1044 Code objects are used by the implementation to represent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1045 ``pseudo-compiled'' executable Python code such as a function body.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1046 They differ from function objects because they don't contain a
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1047 reference to their global execution environment. Code objects are
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1048 returned by the built-in \function{compile()} function and can be
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1049 extracted from function objects through their \member{func_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	1050 attribute.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1051 \bifuncindex{compile}
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	1052 \withsubitem{(function object attribute)}{\ttindex{func_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	1053
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1054 A code object can be executed or evaluated by passing it (instead of a
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1055 source string) to the \keyword{exec} statement or the built-in
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1056 \function{eval()} function.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1057 \stindex{exec}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1058 \bifuncindex{eval}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1059
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1060 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1061 information.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1062
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1063
bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1064 \subsubsection{Type Objects \label{bltin-type-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	1065
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1066 Type objects represent the various object types. An object's type is
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1067 accessed by the built-in function \function{type()}. There are no special
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1068 operations on types. The standard module \module{types} defines names
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1069 for all standard 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	1070 \bifuncindex{type}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1071 \refstmodindex{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1072
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1073 Types are written like this: \code{<type 'int'>}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1074
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1075
bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1076 \subsubsection{The Null Object \label{bltin-null-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	1077
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1078 This object is returned by functions that don't explicitly return a
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1079 value. It supports no special operations. There is exactly one null
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1080 object, named \code{None} (a built-in name).
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1081
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1082 It is written as \code{None}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1083
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1084
bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1085 \subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}}
8734 ddaac06ec326 Document Ellipsis (not much of a documentation snippet, but at least Guido van Rossum <guido@python.org> parents: 8730 diff changeset	1086
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1087 This object is used by extended slice notation (see the
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1088 \citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1089 special operations. There is exactly one ellipsis object, named
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1090 \constant{Ellipsis} (a built-in name).
8734 ddaac06ec326 Document Ellipsis (not much of a documentation snippet, but at least Guido van Rossum <guido@python.org> parents: 8730 diff changeset	1091
ddaac06ec326 Document Ellipsis (not much of a documentation snippet, but at least Guido van Rossum <guido@python.org> parents: 8730 diff changeset	1092 It is written as \code{Ellipsis}.
ddaac06ec326 Document Ellipsis (not much of a documentation snippet, but at least Guido van Rossum <guido@python.org> parents: 8730 diff changeset	1093
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1094
10636 9fd29021d147 Added index entry for "file objects"; this is appearantly referenced Fred Drake <fdrake@acm.org> parents: 10606 diff changeset	1095 \subsubsection{File Objects\obindex{file}
9fd29021d147 Added index entry for "file objects"; this is appearantly referenced Fred Drake <fdrake@acm.org> parents: 10606 diff changeset	1096 \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	1097
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1098 File objects are implemented using C's \code{stdio} package and can be
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1099 created with the built-in function
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1100 \function{open()}\bifuncindex{open} described in section
9461 9ffd604807c2 Don't describe something as "below"; that won't make sense for the Fred Drake <fdrake@acm.org> parents: 9318 diff changeset	1101 \ref{built-in-funcs}, ``Built-in Functions.'' They are also returned
9ffd604807c2 Don't describe something as "below"; that won't make sense for the Fred Drake <fdrake@acm.org> parents: 9318 diff changeset	1102 by some other built-in functions and methods, e.g.,
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1103 \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	1104 \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	1105 \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	1106 \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	1107
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1108 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	1109 \exception{IOError} is raised. This includes situations where the
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1110 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	1111 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	1112
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1113 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	1114
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1115
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1116 \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	1117 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	1118 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	1119 \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	1120 \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	1121 \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	1122
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1123 \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	1124 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	1125 \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	1126 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	1127 \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	1128
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1129 \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	1130 Return true if the file is connected to a tty(-like) device, else
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1131 false. \strong{Note:} If a file-like object is not associated
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1132 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	1133 \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	1134
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1135 \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	1136 \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	1137 \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	1138 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	1139 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	1140 operating system. This can be useful for other, lower level
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1141 interfaces that use file descriptors, e.g.\ module
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1142 \refmodule{fcntl}\refbimodindex{fcntl} or \function{os.read()} and
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1143 friends. \strong{Note:} File-like objects which do not have a real
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1144 file descriptor should \emph{not} provide 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	1145 \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	1146
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1147 \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	1148 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	1149 \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	1150 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	1151 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	1152 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	1153 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	1154 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	1155 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	1156 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	1157 \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	1158
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1159 \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	1160 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	1161 kept in the string\footnote{
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	1162 The advantage of leaving the newline on is that an empty string
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1163 can be returned to mean \EOF{} without being ambiguous. Another
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1164 advantage is that (in cases where it might matter, e.g. if you
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1165 want to make an exact copy of a file while scanning its lines)
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1166 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	1167 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	1168 } (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	1169 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	1170 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	1171 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	1172 An empty string is returned when \EOF{} is hit
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 immediately. Note: Unlike \code{stdio}'s \cfunction{fgets()}, the
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1174 returned string contains null characters (\code{'\e 0'}) if they
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1175 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	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
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1178 \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	1179 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	1180 the lines thus read. If the optional \var{sizehint} argument is
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1181 present, instead of reading up to \EOF{}, whole lines totalling
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1182 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	1183 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	1184 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	1185 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	1186 \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	1187
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1188 \begin{methoddesc}[file]{xreadlines}{}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1189 Equivalent to \function{xreadlines.xreadlines(file)}.\refstmodindex{xreadlines}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1190 \end{methoddesc}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1191
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1192 \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	1193 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	1194 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	1195 (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	1196 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	1197 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	1198 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	1199 \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	1200 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	1201 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	1202 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	1203 \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	1204
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1205 \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	1206 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	1207 \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	1208 \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	1209
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1210 \begin{methoddesc}[file]{truncate}{\optional{size}}
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1211 Truncate the file's size. If the optional \var{size} argument
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1212 present, the file is truncated to (at most) that size. The size
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1213 defaults to the current position. Availability of this function
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1214 depends on the operating system version (for example, not all
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1215 \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	1216 \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	1217
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1218 \begin{methoddesc}[file]{write}{str}
15789 9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1219 Write a string to the file. There is no return value. Note: Due to
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1220 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	1221 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	1222 \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	1223
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1224 \begin{methoddesc}[file]{writelines}{list}
15789 9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1225 Write a list of strings to the file. There is no return value.
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1226 (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	1227 \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	1228 \end{methoddesc}
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1229
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1230 \begin{methoddesc}[file]{xreadlines}{}
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1231 Equivalent to
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1232 \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1233 (See the \refmodule{xreadlines} module for more information.)
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 \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	1235
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1236
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1237 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	1238 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	1239 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	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]{closed}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1242 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	1243 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	1244 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	1245 \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	1246
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1247 \begin{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	1248 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	1249 \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	1250 \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	1251 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	1252 \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	1253
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1254 \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	1255 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	1256 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	1257 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	1258 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	1259 \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	1260
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1261 \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	1262 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	1263 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	1264 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	1265 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	1266 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	1267 (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	1268 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	1269 \member{softspace} attribute.
14705 4712f5b8f279 Clarify that the softspace attribute is used by print for state management, Fred Drake <fdrake@acm.org> parents: 14685 diff changeset	1270 \strong{Note:} This attribute is not used to control the
4712f5b8f279 Clarify that the softspace attribute is used by print for state management, Fred Drake <fdrake@acm.org> parents: 14685 diff changeset	1271 \keyword{print} statement, but to allow the implementation of
4712f5b8f279 Clarify that the softspace attribute is used by print for state management, Fred Drake <fdrake@acm.org> parents: 14685 diff changeset	1272 \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	1273 \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	1274
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1275
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1276 \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	1277
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	1278 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	1279 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	1280 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	1281
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1282
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1283 \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	1284
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1285 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	1286 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	1287
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1288 \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	1289 A dictionary or other mapping object used to store an
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1290 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	1291 \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	1292
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1293 \begin{memberdesc}[object]{__methods__}
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1294 List of the methods of many built-in object 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	1295 e.g., \code{[].__methods__} yields
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1296 \code{['append', 'count', 'index', 'insert', 'pop', 'remove',
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1297 'reverse', 'sort']}. This usually does not need to be explicitly
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1298 provided by the object.
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1299 \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	1300
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1301 \begin{memberdesc}[object]{__members__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1302 Similar to \member{__methods__}, but lists data attributes. This
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1303 usually does not need to be explicitly provided by the object.
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1304 \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	1305
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1306 \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	1307 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	1308 \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	1309
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1310 \begin{memberdesc}[class]{__bases__}
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1311 The tuple of base classes of a class object.
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1312 \end{memberdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstdtypes.tex @ 17581:c1937faabb23 2.1