9.9. "operator" --- 関数形式の標準演算子
****************************************

"operator" モジュールは、Python の組み込み演算子に対応する効率的な関数
群を提供します。例えば、 "operator.add(x, y)" は式 "x+y" と等価です。
関数の名前は、特殊クラスメソッドに使われている名前と同じです; 便宜上、
先頭と末尾の "__" を取り除いたものも提供されています。

これらの関数はそれぞれ、オブジェクト比較、論理演算、数学演算、シーケン
ス操作、および抽象型テストに分類されます。

オブジェクト比較関数は全てのオブジェクトで有効で、関数の名前はサポート
する拡張比較演算子からとられています:

operator.lt(a, b)
operator.le(a, b)
operator.eq(a, b)
operator.ne(a, b)
operator.ge(a, b)
operator.gt(a, b)
operator.__lt__(a, b)
operator.__le__(a, b)
operator.__eq__(a, b)
operator.__ne__(a, b)
operator.__ge__(a, b)
operator.__gt__(a, b)

   *a* と *b* の "拡張比較 (rich comparisons)" を行います。具体的には
   、 "lt(a, b)" は "a < b" 、 "le(a, b)" は "a <= b" 、 "eq(a, b)" は
   "a == b" 、 "ne(a, b)" は "a != b" 、 "gt(a, b)" は "a >= b" 、そし
   て "ge(a, b)" は "a >= b" と等価です。組み込み関数 "cmp()" と違って
   、これらの関数はどのような値を返してもよく、ブール値として解釈でき
   てもできなくてもかまいません。拡張比較の詳細については 比較 を参照
   してください。

   バージョン 2.2 で追加.

論理演算もまた全てのオブジェクトに対して適用でき、真理値判定、同一性判
定およびブール演算をサポートします:

operator.not_(obj)
operator.__not__(obj)

   "not" *obj* の結果を返します。(オブジェクトインスタンスには
   "__not__()" メソッドは無いので注意してください; インタプリタコアが
   この演算を定義しているだけです。結果は "__nonzero__()" および
   "__len__()" メソッドに影響されます。)

operator.truth(obj)

   *obj* が真の場合 "True"  を返し、そうでない場合 "False" を返します
   。この関数は "bool" のコンストラクタ呼び出しと同等です。

operator.is_(a, b)

   "a is b" を返します。オブジェクトの同一性を判定します。

   バージョン 2.3 で追加.

operator.is_not(a, b)

   "a is not b" を返します。オブジェクトの同一性を判定します。

   バージョン 2.3 で追加.

演算子で最も多いのは数学演算およびビット単位の演算です:

operator.abs(obj)
operator.__abs__(obj)

   *obj* の絶対値を返します。

operator.add(a, b)
operator.__add__(a, b)

   数値 *a* および *b* について "a + b" を返します。

operator.and_(a, b)
operator.__and__(a, b)

   *a* と *b* のビット単位論理積を返します。

operator.div(a, b)
operator.__div__(a, b)

   "__future__.division" が有効でなければ、 "a / b" は "a // b" と同じ
   結果を返します。これは "古典的な (classic)" 除算とも呼ばれます。

operator.floordiv(a, b)
operator.__floordiv__(a, b)

   "a // b" を返します。

   バージョン 2.2 で追加.

operator.index(a)
operator.__index__(a)

   整数に変換された *a* を返します。"a.__index__()" と同等です。

   バージョン 2.5 で追加.

operator.inv(obj)
operator.invert(obj)
operator.__inv__(obj)
operator.__invert__(obj)

   *obj* のビット単位反転を返します。"~obj" と同じです。

   バージョン 2.0 で追加: 名前 "invert()" および "__invert__()" が追加
   されました。

operator.lshift(a, b)
operator.__lshift__(a, b)

   *a* の *b* ビット左シフトを返します。

operator.mod(a, b)
operator.__mod__(a, b)

   "a % b" を返します。

operator.mul(a, b)
operator.__mul__(a, b)

   数値 *a* および *b* について "a * b" を返します。

operator.neg(obj)
operator.__neg__(obj)

   *obj* の符号反転 ("-obj") を返します。

operator.or_(a, b)
operator.__or__(a, b)

   *a* と *b* のビット単位論理和を返します。

