1 \section{\module{operator
} ---
2 Standard operators as functions.
}
3 \declaremodule{builtin
}{operator
}
4 \sectionauthor{Skip Montanaro
}{skip@automatrix.com
}
6 \modulesynopsis{All Python's standard operators as built-in functions.
}
9 The
\module{operator
} module exports a set of functions implemented in C
10 corresponding to the intrinsic operators of Python. For example,
11 \code{operator.add(x, y)
} is equivalent to the expression
\code{x+y
}. The
12 function names are those used for special class methods; variants without
13 leading and trailing
\samp{__
} are also provided for convenience.
15 The
\module{operator
} module defines the following functions:
17 \begin{funcdesc
}{add
}{a, b
}
18 \funcline{__add__
}{a, b
}
19 Return
\var{a
} \code{+
} \var{b
}, for
\var{a
} and
\var{b
} numbers.
22 \begin{funcdesc
}{sub
}{a, b
}
23 \funcline{__sub__
}{a, b
}
24 Return
\var{a
} \code{-
} \var{b
}.
27 \begin{funcdesc
}{mul
}{a, b
}
28 \funcline{__mul__
}{a, b
}
29 Return
\var{a
} \code{*
} \var{b
}, for
\var{a
} and
\var{b
} numbers.
32 \begin{funcdesc
}{div
}{a, b
}
33 \funcline{__div__
}{a, b
}
34 Return
\var{a
} \code{/
} \var{b
}.
37 \begin{funcdesc
}{mod
}{a, b
}
38 \funcline{__mod__
}{a, b
}
39 Return
\var{a
} \code{\%
} \var{b
}.
42 \begin{funcdesc
}{neg
}{o
}
44 Return
\var{o
} negated.
47 \begin{funcdesc
}{pos
}{o
}
49 Return
\var{o
} positive.
52 \begin{funcdesc
}{abs
}{o
}
54 Return the absolute value of
\var{o
}.
57 \begin{funcdesc
}{inv
}{o
}
60 \funcline{__invert__
}{o
}
61 Return the bitwise inverse of the number
\var{o
}. The names
62 \function{invert()
} and
\function{__invert__()
} were added in Python
66 \begin{funcdesc
}{lshift
}{a, b
}
67 \funcline{__lshift__
}{a, b
}
68 Return
\var{a
} shifted left by
\var{b
}.
71 \begin{funcdesc
}{rshift
}{a, b
}
72 \funcline{__rshift__
}{a, b
}
73 Return
\var{a
} shifted right by
\var{b
}.
76 \begin{funcdesc
}{and_
}{a, b
}
77 \funcline{__and__
}{a, b
}
78 Return the bitwise and of
\var{a
} and
\var{b
}.
81 \begin{funcdesc
}{or_
}{a, b
}
82 \funcline{__or__
}{a, b
}
83 Return the bitwise or of
\var{a
} and
\var{b
}.
86 \begin{funcdesc
}{xor
}{a, b
}
87 \funcline{__xor__
}{a, b
}
88 Return the bitwise exclusive or of
\var{a
} and
\var{b
}.
91 \begin{funcdesc
}{not_
}{o
}
93 Return the outcome of
\keyword{not
} \var{o
}. (Note that there is no
94 \method{__not__()
} method for object instances; only the interpreter
95 core defines this operation.)
98 \begin{funcdesc
}{truth
}{o
}
99 Return
\code{1} if
\var{o
} is true, and
0 otherwise.
102 \begin{funcdesc
}{concat
}{a, b
}
103 \funcline{__concat__
}{a, b
}
104 Return
\var{a
} \code{+
} \var{b
} for
\var{a
} and
\var{b
} sequences.
107 \begin{funcdesc
}{repeat
}{a, b
}
108 \funcline{__repeat__
}{a, b
}
109 Return
\var{a
} \code{*
} \var{b
} where
\var{a
} is a sequence and
110 \var{b
} is an integer.
113 \begin{funcdesc
}{contains
}{a, b
}
114 \funcline{__contains__
}{a, b
}
115 Return the outcome of the test
\var{b
} \code{in
} \var{a
}.
116 Note the reversed operands. The name
\function{__contains__()
} was
120 \begin{funcdesc
}{sequenceIncludes
}{\unspecified}
121 \deprecated{2.0}{Use
\function{contains()
} instead.
}
122 Alias for
\function{contains()
}.
125 \begin{funcdesc
}{countOf
}{a, b
}
126 Return the number of occurrences of
\var{b
} in
\var{a
}.
129 \begin{funcdesc
}{indexOf
}{a, b
}
130 Return the index of the first of occurrence of
\var{b
} in
\var{a
}.
133 \begin{funcdesc
}{getitem
}{a, b
}
134 \funcline{__getitem__
}{a, b
}
135 Return the value of
\var{a
} at index
\var{b
}.
138 \begin{funcdesc
}{setitem
}{a, b, c
}
139 \funcline{__setitem__
}{a, b, c
}
140 Set the value of
\var{a
} at index
\var{b
} to
\var{c
}.
143 \begin{funcdesc
}{delitem
}{a, b
}
144 \funcline{__delitem__
}{a, b
}
145 Remove the value of
\var{a
} at index
\var{b
}.
148 \begin{funcdesc
}{getslice
}{a, b, c
}
149 \funcline{__getslice__
}{a, b, c
}
150 Return the slice of
\var{a
} from index
\var{b
} to index
\var{c
}\code{-
1}.
153 \begin{funcdesc
}{setslice
}{a, b, c, v
}
154 \funcline{__setslice__
}{a, b, c, v
}
155 Set the slice of
\var{a
} from index
\var{b
} to index
\var{c
}\code{-
1} to the
159 \begin{funcdesc
}{delslice
}{a, b, c
}
160 \funcline{__delslice__
}{a, b, c
}
161 Delete the slice of
\var{a
} from index
\var{b
} to index
\var{c
}\code{-
1}.
164 The
\module{operator
} also defines a few predicates to test the type
165 of objects.
\strong{Note:
} Be careful not to misinterpret the
166 results of these functions; only
\function{isCallable()
} has any
167 measure of reliability with instance objects. For example:
175 >>> operator.isMappingType(o)
179 \begin{funcdesc
}{isCallable
}{o
}
180 \deprecated{2.0}{Use the
\function{callable()
} built-in function instead.
}
181 Returns true if the object
\var{o
} can be called like a function,
182 otherwise it returns false. True is returned for functions, bound and
183 unbound methods, class objects, and instance objects which support the
184 \method{__call__()
} method.
187 \begin{funcdesc
}{isMappingType
}{o
}
188 Returns true if the object
\var{o
} supports the mapping interface.
189 This is true for dictionaries and all instance objects.
190 \strong{Warning:
} There is no reliable way to test if an instance
191 supports the complete mapping protocol since the interface itself is
192 ill-defined. This makes this test less useful than it otherwise might
196 \begin{funcdesc
}{isNumberType
}{o
}
197 Returns true if the object
\var{o
} represents a number. This is true
198 for all numeric types implemented in C, and for all instance objects.
199 \strong{Warning:
} There is no reliable way to test if an instance
200 supports the complete numeric interface since the interface itself is
201 ill-defined. This makes this test less useful than it otherwise might
205 \begin{funcdesc
}{isSequenceType
}{o
}
206 Returns true if the object
\var{o
} supports the sequence protocol.
207 This returns true for all objects which define sequence methods in C,
208 and for all instance objects.
\strong{Warning:
} There is no reliable
209 way to test if an instance supports the complete sequence interface
210 since the interface itself is ill-defined. This makes this test less
211 useful than it otherwise might be.
215 Example: Build a dictionary that maps the ordinals from
\code{0} to
216 \code{256} to their character equivalents.
221 >>> keys = range(
256)
222 >>> vals = map(chr, keys)
223 >>> map(operator.setitem,
[d
]*len(keys), keys, vals)
227 \subsection{Mapping Operators to Functions
\label{operator-map
}}
229 This table shows how abstract operations correspond to operator
230 symbols in the Python syntax and the functions in the
231 \refmodule{operator
} module.
234 \begin{tableiii
}{l|c|l
}{textrm
}{Operation
}{Syntax
}{Function
}
235 \lineiii{Addition
}{\code{\var{a
} +
\var{b
}}}
236 {\code{add(
\var{a
},
\var{b
})
}}
237 \lineiii{Concatenation
}{\code{\var{seq1
} +
\var{seq2
}}}
238 {\code{concat(
\var{seq1
},
\var{seq2
})
}}
239 \lineiii{Containment Test
}{\code{\var{o
} in
\var{seq
}}}
240 {\code{contains(
\var{seq
},
\var{o
})
}}
241 \lineiii{Division
}{\code{\var{a
} /
\var{b
}}}
242 {\code{div(
\var{a
},
\var{b
})
}}
243 \lineiii{Bitwise And
}{\code{\var{a
} \&\
\var{b
}}}
244 {\code{and_(
\var{a
},
\var{b
})
}}
245 \lineiii{Bitwise Exclusive Or
}{\code{\var{a
} \^\
\var{b
}}}
246 {\code{xor(
\var{a
},
\var{b
})
}}
247 \lineiii{Bitwise Inversion
}{\code{\~
{} \var{a
}}}
248 {\code{invert(
\var{a
})
}}
249 \lineiii{Bitwise Or
}{\code{\var{a
} |
\var{b
}}}
250 {\code{or_(
\var{a
},
\var{b
})
}}
251 \lineiii{Indexed Assignment
}{\code{\var{o
}[\var{k
}] =
\var{v
}}}
252 {\code{setitem(
\var{o
},
\var{k
},
\var{v
})
}}
253 \lineiii{Indexed Deletion
}{\code{del
\var{o
}[\var{k
}]}}
254 {\code{delitem(
\var{o
},
\var{k
})
}}
255 \lineiii{Indexing
}{\code{\var{o
}[\var{k
}]}}
256 {\code{getitem(
\var{o
},
\var{k
})
}}
257 \lineiii{Left Shift
}{\code{\var{a
} <
\code{<
} \var{b
}}}
258 {\code{lshift(
\var{a
},
\var{b
})
}}
259 \lineiii{Modulo
}{\code{\var{a
} \%\
\var{b
}}}
260 {\code{mod(
\var{a
},
\var{b
})
}}
261 \lineiii{Multiplication
}{\code{\var{a
} *
\var{b
}}}
262 {\code{mul(
\var{a
},
\var{b
})
}}
263 \lineiii{Negation (Arithmetic)
}{\code{-
\var{a
}}}
264 {\code{neg(
\var{a
})
}}
265 \lineiii{Negation (Logical)
}{\code{not
\var{a
}}}
266 {\code{not_(
\var{a
})
}}
267 \lineiii{Right Shift
}{\code{\var{a
} >
\code{>
} \var{b
}}}
268 {\code{rshift(
\var{a
},
\var{b
})
}}
269 \lineiii{Sequence Repitition
}{\code{\var{seq
} *
\var{i
}}}
270 {\code{repeat(
\var{seq
},
\var{i
})
}}
271 \lineiii{Slice Assignment
}{\code{\var{seq
}[\var{i
}:
\var{j
}]} =
\var{values
}}
272 {\code{setslice(
\var{seq
},
\var{i
},
\var{j
},
\var{values
})
}}
273 \lineiii{Slice Deletion
}{\code{del
\var{seq
}[\var{i
}:
\var{j
}]}}
274 {\code{delslice(
\var{seq
},
\var{i
},
\var{j
})
}}
275 \lineiii{Slicing
}{\code{\var{seq
}[\var{i
}:
\var{j
}]}}
276 {\code{getslice(
\var{seq
},
\var{i
},
\var{j
})
}}
277 \lineiii{String Formatting
}{\code{\var{s
} \%\
\var{o
}}}
278 {\code{mod(
\var{s
},
\var{o
})
}}
279 \lineiii{Subtraction
}{\code{\var{a
} -
\var{b
}}}
280 {\code{sub(
\var{a
},
\var{b
})
}}
281 \lineiii{Truth Test
}{\code{\var{o
}}}
282 {\code{truth(
\var{o
})
}}
