cpython-lru_cache-weakref: Doc/libtypes.tex annotate

annotate Doc/libtypes.tex @ 1590:ac2e5cc29949 legacy-trunk

Added tests for missing host to open_http and open_gopher

author	Guido van Rossum <guido@python.org>
date	Mon, 18 Apr 1994 09:39:56 +0000
parents	2ec96140a36b
children	ac9e12b4ea8c

rev	line source
1471 2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	1 \section{Built-in Types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	2
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	3 The following sections describe the standard types that are built into
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	4 the interpreter. These are the numeric types, sequence types, and
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	5 several others, including types themselves. There is no explicit
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	6 Boolean type; use integers instead.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	7 \indexii{built-in}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	8 \indexii{Boolean}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	9
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	10 Some operations are supported by several object types; in particular,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	11 all objects can be compared, tested for truth value, and converted to
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	12 a string (with the \code{`{\rm \ldots}`} notation). The latter conversion is
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	13 implicitly used when an object is written by the \code{print} statement.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	14 \stindex{print}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	15
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	16 \subsection{Truth Value Testing}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	17
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	18 Any object can be tested for truth value, for use in an \code{if} or
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	19 \code{while} condition or as operand of the Boolean operations below.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	20 The following values are false:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	21 \stindex{if}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	22 \stindex{while}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	23 \indexii{truth}{value}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	24 \indexii{Boolean}{operations}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	25 \index{false}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	26
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	27 \begin{itemize}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	28 \renewcommand{\indexsubitem}{(Built-in object)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	29
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	30 \item \code{None}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	31 \ttindex{None}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	32
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	33 \item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	34
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	35 \item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	36
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	37 \item any empty mapping, e.g., \code{\{\}}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	38
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	39 \end{itemize}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	40
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	41 \emph{All} other values are true --- so objects of many types are
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	42 always true.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	43 \index{true}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	44
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	45 \subsection{Boolean Operations}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	46
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	47 These are the Boolean operations:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	48 \indexii{Boolean}{operations}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	49
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	50 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Result}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	51 \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	52 \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	53 \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	54 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	55 \opindex{and}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	56 \opindex{or}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	57 \opindex{not}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	58
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	59 \noindent
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	60 Notes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	61
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	62 \begin{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	63
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	64 \item[(1)]
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	65 These only evaluate their second argument if needed for their outcome.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	66
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	67 \end{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	68
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	69 \subsection{Comparisons}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	70
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	71 Comparison operations are supported by all objects:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	72
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	73 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Meaning}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	74 \lineiii{<}{strictly less than}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	75 \lineiii{<=}{less than or equal}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	76 \lineiii{>}{strictly greater than}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	77 \lineiii{>=}{greater than or equal}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	78 \lineiii{==}{equal}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	79 \lineiii{<>}{not equal}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	80 \lineiii{!=}{not equal}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	81 \lineiii{is}{object identity}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	82 \lineiii{is not}{negated object identity}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	83 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	84 \indexii{operator}{comparison}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	85 \opindex{==} % XXX All others have funny characters < ! >
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	86 \opindex{is}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	87 \opindex{is not}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	88
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	89 \noindent
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	90 Notes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	91
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	92 \begin{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	93
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	94 \item[(1)]
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	95 \code{<>} and \code{!=} are alternate spellings for the same operator.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	96 (I couldn't choose between \ABC{} and \C{}! :-)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	97 \indexii{\ABC{}}{language}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	98 \indexii{\C{}}{language}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	99
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	100 \end{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	101
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	102 Objects of different types, except different numeric types, never
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	103 compare equal; such objects are ordered consistently but arbitrarily
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	104 (so that sorting a heterogeneous array yields a consistent result).
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	105 Furthermore, some types (e.g., windows) support only a degenerate
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	106 notion of comparison where any two objects of that type are unequal.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	107 Again, such objects are ordered arbitrarily but consistently.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	108 \indexii{types}{numeric}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	109 \indexii{objects}{comparing}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	110
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	111 (Implementation note: objects of different types except numbers are
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	112 ordered by their type names; objects of the same types that don't
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	113 support proper comparison are ordered by their address.)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	114
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	115 Two more operations with the same syntactic priority, \code{in} and
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	116 \code{not in}, are supported only by sequence types (below).
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	117 \opindex{in}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	118 \opindex{not in}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	119
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	120 \subsection{Numeric Types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	121
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	122 There are three numeric types: \dfn{plain integers}, \dfn{long integers}, and
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	123 \dfn{floating point numbers}. Plain integers (also just called \dfn{integers})
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	124 are implemented using \code{long} in \C{}, which gives them at least 32
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	125 bits of precision. Long integers have unlimited precision. Floating
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	126 point numbers are implemented using \code{double} in \C{}. All bets on
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	127 their precision are off unless you happen to know the machine you are
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	128 working with.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	129 \indexii{numeric}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	130 \indexii{integer}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	131 \indexii{integer}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	132 \indexiii{long}{integer}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	133 \indexii{floating point}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	134 \indexii{\C{}}{language}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	135
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	136 Numbers are created by numeric literals or as the result of built-in
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	137 functions and operators. Unadorned integer literals (including hex
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	138 and octal numbers) yield plain integers. Integer literals with an \samp{L}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	139 or \samp{l} suffix yield long integers
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	140 (\samp{L} is preferred because \code{1l} looks too much like eleven!).
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	141 Numeric literals containing a decimal point or an exponent sign yield
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	142 floating point numbers.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	143 \indexii{numeric}{literals}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	144 \indexii{integer}{literals}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	145 \indexiii{long}{integer}{literals}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	146 \indexii{floating point}{literals}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	147 \indexii{hexadecimal}{literals}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	148 \indexii{octal}{literals}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	149
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	150 Python fully supports mixed arithmetic: when a binary arithmetic
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	151 operator has operands of different numeric types, the operand with the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	152 ``smaller'' type is converted to that of the other, where plain
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	153 integer is smaller than long integer is smaller than floating point.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	154 Comparisons between numbers of mixed type use the same rule.%
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	155 \footnote{As a consequence, the list \code{[1, 2]} is considered equal
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	156 to \code{[1.0, 2.0]}, and similar for tuples.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	157 The functions \code{int()}, \code{long()} and \code{float()} can be used
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	158 to coerce numbers to a specific type.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	159 \index{arithmetic}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	160 \bifuncindex{int}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	161 \bifuncindex{long}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	162 \bifuncindex{float}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	163
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	164 All numeric types support the following operations:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	165
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	166 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Result}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	167 \lineiii{abs(\var{x})}{absolute value of \var{x}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	168 \lineiii{int(\var{x})}{\var{x} converted to integer}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	169 \lineiii{long(\var{x})}{\var{x} converted to long integer}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	170 \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	171 \lineiii{-\var{x}}{\var{x} negated}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	172 \lineiii{+\var{x}}{\var{x} unchanged}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	173 \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	174 \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	175 \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	176 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(2)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	177 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	178 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	179 \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	180 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	181 \indexiii{operations on}{numeric}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	182
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	183 \noindent
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	184 Notes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	185 \begin{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	186 \item[(1)]
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	187 Conversion from floating point to (long or plain) integer may round or
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	188 % XXXJH xref here
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	189 truncate as in \C{}; see functions \code{floor} and \code{ceil} in module
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	190 \code{math} for well-defined conversions.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	191 \indexii{numeric}{conversions}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	192 \ttindex{math}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	193 \indexii{\C{}}{language}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	194
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	195 \item[(2)]
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	196 For (plain or long) integer division, the result is an integer; it
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	197 always truncates towards zero.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	198 % XXXJH integer division is better defined nowadays
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	199 \indexii{integer}{division}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	200 \indexiii{long}{integer}{division}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	201
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	202 \item[(3)]
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	203 See the section on built-in functions for an exact definition.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	204
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	205 \end{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	206 % XXXJH exceptions: overflow (when? what operations?) zerodivision
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	207
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	208 \subsubsection{Bit-string Operations on Integer Types.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	209
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	210 Plain and long integer types support additional operations that make
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	211 sense only for bit-strings. Negative numbers are treated as their 2's
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	212 complement value:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	213
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	214 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Result}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	215 \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	216 \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	217 \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	218 \lineiii{\var{x} \| \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	219 \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	220 \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	221 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	222 % XXXJH what's `left'? `right'? maybe better use lsb or msb or something
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	223 \indexiii{operations on}{integer}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	224 \indexii{bit-string}{operations}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	225 \indexii{shifting}{operations}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	226 \indexii{masking}{operations}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	227
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	228 \subsection{Sequence Types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	229
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	230 There are three sequence types: strings, lists and tuples.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	231 Strings literals are written in single quotes: \code{'xyzzy'}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	232 Lists are constructed with square brackets,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	233 separating items with commas:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	234 \code{[a, b, c]}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	235 Tuples are constructed by the comma operator
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	236 (not within square brackets), with or without enclosing parentheses,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	237 but an empty tuple must have the enclosing parentheses, e.g.,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	238 \code{a, b, c} or \code{()}. A single item tuple must have a trailing comma,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	239 e.g., \code{(d,)}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	240 \indexii{sequence}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	241 \indexii{string}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	242 \indexii{tuple}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	243 \indexii{list}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	244
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	245 Sequence types support the following operations (\var{s} and \var{t} are
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	246 sequences of the same type; \var{n}, \var{i} and \var{j} are integers):
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	247
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	248 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Result}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	249 \lineiii{len(\var{s})}{length of \var{s}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	250 \lineiii{min(\var{s})}{smallest item of \var{s}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	251 \lineiii{max(\var{s})}{largest item of \var{s}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	252 \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	253 \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is equal to \var{x}, else \code{1}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	254 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	255 \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	256 \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	257 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	258 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	259 \indexiii{operations on}{sequence}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	260 \bifuncindex{len}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	261 \bifuncindex{min}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	262 \bifuncindex{max}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	263 \indexii{concatenation}{operation}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	264 \indexii{repetition}{operation}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	265 \indexii{subscript}{operation}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	266 \indexii{slice}{operation}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	267 \opindex{in}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	268 \opindex{not in}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	269
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	270 \noindent
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	271 Notes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	272
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	273 % XXXJH all TeX-math expressions replaced by python-syntax expressions
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	274 \begin{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	275
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	276 \item[(1)] If \var{i} or \var{j} is negative, the index is relative to
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	277 the end of the string, i.e., \code{len(\var{s}) + \var{i}} or
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	278 \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	279 still \code{0}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	280
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	281 \item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	282 the sequence of items with index \var{k} such that \code{\var{i} <=
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	283 \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	284 \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	285 use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	286 \var{i} is greater than or equal to \var{j}, the slice is empty.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	287
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	288 \end{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	289
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	290 \subsubsection{More String Operations.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	291
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	292 String objects have one unique built-in operation: the \code{\%}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	293 operator (modulo) with a string left argument interprets this string
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	294 as a C sprintf format string to be applied to the right argument, and
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	295 returns the string resulting from this formatting operation.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	296
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	297 Unless the format string requires exactly one argument, the right
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	298 argument should be a tuple of the correct size. The following format
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	299 characters are understood: \%, c, s, i, d, u, o, x, X, e, E, f, g, G.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	300 Width and precision may be a * to specify that an integer argument
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	301 specifies the actual width or precision. The flag characters -, +,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	302 blank, \# and 0 are understood. The size specifiers h, l or L may be
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	303 present but are ignored. The ANSI features \code{\%p} and \code{\%n}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	304 are not supported. Since Python strings have an explicit length,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	305 \code{\%s} conversions don't assume that \code{'\\0'} is the end of
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	306 the string.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	307
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	308 For safety reasons, huge floating point precisions are truncated;
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	309 \code{\%f} conversions for huge numbers are replaced by
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	310 \code{\%g} conversions. All other errors raise exceptions.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	311
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	312 Additional string operations are defined in standard module
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	313 \code{string} and in built-in module \code{regex}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	314 \index{string}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	315 \index{regex}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	316
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	317 \subsubsection{Mutable Sequence Types.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	318
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	319 List objects support additional operations that allow in-place
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	320 modification of the object.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	321 These operations would be supported by other mutable sequence types
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	322 (when added to the language) as well.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	323 Strings and tuples are immutable sequence types and such objects cannot
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	324 be modified once created.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	325 The following operations are defined on mutable sequence types (where
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	326 \var{x} is an arbitrary object):
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	327 \indexiii{mutable}{sequence}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	328 \indexii{list}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	329
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	330 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Result}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	331 \lineiii{\var{s}[\var{i}] = \var{x}}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	332 {item \var{i} of \var{s} is replaced by \var{x}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	333 \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	334 {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	335 \lineiii{del \var{s}[\var{i}:\var{j}]}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	336 {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	337 \lineiii{\var{s}.append(\var{x})}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	338 {same as \code{\var{s}[len(\var{x}):len(\var{x})] = [\var{x}]}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	339 \lineiii{\var{s}.count(\var{x})}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	340 {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	341 \lineiii{\var{s}.index(\var{x})}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	342 {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	343 \lineiii{\var{s}.insert(\var{i}, \var{x})}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	344 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	345 \lineiii{\var{s}.remove(\var{x})}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	346 {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	347 \lineiii{\var{s}.reverse()}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	348 {reverses the items of \var{s} in place}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	349 \lineiii{\var{s}.sort()}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	350 {permutes the items of \var{s} to satisfy
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	351 \code{\var{s}[\var{i}] <= \var{s}[\var{j}]},
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	352 for \code{\var{i} < \var{j}}}{(2)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	353 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	354 \indexiv{operations on}{mutable}{sequence}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	355 \indexiii{operations on}{sequence}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	356 \indexiii{operations on}{list}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	357 \indexii{subscript}{assignment}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	358 \indexii{slice}{assignment}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	359 \stindex{del}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	360 \renewcommand{\indexsubitem}{(list method)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	361 \ttindex{append}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	362 \ttindex{count}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	363 \ttindex{index}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	364 \ttindex{insert}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	365 \ttindex{remove}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	366 \ttindex{reverse}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	367 \ttindex{sort}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	368
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	369 \noindent
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	370 Notes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	371 \begin{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	372 \item[(1)] Raises an exception when \var{x} is not found in \var{s}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	373
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	374 \item[(2)] The \code{sort()} method takes an optional argument
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	375 specifying a comparison function of two arguments (list items) which
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	376 should return \code{-1}, \code{0} or \code{1} depending on whether the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	377 first argument is considered smaller than, equal to, or larger than the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	378 second argument. Note that this slows the sorting process down
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	379 considerably; e.g. to sort an array in reverse order it is much faster
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	380 to use calls to \code{sort()} and \code{reverse()} than to use
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	381 \code{sort()} with a comparison function that reverses the ordering of
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	382 the elements.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	383 \end{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	384
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	385 \subsection{Mapping Types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	386
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	387 A \dfn{mapping} object maps values of one type (the key type) to
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	388 arbitrary objects. Mappings are mutable objects. There is currently
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	389 only one mapping type, the \dfn{dictionary}. A dictionary's keys are
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	390 almost arbitrary values. The only types of values not acceptable as
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	391 keys are values containing lists or dictionaries or other mutable
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	392 types that are compared by value rather than by object identity.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	393 Numeric types used for keys obey the normal rules for numeric
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	394 comparison: if two numbers compare equal (e.g. 1 and 1.0) then they
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	395 can be used interchangeably to index the same dictionary entry.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	396
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	397 \indexii{mapping}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	398 \indexii{dictionary}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	399
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	400 Dictionaries are created by placing a comma-separated list of
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	401 \code{\var{key}: \var{value}} pairs within braces, for example:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	402 \code{\{'jack': 4098, 'sjoerd: 4127\}} or
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	403 \code{\{4098: 'jack', 4127: 'sjoerd\}}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	404
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	405 The following operations are defined on mappings (where \var{a} is a
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	406 mapping, \var{k} is a key and \var{x} is an arbitrary object):
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	407
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	408 \begin{tableiii}{\|c\|l\|c\|}{code}{Operation}{Result}{Notes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	409 \lineiii{len(\var{a})}{the number of items in \var{a}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	410 \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	411 \lineiii{\var{a}[\var{k}] = \var{x}}{set \code{\var{a}[\var{k}]} to \var{x}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	412 \lineiii{del \var{a}[\var{k}]}{remove \code{\var{a}[\var{k}]} from \var{a}}{(1)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	413 \lineiii{\var{a}.items()}{a copy of \var{a}'s list of (key, item) pairs}{(2)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	414 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	415 \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	416 \lineiii{\var{a}.has_key(\var{k})}{\code{1} if \var{a} has a key \var{k}, else \code{0}}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	417 \end{tableiii}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	418 \indexiii{operations on}{mapping}{types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	419 \indexiii{operations on}{dictionary}{type}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	420 \stindex{del}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	421 \bifuncindex{len}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	422 \renewcommand{\indexsubitem}{(dictionary method)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	423 \ttindex{keys}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	424 \ttindex{has_key}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	425
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	426 % XXXJH some lines above, you talk about `true', elsewhere you
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	427 % explicitely states \code{0} or \code{1}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	428 \noindent
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	429 Notes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	430 \begin{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	431 \item[(1)] Raises an exception if \var{k} is not in the map.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	432
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	433 \item[(2)] Keys and values are listed in random order, but at any
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	434 moment the ordering of the \code{keys()}, \code{values()} and
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	435 \code{items()} lists is the consistent with each other.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	436 \end{description}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	437
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	438 \subsection{Other Built-in Types}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	439
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	440 The interpreter supports several other kinds of objects.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	441 Most of these support only one or two operations.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	442
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	443 \subsubsection{Modules.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	444
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	445 The only special operation on a module is attribute access:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	446 \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} accesses
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	447 a name defined in \var{m}'s symbol table. Module attributes can be
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	448 assigned to. (Note that the \code{import} statement is not, strictly
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	449 spoken, an operation on a module object; \code{import \var{foo}} does not
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	450 require a module object named \var{foo} to exist, rather it requires
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	451 an (external) \emph{definition} for a module named \var{foo}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	452 somewhere.)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	453
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	454 A special member of every module is \code{__dict__}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	455 This is the dictionary containing the module's symbol table.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	456 Modifying this dictionary will actually change the module's symbol
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	457 table, but direct assignment to the \code{__dict__} attribute is not
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	458 possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	459 defines \code{\var{m}.a} to be \code{1}, but you can't write \code{\var{m}.__dict__ = \{\}}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	460
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	461 Modules are written like this: \code{<module 'sys'>}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	462
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	463 \subsubsection{Classes and Class Instances.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	464 % XXXJH cross ref here
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	465 (See the Python Reference Manual for these.)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	466
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	467 \subsubsection{Functions.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	468
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	469 Function objects are created by function definitions. The only
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	470 operation on a function object is to call it:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	471 \code{\var{func}(\var{argument-list})}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	472
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	473 There are really two flavors of function objects: built-in functions
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	474 and user-defined functions. Both support the same operation (to call
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	475 the function), but the implementation is different, hence the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	476 different object types.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	477
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	478 The implementation adds two special read-only attributes:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	479 \code{\var{f}.func_code} is a function's \dfn{code object} (see below) and
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	480 \code{\var{f}.func_globals} is the dictionary used as the function's
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	481 global name space (this is the same as \code{\var{m}.__dict__} where
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	482 \var{m} is the module in which the function \var{f} was defined).
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	483
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	484 \subsubsection{Methods.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	485
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	486 Methods are functions that are called using the attribute notation.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	487 There are two flavors: built-in methods (such as \code{append()} on
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	488 lists) and class instance methods. Built-in methods are described
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	489 with the types that support them.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	490
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	491 The implementation adds two special read-only attributes to class
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	492 instance methods: \code{\var{m}.im_self} is the object whose method this
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	493 is, and \code{\var{m}.im_func} is the function implementing the method.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	494 Calling \code{\var{m}(\var{arg-1}, \var{arg-2}, {\rm \ldots},
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	495 \var{arg-n})} is completely equivalent to calling
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	496 \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, \var{arg-2}, {\rm
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	497 \ldots}, \var{arg-n})}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	498
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	499 (See the Python Reference Manual for more info.)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	500
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	501 \subsubsection{Type Objects.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	502
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	503 Type objects represent the various object types. An object's type is
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	504 % XXXJH xref here
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	505 accessed by the built-in function \code{type()}. There are no special
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	506 operations on types.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	507
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	508 Types are written like this: \code{<type 'int'>}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	509
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	510 \subsubsection{The Null Object.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	511
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	512 This object is returned by functions that don't explicitly return a
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	513 value. It supports no special operations. There is exactly one null
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	514 object, named \code{None} (a built-in name).
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	515
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	516 It is written as \code{None}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	517
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	518 \subsubsection{File Objects.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	519
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	520 File objects are implemented using \C{}'s \code{stdio} package and can be
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	521 % XXXJH xref here
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	522 created with the built-in function \code{open()} described under
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	523 Built-in Functions below.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	524
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	525 When a file operation fails for an I/O-related reason, the exception
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	526 \code{IOError} is raised. This includes situations where the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	527 operation is not defined for some reason, like \code{seek()} on a tty
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	528 device or writing a file opened for reading.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	529
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	530 Files have the following methods:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	531
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	532
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	533 \renewcommand{\indexsubitem}{(file method)}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	534
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	535 \begin{funcdesc}{close}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	536 Close the file. A closed file cannot be read or written anymore.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	537 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	538
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	539 \begin{funcdesc}{flush}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	540 Flush the internal buffer, like \code{stdio}'s \code{fflush()}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	541 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	542
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	543 \begin{funcdesc}{isatty}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	544 Return \code{1} if the file is connected to a tty(-like) device, else
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	545 \code{0}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	546 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	547
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	548 \begin{funcdesc}{read}{size}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	549 Read at most \var{size} bytes from the file (less if the read hits
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	550 \EOF{} or no more data is immediately available on a pipe, tty or
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	551 similar device). If the \var{size} argument is omitted, read all
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	552 data until \EOF{} is reached. The bytes are returned as a string
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	553 object. An empty string is returned when \EOF{} is encountered
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	554 immediately. (For certain files, like ttys, it makes sense to
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	555 continue reading after an \EOF{} is hit.)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	556 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	557
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	558 \begin{funcdesc}{readline}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	559 Read one entire line from the file. A trailing newline character is
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	560 kept in the string (but may be absent when a file ends with an
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	561 incomplete line). An empty string is returned when \EOF{} is hit
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	562 immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	563 string contains null characters (\code{'\e 0'}) if they occurred in the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	564 input.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	565 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	566
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	567 \begin{funcdesc}{readlines}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	568 Read until \EOF{} using \code{readline()} and return a list containing
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	569 the lines thus read.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	570 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	571
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	572 \begin{funcdesc}{seek}{offset\, whence}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	573 Set the file's current position, like \code{stdio}'s \code{fseek()}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	574 The \var{whence} argument is optional and defaults to \code{0}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	575 (absolute file positioning); other values are \code{1} (seek
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	576 relative to the current position) and \code{2} (seek relative to the
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	577 file's end). There is no return value.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	578 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	579
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	580 \begin{funcdesc}{tell}{}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	581 Return the file's current position, like \code{stdio}'s \code{ftell()}.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	582 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	583
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	584 \begin{funcdesc}{write}{str}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	585 Write a string to the file. There is no return value.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	586 \end{funcdesc}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	587
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	588 \subsubsection{Internal Objects.}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	589
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	590 (See the Python Reference Manual for these.)
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	591
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	592 \subsection{Special Attributes}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	593
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	594 The implementation adds a few special read-only attributes to several
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	595 object types, where they are relevant:
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	596
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	597 \begin{itemize}
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	598
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	599 \item
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	600 \code{\var{x}.__dict__} is a dictionary of some sort used to store an
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	601 object's (writable) attributes;
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	602
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	603 \item
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	604 \code{\var{x}.__methods__} lists the methods of many built-in object types,
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	605 e.g., \code{[].__methods__} is
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	606 % XXXJH results in?, yields?, written down as an example
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	607 \code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']};
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	608
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	609 \item
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	610 \code{\var{x}.__members__} lists data attributes;
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	611
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	612 \item
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	613 \code{\var{x}.__class__} is the class to which a class instance belongs;
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	614
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	615 \item
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	616 \code{\var{x}.__bases__} is the tuple of base classes of a class object.
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	617
2ec96140a36b Restructured library documentation Guido van Rossum <guido@python.org> parents: diff changeset	618 \end{itemize}

Mercurial > cpython-lru_cache-weakref

annotate Doc/libtypes.tex @ 1590:ac2e5cc29949 legacy-trunk