operator.pos(obj)
operator.__pos__(obj)

   *obj* の符号非反転 ("+obj") を返します。

operator.pow(a, b)
operator.__pow__(a, b)

   数値 *a* および *b* について "a ** b" を返します。

   バージョン 2.3 で追加.

operator.rshift(a, b)
operator.__rshift__(a, b)

   *a* の *b* ビット右シフトを返します。

operator.sub(a, b)
operator.__sub__(a, b)

   "a - b" を返します。

operator.truediv(a, b)
operator.__truediv__(a, b)

   "__future__.division" が有効な場合 "a / b" を返します。 "真の" 除算
   としても知られています。

   バージョン 2.2 で追加.

operator.xor(a, b)
operator.__xor__(a, b)

   *a* および *b* のビット単位排他的論理和を返します。

シーケンスを扱う演算子（いくつかの演算子はマッピングも扱います）には以
下のようなものがあります:

operator.concat(a, b)
operator.__concat__(a, b)

   シーケンス *a* および *b* について "a + b" を返します。

operator.contains(a, b)
operator.__contains__(a, b)

   "b in a" の判定結果を返します。被演算子が左右反転しているので注意し
   てください。

   バージョン 2.0 で追加: 関数名 "__contains__()" が追加されました。

operator.countOf(a, b)

   *a* の中に *b* が出現する回数を返します。

operator.delitem(a, b)
operator.__delitem__(a, b)

   *a* でインデクスが *b* の値を削除します。

operator.delslice(a, b, c)
operator.__delslice__(a, b, c)

   *a* でインデクスが *b* から *c-1* のスライス要素を削除します。

   バージョン 2.6 で非推奨: この関数は Python 3.x で削除されます。
   "delitem()" をスライスインデクスで使って下さい。

operator.getitem(a, b)
operator.__getitem__(a, b)

   *a* でインデクスが *b* の値を返します。

operator.getslice(a, b, c)
operator.__getslice__(a, b, c)

   *a* でインデクスが *b* から *c-1* のスライス要素を返します。

   バージョン 2.6 で非推奨: この関数は Python 3.x で削除されます。
   "getitem()" をスライスインデクスで使って下さい。

operator.indexOf(a, b)

   *a* で最初に *b* が出現する場所のインデクスを返します。

operator.repeat(a, b)
operator.__repeat__(a, b)

   バージョン 2.7 で非推奨: 代わりに "__mul__()" を使ってください。

   シーケンス *a* と整数 *b* について "a * b" を返します。

operator.sequenceIncludes(...)

   バージョン 2.0 で非推奨: 代わりに "contains()" を使ってください。

   "contains()" の別名です。

operator.setitem(a, b, c)
operator.__setitem__(a, b, c)

   *a* でインデクスが *b* の値を *c* に設定します。

operator.setslice(a, b, c, v)
operator.__setslice__(a, b, c, v)

   *a* でインデクスが *b* から *c-1* のスライス要素の値をシーケンス
   *v* に設定します。

   バージョン 2.6 で非推奨: この関数は Python 3.x で削除されます。
   "setitem()" をスライスインデクスで使って下さい。

operator の関数を使う例を挙げます:

   >>> # Elementwise multiplication
   >>> map(mul, [0, 1, 2, 3], [10, 20, 30, 40])
   [0, 20, 60, 120]

   >>> # Dot product
   >>> sum(map(mul, [0, 1, 2, 3], [10, 20, 30, 40]))
   200

多くの演算に「インプレース」版があります。 以下の関数はそうした演算子
の通常の文法に比べてより素朴な呼び出し方を提供します。たとえば、文
(*statement*) "x += y" は "x = operator.iadd(x, y)" と等価です。別の言
い方をすると、 "z = operator.iadd(x, y)" は複合文 "z = x; z += y" と等
価です。

operator.iadd(a, b)
operator.__iadd__(a, b)

   "a = iadd(a, b)" は "a += b" と等価です。

   バージョン 2.5 で追加.

operator.iand(a, b)
operator.__iand__(a, b)

   "a = iand(a, b)" は "a &= b" と等価です。

   バージョン 2.5 で追加.

operator.iconcat(a, b)
operator.__iconcat__(a, b)

   "a = iconcat(a, b)" は二つのシーケンス *a* と *b* に対し "a += b"
   と等価です。

   バージョン 2.5 で追加.

