Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{operator} --- |
| 2 | Standard operators as functions.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{builtin}{operator} |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 4 | \sectionauthor{Skip Montanaro}{skip@automatrix.com} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | |
| 6 | \modulesynopsis{All Python's standard operators as built-in functions.} |
| 7 | |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 8 | |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 9 | The \module{operator} module exports a set of functions implemented in C |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 10 | corresponding to the intrinsic operators of Python. For example, |
Fred Drake | f3e6df1 | 1997-12-29 17:11:55 +0000 | [diff] [blame] | 11 | \code{operator.add(x, y)} is equivalent to the expression \code{x+y}. The |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 12 | function names are those used for special class methods; variants without |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 13 | leading and trailing \samp{__} are also provided for convenience. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 14 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 15 | The functions fall into categories that perform object comparisons, |
| 16 | logical operations, mathematical operations, sequence operations, and |
| 17 | abstract type tests. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 18 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 19 | The object comparison functions are useful for all objects, and are |
| 20 | named after the rich comparison operators they support: |
| 21 | |
| 22 | \begin{funcdesc}{lt}{a, b} |
| 23 | \funcline{le}{a, b} |
| 24 | \funcline{eq}{a, b} |
| 25 | \funcline{ne}{a, b} |
| 26 | \funcline{ge}{a, b} |
| 27 | \funcline{gt}{a, b} |
| 28 | \funcline{__lt__}{a, b} |
| 29 | \funcline{__le__}{a, b} |
| 30 | \funcline{__eq__}{a, b} |
| 31 | \funcline{__ne__}{a, b} |
| 32 | \funcline{__ge__}{a, b} |
| 33 | \funcline{__gt__}{a, b} |
| 34 | Perform ``rich comparisons'' between \var{a} and \var{b}. Specifically, |
| 35 | \code{lt(\var{a}, \var{b})} is equivalent to \code{\var{a} < \var{b}}, |
| 36 | \code{le(\var{a}, \var{b})} is equivalent to \code{\var{a} <= \var{b}}, |
| 37 | \code{eq(\var{a}, \var{b})} is equivalent to \code{\var{a} == \var{b}}, |
| 38 | \code{ne(\var{a}, \var{b})} is equivalent to \code{\var{a} != \var{b}}, |
| 39 | \code{gt(\var{a}, \var{b})} is equivalent to \code{\var{a} > \var{b}} |
| 40 | and |
| 41 | \code{ge(\var{a}, \var{b})} is equivalent to \code{\var{a} >= \var{b}}. |
| 42 | Note that unlike the built-in \function{cmp()}, these functions can |
| 43 | return any value, which may or may not be interpretable as a Boolean |
| 44 | value. See the \citetitle[../ref/ref.html]{Python Reference Manual} |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 45 | for more information about rich comparisons. |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 46 | \versionadded{2.2} |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 47 | \end{funcdesc} |
| 48 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 49 | |
| 50 | The logical operations are also generally applicable to all objects, |
Raymond Hettinger | 1b56de0 | 2003-02-21 05:42:13 +0000 | [diff] [blame] | 51 | and support truth tests, identity tests, and boolean operations: |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 52 | |
| 53 | \begin{funcdesc}{not_}{o} |
| 54 | \funcline{__not__}{o} |
| 55 | Return the outcome of \keyword{not} \var{o}. (Note that there is no |
| 56 | \method{__not__()} method for object instances; only the interpreter |
| 57 | core defines this operation. The result is affected by the |
| 58 | \method{__nonzero__()} and \method{__len__()} methods.) |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 59 | \end{funcdesc} |
| 60 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 61 | \begin{funcdesc}{truth}{o} |
Fred Drake | 8ec17a0 | 2003-01-11 23:15:47 +0000 | [diff] [blame] | 62 | Return \constant{True} if \var{o} is true, and \constant{False} |
Neal Norwitz | 06daee9 | 2003-01-12 15:04:54 +0000 | [diff] [blame] | 63 | otherwise. This is equivalent to using the \class{bool} |
Fred Drake | 8ec17a0 | 2003-01-11 23:15:47 +0000 | [diff] [blame] | 64 | constructor. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 65 | \end{funcdesc} |
| 66 | |
Raymond Hettinger | 9543b34 | 2003-01-18 23:22:20 +0000 | [diff] [blame] | 67 | \begin{funcdesc}{is_}{a, b} |
| 68 | Return \code{\var{a} is \var{b}}. Tests object identity. |
Raymond Hettinger | 83c1874 | 2003-11-02 09:50:56 +0000 | [diff] [blame] | 69 | \versionadded{2.3} |
Raymond Hettinger | 9543b34 | 2003-01-18 23:22:20 +0000 | [diff] [blame] | 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{is_not}{a, b} |
| 73 | Return \code{\var{a} is not \var{b}}. Tests object identity. |
Raymond Hettinger | 83c1874 | 2003-11-02 09:50:56 +0000 | [diff] [blame] | 74 | \versionadded{2.3} |
Raymond Hettinger | 9543b34 | 2003-01-18 23:22:20 +0000 | [diff] [blame] | 75 | \end{funcdesc} |
| 76 | |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 77 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 78 | The mathematical and bitwise operations are the most numerous: |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 79 | |
| 80 | \begin{funcdesc}{abs}{o} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 81 | \funcline{__abs__}{o} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 82 | Return the absolute value of \var{o}. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 83 | \end{funcdesc} |
| 84 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 85 | \begin{funcdesc}{add}{a, b} |
| 86 | \funcline{__add__}{a, b} |
| 87 | Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 88 | \end{funcdesc} |
| 89 | |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 90 | \begin{funcdesc}{and_}{a, b} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 91 | \funcline{__and__}{a, b} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 92 | Return the bitwise and of \var{a} and \var{b}. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 93 | \end{funcdesc} |
| 94 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 95 | \begin{funcdesc}{div}{a, b} |
| 96 | \funcline{__div__}{a, b} |
| 97 | Return \var{a} \code{/} \var{b} when \code{__future__.division} is not |
| 98 | in effect. This is also known as ``classic'' division. |
| 99 | \end{funcdesc} |
| 100 | |
| 101 | \begin{funcdesc}{floordiv}{a, b} |
| 102 | \funcline{__floordiv__}{a, b} |
| 103 | Return \var{a} \code{//} \var{b}. |
| 104 | \versionadded{2.2} |
| 105 | \end{funcdesc} |
| 106 | |
| 107 | \begin{funcdesc}{inv}{o} |
| 108 | \funcline{invert}{o} |
| 109 | \funcline{__inv__}{o} |
| 110 | \funcline{__invert__}{o} |
| 111 | Return the bitwise inverse of the number \var{o}. This is equivalent |
| 112 | to \code{\textasciitilde}\var{o}. The names \function{invert()} and |
| 113 | \function{__invert__()} were added in Python 2.0. |
| 114 | \end{funcdesc} |
| 115 | |
| 116 | \begin{funcdesc}{lshift}{a, b} |
| 117 | \funcline{__lshift__}{a, b} |
| 118 | Return \var{a} shifted left by \var{b}. |
| 119 | \end{funcdesc} |
| 120 | |
| 121 | \begin{funcdesc}{mod}{a, b} |
| 122 | \funcline{__mod__}{a, b} |
| 123 | Return \var{a} \code{\%} \var{b}. |
| 124 | \end{funcdesc} |
| 125 | |
| 126 | \begin{funcdesc}{mul}{a, b} |
| 127 | \funcline{__mul__}{a, b} |
| 128 | Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers. |
| 129 | \end{funcdesc} |
| 130 | |
| 131 | \begin{funcdesc}{neg}{o} |
| 132 | \funcline{__neg__}{o} |
| 133 | Return \var{o} negated. |
| 134 | \end{funcdesc} |
| 135 | |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 136 | \begin{funcdesc}{or_}{a, b} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 137 | \funcline{__or__}{a, b} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 138 | Return the bitwise or of \var{a} and \var{b}. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 139 | \end{funcdesc} |
| 140 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 141 | \begin{funcdesc}{pos}{o} |
| 142 | \funcline{__pos__}{o} |
| 143 | Return \var{o} positive. |
| 144 | \end{funcdesc} |
| 145 | |
Raymond Hettinger | 5959c55 | 2002-08-19 03:19:09 +0000 | [diff] [blame] | 146 | \begin{funcdesc}{pow}{a, b} |
| 147 | \funcline{__pow__}{a, b} |
| 148 | Return \var{a} \code{**} \var{b}, for \var{a} and \var{b} numbers. |
Neal Norwitz | 11b795c | 2002-08-19 22:38:01 +0000 | [diff] [blame] | 149 | \versionadded{2.3} |
Raymond Hettinger | 5959c55 | 2002-08-19 03:19:09 +0000 | [diff] [blame] | 150 | \end{funcdesc} |
| 151 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 152 | \begin{funcdesc}{rshift}{a, b} |
| 153 | \funcline{__rshift__}{a, b} |
| 154 | Return \var{a} shifted right by \var{b}. |
| 155 | \end{funcdesc} |
| 156 | |
| 157 | \begin{funcdesc}{sub}{a, b} |
| 158 | \funcline{__sub__}{a, b} |
| 159 | Return \var{a} \code{-} \var{b}. |
| 160 | \end{funcdesc} |
| 161 | |
| 162 | \begin{funcdesc}{truediv}{a, b} |
| 163 | \funcline{__truediv__}{a, b} |
| 164 | Return \var{a} \code{/} \var{b} when \code{__future__.division} is in |
Armin Rigo | ecc275b | 2005-12-29 16:04:25 +0000 | [diff] [blame] | 165 | effect. This is also known as ``true'' division. |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 166 | \versionadded{2.2} |
| 167 | \end{funcdesc} |
| 168 | |
Guido van Rossum | a58e9ed | 1998-05-22 18:48:37 +0000 | [diff] [blame] | 169 | \begin{funcdesc}{xor}{a, b} |
| 170 | \funcline{__xor__}{a, b} |
| 171 | Return the bitwise exclusive or of \var{a} and \var{b}. |
| 172 | \end{funcdesc} |
| 173 | |
Guido van Rossum | a58e9ed | 1998-05-22 18:48:37 +0000 | [diff] [blame] | 174 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 175 | Operations which work with sequences include: |
Guido van Rossum | a58e9ed | 1998-05-22 18:48:37 +0000 | [diff] [blame] | 176 | |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 177 | \begin{funcdesc}{concat}{a, b} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 178 | \funcline{__concat__}{a, b} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 179 | Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 180 | \end{funcdesc} |
| 181 | |
Guido van Rossum | a58e9ed | 1998-05-22 18:48:37 +0000 | [diff] [blame] | 182 | \begin{funcdesc}{contains}{a, b} |
Fred Drake | 5316ef4 | 2000-09-17 16:10:25 +0000 | [diff] [blame] | 183 | \funcline{__contains__}{a, b} |
Guido van Rossum | a58e9ed | 1998-05-22 18:48:37 +0000 | [diff] [blame] | 184 | Return the outcome of the test \var{b} \code{in} \var{a}. |
Fred Drake | 5316ef4 | 2000-09-17 16:10:25 +0000 | [diff] [blame] | 185 | Note the reversed operands. The name \function{__contains__()} was |
| 186 | added in Python 2.0. |
| 187 | \end{funcdesc} |
| 188 | |
Guido van Rossum | a58e9ed | 1998-05-22 18:48:37 +0000 | [diff] [blame] | 189 | \begin{funcdesc}{countOf}{a, b} |
| 190 | Return the number of occurrences of \var{b} in \var{a}. |
| 191 | \end{funcdesc} |
| 192 | |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 193 | \begin{funcdesc}{delitem}{a, b} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 194 | \funcline{__delitem__}{a, b} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 195 | Remove the value of \var{a} at index \var{b}. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 196 | \end{funcdesc} |
| 197 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 198 | \begin{funcdesc}{delslice}{a, b, c} |
| 199 | \funcline{__delslice__}{a, b, c} |
| 200 | Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}. |
| 201 | \end{funcdesc} |
| 202 | |
| 203 | \begin{funcdesc}{getitem}{a, b} |
| 204 | \funcline{__getitem__}{a, b} |
| 205 | Return the value of \var{a} at index \var{b}. |
| 206 | \end{funcdesc} |
| 207 | |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 208 | \begin{funcdesc}{getslice}{a, b, c} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 209 | \funcline{__getslice__}{a, b, c} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 210 | Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 211 | \end{funcdesc} |
| 212 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 213 | \begin{funcdesc}{indexOf}{a, b} |
| 214 | Return the index of the first of occurrence of \var{b} in \var{a}. |
| 215 | \end{funcdesc} |
| 216 | |
| 217 | \begin{funcdesc}{repeat}{a, b} |
| 218 | \funcline{__repeat__}{a, b} |
| 219 | Return \var{a} \code{*} \var{b} where \var{a} is a sequence and |
| 220 | \var{b} is an integer. |
| 221 | \end{funcdesc} |
| 222 | |
| 223 | \begin{funcdesc}{sequenceIncludes}{\unspecified} |
| 224 | \deprecated{2.0}{Use \function{contains()} instead.} |
| 225 | Alias for \function{contains()}. |
| 226 | \end{funcdesc} |
| 227 | |
| 228 | \begin{funcdesc}{setitem}{a, b, c} |
| 229 | \funcline{__setitem__}{a, b, c} |
| 230 | Set the value of \var{a} at index \var{b} to \var{c}. |
| 231 | \end{funcdesc} |
| 232 | |
Fred Drake | 98b032a | 1997-12-04 14:20:59 +0000 | [diff] [blame] | 233 | \begin{funcdesc}{setslice}{a, b, c, v} |
Fred Drake | c07ae9f | 1998-03-08 05:56:15 +0000 | [diff] [blame] | 234 | \funcline{__setslice__}{a, b, c, v} |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 235 | Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the |
| 236 | sequence \var{v}. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 237 | \end{funcdesc} |
| 238 | |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 239 | |
Armin Rigo | f5bd3b4 | 2005-12-29 16:50:42 +0000 | [diff] [blame] | 240 | Many operations have an ``in-place'' version. The following functions |
| 241 | provide a more primitive access to in-place operators than the usual |
| 242 | syntax does; for example, the statement \code{x += y} is equivalent to |
| 243 | \code{x = operator.iadd(x, y)}. Another way to put it is to say that |
| 244 | \code{z = operator.iadd(x, y)} is equivalent to the compound statement |
| 245 | \code{z = x; z += y}. |
| 246 | |
| 247 | \begin{funcdesc}{iadd}{a, b} |
| 248 | \funcline{__iadd__}{a, b} |
| 249 | \code{a = iadd(a, b)} is equivalent to \code{a += b}. |
| 250 | \versionadded{2.5} |
| 251 | \end{funcdesc} |
| 252 | |
| 253 | \begin{funcdesc}{iand}{a, b} |
| 254 | \funcline{__iand__}{a, b} |
| 255 | \code{a = iand(a, b)} is equivalent to \code{a \&= b}. |
| 256 | \versionadded{2.5} |
| 257 | \end{funcdesc} |
| 258 | |
| 259 | \begin{funcdesc}{iconcat}{a, b} |
| 260 | \funcline{__iconcat__}{a, b} |
| 261 | \code{a = iconcat(a, b)} is equivalent to \code{a += b} for \var{a} |
| 262 | and \var{b} sequences. |
| 263 | \versionadded{2.5} |
| 264 | \end{funcdesc} |
| 265 | |
| 266 | \begin{funcdesc}{idiv}{a, b} |
| 267 | \funcline{__idiv__}{a, b} |
| 268 | \code{a = idiv(a, b)} is equivalent to \code{a /= b} when |
| 269 | \code{__future__.division} is not in effect. |
| 270 | \versionadded{2.5} |
| 271 | \end{funcdesc} |
| 272 | |
| 273 | \begin{funcdesc}{ifloordiv}{a, b} |
| 274 | \funcline{__ifloordiv__}{a, b} |
| 275 | \code{a = ifloordiv(a, b)} is equivalent to \code{a //= b}. |
| 276 | \versionadded{2.5} |
| 277 | \end{funcdesc} |
| 278 | |
| 279 | \begin{funcdesc}{ilshift}{a, b} |
| 280 | \funcline{__ilshift__}{a, b} |
| 281 | \code{a = ilshift(a, b)} is equivalent to \code{a <}\code{<= b}. |
| 282 | \versionadded{2.5} |
| 283 | \end{funcdesc} |
| 284 | |
| 285 | \begin{funcdesc}{imod}{a, b} |
| 286 | \funcline{__imod__}{a, b} |
| 287 | \code{a = imod(a, b)} is equivalent to \code{a \%= b}. |
| 288 | \versionadded{2.5} |
| 289 | \end{funcdesc} |
| 290 | |
| 291 | \begin{funcdesc}{imul}{a, b} |
| 292 | \funcline{__imul__}{a, b} |
| 293 | \code{a = imul(a, b)} is equivalent to \code{a *= b}. |
| 294 | \versionadded{2.5} |
| 295 | \end{funcdesc} |
| 296 | |
| 297 | \begin{funcdesc}{ior}{a, b} |
| 298 | \funcline{__ior__}{a, b} |
| 299 | \code{a = ior(a, b)} is equivalent to \code{a |= b}. |
| 300 | \versionadded{2.5} |
| 301 | \end{funcdesc} |
| 302 | |
| 303 | \begin{funcdesc}{ipow}{a, b} |
| 304 | \funcline{__ipow__}{a, b} |
| 305 | \code{a = ipow(a, b)} is equivalent to \code{a **= b}. |
| 306 | \versionadded{2.5} |
| 307 | \end{funcdesc} |
| 308 | |
| 309 | \begin{funcdesc}{irepeat}{a, b} |
| 310 | \funcline{__irepeat__}{a, b} |
| 311 | \code{a = irepeat(a, b)} is equivalent to \code{a *= b} where |
| 312 | \var{a} is a sequence and \var{b} is an integer. |
| 313 | \versionadded{2.5} |
| 314 | \end{funcdesc} |
| 315 | |
| 316 | \begin{funcdesc}{irshift}{a, b} |
| 317 | \funcline{__irshift__}{a, b} |
| 318 | \code{a = irshift(a, b)} is equivalent to \code{a >}\code{>= b}. |
| 319 | \versionadded{2.5} |
| 320 | \end{funcdesc} |
| 321 | |
| 322 | \begin{funcdesc}{isub}{a, b} |
| 323 | \funcline{__isub__}{a, b} |
| 324 | \code{a = isub(a, b)} is equivalent to \code{a -= b}. |
| 325 | \versionadded{2.5} |
| 326 | \end{funcdesc} |
| 327 | |
| 328 | \begin{funcdesc}{itruediv}{a, b} |
| 329 | \funcline{__itruediv__}{a, b} |
| 330 | \code{a = itruediv(a, b)} is equivalent to \code{a /= b} when |
| 331 | \code{__future__.division} is in effect. |
| 332 | \versionadded{2.5} |
| 333 | \end{funcdesc} |
| 334 | |
| 335 | \begin{funcdesc}{ixor}{a, b} |
| 336 | \funcline{__ixor__}{a, b} |
| 337 | \code{a = ixor(a, b)} is equivalent to \code{a \textasciicircum= b}. |
| 338 | \versionadded{2.5} |
| 339 | \end{funcdesc} |
| 340 | |
| 341 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 342 | The \module{operator} module also defines a few predicates to test the |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 343 | type of objects. \note{Be careful not to misinterpret the |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 344 | results of these functions; only \function{isCallable()} has any |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 345 | measure of reliability with instance objects. For example:} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 346 | |
| 347 | \begin{verbatim} |
| 348 | >>> class C: |
| 349 | ... pass |
| 350 | ... |
| 351 | >>> import operator |
| 352 | >>> o = C() |
| 353 | >>> operator.isMappingType(o) |
Martin v. Löwis | ccabed3 | 2003-11-27 19:48:03 +0000 | [diff] [blame] | 354 | True |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 355 | \end{verbatim} |
| 356 | |
| 357 | \begin{funcdesc}{isCallable}{o} |
| 358 | \deprecated{2.0}{Use the \function{callable()} built-in function instead.} |
| 359 | Returns true if the object \var{o} can be called like a function, |
| 360 | otherwise it returns false. True is returned for functions, bound and |
| 361 | unbound methods, class objects, and instance objects which support the |
| 362 | \method{__call__()} method. |
| 363 | \end{funcdesc} |
| 364 | |
| 365 | \begin{funcdesc}{isMappingType}{o} |
| 366 | Returns true if the object \var{o} supports the mapping interface. |
Raymond Hettinger | ad351f8 | 2005-04-07 05:36:17 +0000 | [diff] [blame] | 367 | This is true for dictionaries and all instance objects defining |
| 368 | \method{__getitem__}. |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 369 | \warning{There is no reliable way to test if an instance |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 370 | supports the complete mapping protocol since the interface itself is |
| 371 | ill-defined. This makes this test less useful than it otherwise might |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 372 | be.} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 373 | \end{funcdesc} |
| 374 | |
| 375 | \begin{funcdesc}{isNumberType}{o} |
| 376 | Returns true if the object \var{o} represents a number. This is true |
Raymond Hettinger | ad351f8 | 2005-04-07 05:36:17 +0000 | [diff] [blame] | 377 | for all numeric types implemented in C. |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 378 | \warning{There is no reliable way to test if an instance |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 379 | supports the complete numeric interface since the interface itself is |
| 380 | ill-defined. This makes this test less useful than it otherwise might |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 381 | be.} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 382 | \end{funcdesc} |
| 383 | |
| 384 | \begin{funcdesc}{isSequenceType}{o} |
| 385 | Returns true if the object \var{o} supports the sequence protocol. |
| 386 | This returns true for all objects which define sequence methods in C, |
Raymond Hettinger | ad351f8 | 2005-04-07 05:36:17 +0000 | [diff] [blame] | 387 | and for all instance objects defining \method{__getitem__}. |
| 388 | \warning{There is no reliable |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 389 | way to test if an instance supports the complete sequence interface |
| 390 | since the interface itself is ill-defined. This makes this test less |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 391 | useful than it otherwise might be.} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 392 | \end{funcdesc} |
| 393 | |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 394 | |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 395 | Example: Build a dictionary that maps the ordinals from \code{0} to |
Raymond Hettinger | fb5f04d | 2005-04-07 04:38:04 +0000 | [diff] [blame] | 396 | \code{255} to their character equivalents. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 397 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 398 | \begin{verbatim} |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 399 | >>> import operator |
| 400 | >>> d = {} |
| 401 | >>> keys = range(256) |
| 402 | >>> vals = map(chr, keys) |
| 403 | >>> map(operator.setitem, [d]*len(keys), keys, vals) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 404 | \end{verbatim} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 405 | |
| 406 | |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 407 | The \module{operator} module also defines tools for generalized attribute |
| 408 | and item lookups. These are useful for making fast field extractors |
Raymond Hettinger | b606b3d | 2003-12-17 20:50:46 +0000 | [diff] [blame] | 409 | as arguments for \function{map()}, \function{sorted()}, |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 410 | \method{itertools.groupby()}, or other functions that expect a |
| 411 | function argument. |
| 412 | |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 413 | \begin{funcdesc}{attrgetter}{attr\optional{, args...}} |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 414 | Return a callable object that fetches \var{attr} from its operand. |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 415 | If more than one attribute is requested, returns a tuple of attributes. |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 416 | After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 417 | \samp{b.name}. After, \samp{f=attrgetter('name', 'date')}, the call |
| 418 | \samp{f(b)} returns \samp{(b.name, b.date)}. |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 419 | \versionadded{2.4} |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 420 | \versionchanged[Added support for multiple attributes]{2.5} |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 421 | \end{funcdesc} |
| 422 | |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 423 | \begin{funcdesc}{itemgetter}{item\optional{, args...}} |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 424 | Return a callable object that fetches \var{item} from its operand. |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 425 | If more than one item is requested, returns a tuple of items. |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 426 | After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns |
| 427 | \samp{b[2]}. |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 428 | After, \samp{f=itemgetter(2,5,3)}, the call \samp{f(b)} returns |
| 429 | \samp{(b[2], b[5], b[3])}. |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 430 | \versionadded{2.4} |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 431 | \versionchanged[Added support for multiple item extraction]{2.5} |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 432 | \end{funcdesc} |
| 433 | |
| 434 | Examples: |
| 435 | |
| 436 | \begin{verbatim} |
Raymond Hettinger | 984f9bb | 2005-03-09 16:38:48 +0000 | [diff] [blame] | 437 | >>> from operator import itemgetter |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 438 | >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] |
| 439 | >>> getcount = itemgetter(1) |
| 440 | >>> map(getcount, inventory) |
| 441 | [3, 2, 5, 1] |
Raymond Hettinger | b606b3d | 2003-12-17 20:50:46 +0000 | [diff] [blame] | 442 | >>> sorted(inventory, key=getcount) |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 443 | [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] |
| 444 | \end{verbatim} |
| 445 | |
| 446 | |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 447 | \subsection{Mapping Operators to Functions \label{operator-map}} |
| 448 | |
| 449 | This table shows how abstract operations correspond to operator |
| 450 | symbols in the Python syntax and the functions in the |
| 451 | \refmodule{operator} module. |
| 452 | |
| 453 | |
| 454 | \begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function} |
| 455 | \lineiii{Addition}{\code{\var{a} + \var{b}}} |
| 456 | {\code{add(\var{a}, \var{b})}} |
| 457 | \lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}} |
| 458 | {\code{concat(\var{seq1}, \var{seq2})}} |
| 459 | \lineiii{Containment Test}{\code{\var{o} in \var{seq}}} |
| 460 | {\code{contains(\var{seq}, \var{o})}} |
| 461 | \lineiii{Division}{\code{\var{a} / \var{b}}} |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 462 | {\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}} |
| 463 | \lineiii{Division}{\code{\var{a} / \var{b}}} |
| 464 | {\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}} |
| 465 | \lineiii{Division}{\code{\var{a} // \var{b}}} |
| 466 | {\code{floordiv(\var{a}, \var{b})}} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 467 | \lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}} |
| 468 | {\code{and_(\var{a}, \var{b})}} |
| 469 | \lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}} |
| 470 | {\code{xor(\var{a}, \var{b})}} |
| 471 | \lineiii{Bitwise Inversion}{\code{\~{} \var{a}}} |
| 472 | {\code{invert(\var{a})}} |
| 473 | \lineiii{Bitwise Or}{\code{\var{a} | \var{b}}} |
| 474 | {\code{or_(\var{a}, \var{b})}} |
Raymond Hettinger | 5959c55 | 2002-08-19 03:19:09 +0000 | [diff] [blame] | 475 | \lineiii{Exponentiation}{\code{\var{a} ** \var{b}}} |
| 476 | {\code{pow(\var{a}, \var{b})}} |
Raymond Hettinger | 1b56de0 | 2003-02-21 05:42:13 +0000 | [diff] [blame] | 477 | \lineiii{Identity}{\code{\var{a} is \var{b}}} |
| 478 | {\code{is_(\var{a}, \var{b})}} |
| 479 | \lineiii{Identity}{\code{\var{a} is not \var{b}}} |
| 480 | {\code{is_not(\var{a}, \var{b})}} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 481 | \lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}} |
| 482 | {\code{setitem(\var{o}, \var{k}, \var{v})}} |
| 483 | \lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}} |
| 484 | {\code{delitem(\var{o}, \var{k})}} |
| 485 | \lineiii{Indexing}{\code{\var{o}[\var{k}]}} |
| 486 | {\code{getitem(\var{o}, \var{k})}} |
| 487 | \lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}} |
| 488 | {\code{lshift(\var{a}, \var{b})}} |
| 489 | \lineiii{Modulo}{\code{\var{a} \%\ \var{b}}} |
| 490 | {\code{mod(\var{a}, \var{b})}} |
| 491 | \lineiii{Multiplication}{\code{\var{a} * \var{b}}} |
| 492 | {\code{mul(\var{a}, \var{b})}} |
| 493 | \lineiii{Negation (Arithmetic)}{\code{- \var{a}}} |
| 494 | {\code{neg(\var{a})}} |
| 495 | \lineiii{Negation (Logical)}{\code{not \var{a}}} |
| 496 | {\code{not_(\var{a})}} |
| 497 | \lineiii{Right Shift}{\code{\var{a} >\code{>} \var{b}}} |
| 498 | {\code{rshift(\var{a}, \var{b})}} |
| 499 | \lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}} |
| 500 | {\code{repeat(\var{seq}, \var{i})}} |
| 501 | \lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}} |
| 502 | {\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}} |
| 503 | \lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}} |
| 504 | {\code{delslice(\var{seq}, \var{i}, \var{j})}} |
| 505 | \lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}} |
| 506 | {\code{getslice(\var{seq}, \var{i}, \var{j})}} |
| 507 | \lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}} |
| 508 | {\code{mod(\var{s}, \var{o})}} |
| 509 | \lineiii{Subtraction}{\code{\var{a} - \var{b}}} |
| 510 | {\code{sub(\var{a}, \var{b})}} |
| 511 | \lineiii{Truth Test}{\code{\var{o}}} |
| 512 | {\code{truth(\var{o})}} |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 513 | \lineiii{Ordering}{\code{\var{a} < \var{b}}} |
| 514 | {\code{lt(\var{a}, \var{b})}} |
| 515 | \lineiii{Ordering}{\code{\var{a} <= \var{b}}} |
| 516 | {\code{le(\var{a}, \var{b})}} |
| 517 | \lineiii{Equality}{\code{\var{a} == \var{b}}} |
| 518 | {\code{eq(\var{a}, \var{b})}} |
| 519 | \lineiii{Difference}{\code{\var{a} != \var{b}}} |
| 520 | {\code{ne(\var{a}, \var{b})}} |
| 521 | \lineiii{Ordering}{\code{\var{a} >= \var{b}}} |
| 522 | {\code{ge(\var{a}, \var{b})}} |
| 523 | \lineiii{Ordering}{\code{\var{a} > \var{b}}} |
| 524 | {\code{gt(\var{a}, \var{b})}} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 525 | \end{tableiii} |