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} |
| 45 | for more informations about rich comparisons. |
| 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 |
| 165 | effect. This is also known as division. |
| 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 | |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 240 | The \module{operator} module also defines a few predicates to test the |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 241 | type of objects. \note{Be careful not to misinterpret the |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 242 | results of these functions; only \function{isCallable()} has any |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 243 | measure of reliability with instance objects. For example:} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 244 | |
| 245 | \begin{verbatim} |
| 246 | >>> class C: |
| 247 | ... pass |
| 248 | ... |
| 249 | >>> import operator |
| 250 | >>> o = C() |
| 251 | >>> operator.isMappingType(o) |
Martin v. Löwis | ccabed3 | 2003-11-27 19:48:03 +0000 | [diff] [blame] | 252 | True |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 253 | \end{verbatim} |
| 254 | |
| 255 | \begin{funcdesc}{isCallable}{o} |
| 256 | \deprecated{2.0}{Use the \function{callable()} built-in function instead.} |
| 257 | Returns true if the object \var{o} can be called like a function, |
| 258 | otherwise it returns false. True is returned for functions, bound and |
| 259 | unbound methods, class objects, and instance objects which support the |
| 260 | \method{__call__()} method. |
| 261 | \end{funcdesc} |
| 262 | |
| 263 | \begin{funcdesc}{isMappingType}{o} |
| 264 | Returns true if the object \var{o} supports the mapping interface. |
| 265 | This is true for dictionaries and all instance objects. |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 266 | \warning{There is no reliable way to test if an instance |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 267 | supports the complete mapping protocol since the interface itself is |
| 268 | ill-defined. This makes this test less useful than it otherwise might |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 269 | be.} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 270 | \end{funcdesc} |
| 271 | |
| 272 | \begin{funcdesc}{isNumberType}{o} |
| 273 | Returns true if the object \var{o} represents a number. This is true |
| 274 | for all numeric types implemented in C, and for all instance objects. |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 275 | \warning{There is no reliable way to test if an instance |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 276 | supports the complete numeric interface since the interface itself is |
| 277 | ill-defined. This makes this test less useful than it otherwise might |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 278 | be.} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 279 | \end{funcdesc} |
| 280 | |
| 281 | \begin{funcdesc}{isSequenceType}{o} |
| 282 | Returns true if the object \var{o} supports the sequence protocol. |
| 283 | This returns true for all objects which define sequence methods in C, |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 284 | and for all instance objects. \warning{There is no reliable |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 285 | way to test if an instance supports the complete sequence interface |
| 286 | since the interface itself is ill-defined. This makes this test less |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 287 | useful than it otherwise might be.} |
Fred Drake | 8d3312f | 2000-10-02 03:36:18 +0000 | [diff] [blame] | 288 | \end{funcdesc} |
| 289 | |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 290 | |
Fred Drake | 0514ce1 | 1997-12-16 14:29:48 +0000 | [diff] [blame] | 291 | Example: Build a dictionary that maps the ordinals from \code{0} to |
| 292 | \code{256} to their character equivalents. |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 293 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 294 | \begin{verbatim} |
Guido van Rossum | 61ed4db | 1996-12-06 21:22:41 +0000 | [diff] [blame] | 295 | >>> import operator |
| 296 | >>> d = {} |
| 297 | >>> keys = range(256) |
| 298 | >>> vals = map(chr, keys) |
| 299 | >>> map(operator.setitem, [d]*len(keys), keys, vals) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 300 | \end{verbatim} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 301 | |
| 302 | |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 303 | The \module{operator} module also defines tools for generalized attribute |
| 304 | and item lookups. These are useful for making fast field extractors |
Raymond Hettinger | b606b3d | 2003-12-17 20:50:46 +0000 | [diff] [blame] | 305 | as arguments for \function{map()}, \function{sorted()}, |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 306 | \method{itertools.groupby()}, or other functions that expect a |
| 307 | function argument. |
| 308 | |
| 309 | \begin{funcdesc}{attrgetter}{attr} |
| 310 | Return a callable object that fetches \var{attr} from its operand. |
| 311 | After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns |
| 312 | \samp{b.name}. |
| 313 | \versionadded{2.4} |
| 314 | \end{funcdesc} |
| 315 | |
| 316 | \begin{funcdesc}{itemgetter}{item} |
| 317 | Return a callable object that fetches \var{item} from its operand. |
| 318 | After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns |
| 319 | \samp{b[2]}. |
| 320 | \versionadded{2.4} |
| 321 | \end{funcdesc} |
| 322 | |
| 323 | Examples: |
| 324 | |
| 325 | \begin{verbatim} |
| 326 | >>> from operator import * |
| 327 | >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] |
| 328 | >>> getcount = itemgetter(1) |
| 329 | >>> map(getcount, inventory) |
| 330 | [3, 2, 5, 1] |
Raymond Hettinger | b606b3d | 2003-12-17 20:50:46 +0000 | [diff] [blame] | 331 | >>> sorted(inventory, key=getcount) |
Raymond Hettinger | 166958b | 2003-12-01 13:18:39 +0000 | [diff] [blame] | 332 | [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] |
| 333 | \end{verbatim} |
| 334 | |
| 335 | |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 336 | \subsection{Mapping Operators to Functions \label{operator-map}} |
| 337 | |
| 338 | This table shows how abstract operations correspond to operator |
| 339 | symbols in the Python syntax and the functions in the |
| 340 | \refmodule{operator} module. |
| 341 | |
| 342 | |
| 343 | \begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function} |
| 344 | \lineiii{Addition}{\code{\var{a} + \var{b}}} |
| 345 | {\code{add(\var{a}, \var{b})}} |
| 346 | \lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}} |
| 347 | {\code{concat(\var{seq1}, \var{seq2})}} |
| 348 | \lineiii{Containment Test}{\code{\var{o} in \var{seq}}} |
| 349 | {\code{contains(\var{seq}, \var{o})}} |
| 350 | \lineiii{Division}{\code{\var{a} / \var{b}}} |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 351 | {\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}} |
| 352 | \lineiii{Division}{\code{\var{a} / \var{b}}} |
| 353 | {\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}} |
| 354 | \lineiii{Division}{\code{\var{a} // \var{b}}} |
| 355 | {\code{floordiv(\var{a}, \var{b})}} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 356 | \lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}} |
| 357 | {\code{and_(\var{a}, \var{b})}} |
| 358 | \lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}} |
| 359 | {\code{xor(\var{a}, \var{b})}} |
| 360 | \lineiii{Bitwise Inversion}{\code{\~{} \var{a}}} |
| 361 | {\code{invert(\var{a})}} |
| 362 | \lineiii{Bitwise Or}{\code{\var{a} | \var{b}}} |
| 363 | {\code{or_(\var{a}, \var{b})}} |
Raymond Hettinger | 5959c55 | 2002-08-19 03:19:09 +0000 | [diff] [blame] | 364 | \lineiii{Exponentiation}{\code{\var{a} ** \var{b}}} |
| 365 | {\code{pow(\var{a}, \var{b})}} |
Raymond Hettinger | 1b56de0 | 2003-02-21 05:42:13 +0000 | [diff] [blame] | 366 | \lineiii{Identity}{\code{\var{a} is \var{b}}} |
| 367 | {\code{is_(\var{a}, \var{b})}} |
| 368 | \lineiii{Identity}{\code{\var{a} is not \var{b}}} |
| 369 | {\code{is_not(\var{a}, \var{b})}} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 370 | \lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}} |
| 371 | {\code{setitem(\var{o}, \var{k}, \var{v})}} |
| 372 | \lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}} |
| 373 | {\code{delitem(\var{o}, \var{k})}} |
| 374 | \lineiii{Indexing}{\code{\var{o}[\var{k}]}} |
| 375 | {\code{getitem(\var{o}, \var{k})}} |
| 376 | \lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}} |
| 377 | {\code{lshift(\var{a}, \var{b})}} |
| 378 | \lineiii{Modulo}{\code{\var{a} \%\ \var{b}}} |
| 379 | {\code{mod(\var{a}, \var{b})}} |
| 380 | \lineiii{Multiplication}{\code{\var{a} * \var{b}}} |
| 381 | {\code{mul(\var{a}, \var{b})}} |
| 382 | \lineiii{Negation (Arithmetic)}{\code{- \var{a}}} |
| 383 | {\code{neg(\var{a})}} |
| 384 | \lineiii{Negation (Logical)}{\code{not \var{a}}} |
| 385 | {\code{not_(\var{a})}} |
| 386 | \lineiii{Right Shift}{\code{\var{a} >\code{>} \var{b}}} |
| 387 | {\code{rshift(\var{a}, \var{b})}} |
| 388 | \lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}} |
| 389 | {\code{repeat(\var{seq}, \var{i})}} |
| 390 | \lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}} |
| 391 | {\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}} |
| 392 | \lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}} |
| 393 | {\code{delslice(\var{seq}, \var{i}, \var{j})}} |
| 394 | \lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}} |
| 395 | {\code{getslice(\var{seq}, \var{i}, \var{j})}} |
| 396 | \lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}} |
| 397 | {\code{mod(\var{s}, \var{o})}} |
| 398 | \lineiii{Subtraction}{\code{\var{a} - \var{b}}} |
| 399 | {\code{sub(\var{a}, \var{b})}} |
| 400 | \lineiii{Truth Test}{\code{\var{o}}} |
| 401 | {\code{truth(\var{o})}} |
Fred Drake | e89659c | 2001-08-10 15:55:09 +0000 | [diff] [blame] | 402 | \lineiii{Ordering}{\code{\var{a} < \var{b}}} |
| 403 | {\code{lt(\var{a}, \var{b})}} |
| 404 | \lineiii{Ordering}{\code{\var{a} <= \var{b}}} |
| 405 | {\code{le(\var{a}, \var{b})}} |
| 406 | \lineiii{Equality}{\code{\var{a} == \var{b}}} |
| 407 | {\code{eq(\var{a}, \var{b})}} |
| 408 | \lineiii{Difference}{\code{\var{a} != \var{b}}} |
| 409 | {\code{ne(\var{a}, \var{b})}} |
| 410 | \lineiii{Ordering}{\code{\var{a} >= \var{b}}} |
| 411 | {\code{ge(\var{a}, \var{b})}} |
| 412 | \lineiii{Ordering}{\code{\var{a} > \var{b}}} |
| 413 | {\code{gt(\var{a}, \var{b})}} |
Fred Drake | 8c2fd49 | 2000-10-22 03:19:30 +0000 | [diff] [blame] | 414 | \end{tableiii} |