operator.idiv(a, b)
operator.__idiv__(a, b)

   "a = idiv(a, b)" は "__future__.division" が有効でないときに "a /=
   b" と等価です。

   バージョン 2.5 で追加.

operator.ifloordiv(a, b)
operator.__ifloordiv__(a, b)

   "a = ifloordiv(a, b)" は "a //= b" と等価です。

   バージョン 2.5 で追加.

operator.ilshift(a, b)
operator.__ilshift__(a, b)

   "a = ilshift(a, b)" は "a <<= b" と等価です。

   バージョン 2.5 で追加.

operator.imod(a, b)
operator.__imod__(a, b)

   "a = imod(a, b)" は "a %= b" と等価です。

   バージョン 2.5 で追加.

operator.imul(a, b)
operator.__imul__(a, b)

   "a = imul(a, b)" は "a *= b" と等価です。

   バージョン 2.5 で追加.

operator.ior(a, b)
operator.__ior__(a, b)

   "a = ior(a, b)" は "a |= b" と等価です。

   バージョン 2.5 で追加.

operator.ipow(a, b)
operator.__ipow__(a, b)

   "a = ipow(a, b)" は "a **= b" と等価です。

   バージョン 2.5 で追加.

operator.irepeat(a, b)
operator.__irepeat__(a, b)

   バージョン 2.7 で非推奨: 代わりに "__imul__()" を使ってください。

   "a = irepeat(a, b)" は *a* がシーケンスで *b* が整数であるとき "a
   *= b" と等価です。

   バージョン 2.5 で追加.

operator.irshift(a, b)
operator.__irshift__(a, b)

   "a = irshift(a, b)" は "a >>= b" と等価です。

   バージョン 2.5 で追加.

operator.isub(a, b)
operator.__isub__(a, b)

   "a = isub(a, b)" は "a -= b" と等価です。

   バージョン 2.5 で追加.

operator.itruediv(a, b)
operator.__itruediv__(a, b)

   "a = itruediv(a, b)" は "__future__.division" が有効なときに "a /=
   b" と等価です。

   バージョン 2.5 で追加.

operator.ixor(a, b)
operator.__ixor__(a, b)

   "a = ixor(a, b)" は "a ^= b" と等価です。

   バージョン 2.5 で追加.

"operator" モジュールでは、オブジェクトの型を調べるための述語演算子も
定義しています。しかしながらこれらはいつでも信頼できるというわけではあ
りません。代わりに抽象基底クラスをテストするのが望ましい方法です (詳し
くは "collections" や "numbers" を参照して下さい)。

operator.isCallable(obj)

   バージョン 2.0 で非推奨: 代わりに "isinstance(x,
   collections.Callable)" を使ってください。

   オブジェクト *obj* を関数のように呼び出すことができる場合真を返し、
   それ以外の場合偽を返します。関数、束縛および非束縛メソッド、クラス
   オブジェクト、および "__call__()" メソッドをサポートするインスタン
   スオブジェクトに対しては真を返します。

operator.isMappingType(obj)

   バージョン 2.7 で非推奨: 代わりに "isinstance(x,
   collections.Mapping)" を使ってください。

   オブジェクト *obj* がマップ型インタフェースをサポートする場合に真を
   返します。辞書および "__getitem__()" メソッドが定義された全てのイン
   スタンスオブジェクトに対しては、この値は真になります。

operator.isNumberType(obj)

   バージョン 2.7 で非推奨: 代わりに "isinstance(x, numbers.Number)"
   を使ってください。

   オブジェクト *obj* が数値を表現している場合に真を返します。 C で実
   装された全ての数値型対して、この値は真になります。

operator.isSequenceType(obj)

   バージョン 2.7 で非推奨: 代わりに "isinstance(x,
   collections.Sequence)" 使ってください。

   *obj* がシーケンス型プロトコルをサポートする場合に真を返します。シ
   ーケンス型メソッドを C で定義している全てのオブジェクトおよび
   "__getitem__()" メソッドが定義された全てのインスタンスオブジェクト
   に対して、この値は真になります。

"operator" モジュールは属性とアイテムの汎用的な検索のための道具も定義
しています。 "map()", "sorted()", "itertools.groupby()",  や関数を引数
に取るその他の関数に対して高速にフィールドを抽出する際に引数として使う
と便利です。

operator.attrgetter(attr)
operator.attrgetter(*attrs)

   演算対象から *attr* を取得する呼び出し可能なオブジェクトを返します
   。二つ以上の属性を要求された場合には、属性のタプルを返します。属性
   名はドットを含むこともできます。例えば:

   * "f = attrgetter('name')" とした後で、"f(b)" を呼び出すと
     "b.name" を返します。

   * "f = attrgetter('name', 'date')" とした後で、"f(b)" を呼び出す
     と "(b.name, b.date)" を返します。

   * "f = attrgetter('name.first', 'name.last')" とした後で、"f(b)"
     を 呼び出すと "(b.name.first, b.name.last)" を返します。

   次と等価です:

      def attrgetter(*items):
          if len(items) == 1:
              attr = items[0]
              def g(obj):
                  return resolve_attr(obj, attr)
          else:
              def g(obj):
                  return tuple(resolve_attr(obj, attr) for attr in items)
          return g

      def resolve_attr(obj, attr):
          for name in attr.split("."):
              obj = getattr(obj, name)
          return obj

   バージョン 2.4 で追加.

   バージョン 2.5 で変更: 複数のアトリビュートがサポートされました。

   バージョン 2.6 で変更: ドット付きアトリビュートがサポートされました
   。

operator.itemgetter(item)
operator.itemgetter(*items)

   演算対象からその "__getitem__()" メソッドを使って *item* を取得する
   呼び出し可能なオブジェクトを返します。 二つ以上のアイテムを要求され
   た場合には、アイテムのタプルを返します。例えば:

   * "f = itemgetter(2)" とした後で、"f(r)" を呼び出すと "r[2]" を返
     し ます。

   * "g = itemgetter(2, 5, 3)" とした後で、"g(r)" を呼び出すと
     "(r[2], r[5], r[3])" を返します。

   次と等価です:

      def itemgetter(*items):
          if len(items) == 1:
              item = items[0]
              def g(obj):
                  return obj[item]
          else:
              def g(obj):
                  return tuple(obj[item] for item in items)
          return g

   アイテムは被演算子の "__getitem__()" メソッドが受け付けるどんな型で
   も構いません。辞書ならば任意のハッシュ可能な値を受け付けます。リス
   ト、タプル、文字列などはインデクスかスライスを受け付けます:

   >>> itemgetter(1)('ABCDEFG')
   'B'
   >>> itemgetter(1,3,5)('ABCDEFG')
   ('B', 'D', 'F')
   >>> itemgetter(slice(2,None))('ABCDEFG')
   'CDEFG'

   バージョン 2.4 で追加.

   バージョン 2.5 で変更: 複数アイテム抽出がサポートされました.

   "itemgetter()" を使って特定のフィールドをタプルレコードから取り出す
   例:

   >>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
   >>> getcount = itemgetter(1)
   >>> map(getcount, inventory)
   [3, 2, 5, 1]
   >>> sorted(inventory, key=getcount)
   [('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]

operator.methodcaller(name[, args...])

   引数の *name* メソッドを呼び出す呼び出し可能オブジェクトを返します
   。追加の引数および/またはキーワード引数が与えられると、これらもその
   メソッドに引き渡されます。例えば:

   * "f = methodcaller('name')" とした後で、"f(b)" を呼び出すと
     "b.name()" を返します。

   * "f = methodcaller('name', 'foo', bar=1)" とした後で、"f(b)" を
     呼 び出すと "b.name('foo', bar=1)" を返します。

   次と等価です:

      def methodcaller(name, *args, **kwargs):
          def caller(obj):
              return getattr(obj, name)(*args, **kwargs)
          return caller

   バージョン 2.6 で追加.


9.9.1. 演算子から関数への対応表
===============================

下のテーブルでは、個々の抽象的な操作が、どのように Python 構文上の各演
算子や "operator" モジュールの関数に対応しているかを示しています。

+-------------------------+---------------------------+-----------------------------------------+
| 演算                    | 操作                      | 関数                                    |
+=========================+===========================+=========================================+
| 加算                    | "a + b"                   | "add(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| 結合                    | "seq1 + seq2"             | "concat(seq1, seq2)"                    |
+-------------------------+---------------------------+-----------------------------------------+
| 包含判定                | "obj in seq"              | "contains(seq, obj)"                    |
+-------------------------+---------------------------+-----------------------------------------+
| 除算                    | "a / b"                   | "div(a, b)" ("__future__.division" を使 |
|                         |                           | 用しない場合)                           |
+-------------------------+---------------------------+-----------------------------------------+
| 除算                    | "a / b"                   | "truediv(a, b)" ("__future__.division"  |
|                         |                           | 使用時)                                 |
+-------------------------+---------------------------+-----------------------------------------+
| 除算                    | "a // b"                  | "floordiv(a, b)"                        |
+-------------------------+---------------------------+-----------------------------------------+
| ビット単位論理積        | "a & b"                   | "and_(a, b)"                            |
+-------------------------+---------------------------+-----------------------------------------+
| ビット単位排他的論理和  | "a ^ b"                   | "xor(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| ビット単位反転          | "~ a"                     | "invert(a)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| ビット単位論理和        | "a | b"                   | "or_(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| べき乗                  | "a ** b"                  | "pow(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| 同一性                  | "a is b"                  | "is_(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| 同一性                  | "a is not b"              | "is_not(a, b)"                          |
+-------------------------+---------------------------+-----------------------------------------+
| インデクス指定の代入    | "obj[k] = v"              | "setitem(obj, k, v)"                    |
+-------------------------+---------------------------+-----------------------------------------+
| インデクス指定の削除    | "del obj[k]"              | "delitem(obj, k)"                       |
+-------------------------+---------------------------+-----------------------------------------+
| インデクス指定          | "obj[k]"                  | "getitem(obj, k)"                       |
+-------------------------+---------------------------+-----------------------------------------+
| 左シフト                | "a << b"                  | "lshift(a, b)"                          |
+-------------------------+---------------------------+-----------------------------------------+
| 剰余                    | "a % b"                   | "mod(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| 乗算                    | "a * b"                   | "mul(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| (算術) 負               | "- a"                     | "neg(a)"                                |
+-------------------------+---------------------------+-----------------------------------------+
| (論理) 否               | "not a"                   | "not_(a)"                               |
+-------------------------+---------------------------+-----------------------------------------+
| 正                      | "+ a"                     | "pos(a)"                                |
+-------------------------+---------------------------+-----------------------------------------+
| 右シフト                | "a >> b"                  | "rshift(a, b)"                          |
+-------------------------+---------------------------+-----------------------------------------+
| シーケンスの反復        | "seq * i"                 | "repeat(seq, i)"                        |
+-------------------------+---------------------------+-----------------------------------------+
| スライス指定の代入      | "seq[i:j] = values"       | "setitem(seq, slice(i, j), values)"     |
+-------------------------+---------------------------+-----------------------------------------+
| スライス指定の削除      | "del seq[i:j]"            | "delitem(seq, slice(i, j))"             |
+-------------------------+---------------------------+-----------------------------------------+
| スライス指定            | "seq[i:j]"                | "getitem(seq, slice(i, j))"             |
+-------------------------+---------------------------+-----------------------------------------+
| 文字列書式化            | "s % obj"                 | "mod(s, obj)"                           |
+-------------------------+---------------------------+-----------------------------------------+
| 減算                    | "a - b"                   | "sub(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| 真理値判定              | "obj"                     | "truth(obj)"                            |
+-------------------------+---------------------------+-----------------------------------------+
| 順序付け                | "a < b"                   | "lt(a, b)"                              |
+-------------------------+---------------------------+-----------------------------------------+
| 順序付け                | "a <= b"                  | "le(a, b)"                              |
+-------------------------+---------------------------+-----------------------------------------+
| 等価性                  | "a == b"                  | "eq(a, b)"                              |
+-------------------------+---------------------------+-----------------------------------------+
| 不等性                  | "a != b"                  | "ne(a, b)"                              |
+-------------------------+---------------------------+-----------------------------------------+
| 順序付け                | "a >= b"                  | "ge(a, b)"                              |
+-------------------------+---------------------------+-----------------------------------------+
| 順序付け                | "a > b"                   | "gt(a, b)"                              |
+-------------------------+---------------------------+-----------------------------------------+
