"operator" --- Standard operators as functions
**********************************************

**ソースコード:** Lib/operator.py

======================================================================

"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" と等価です。これらの関数はどのような値を
   返してもよく、ブール値として解釈できてもできなくてもかまいません。
   拡張比較の詳細については 比較 を参照してください。

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

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

   Return the outcome of "not" *obj*.  (Note that there is no
   "__not__()" method for object instances; only the interpreter core
   defines this operation.  The result is affected by the "__bool__()"
   and "__len__()" methods.)

operator.truth(obj)

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

operator.is_(a, b)

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

operator.is_not(a, b)

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

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

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.floordiv(a, b)
operator.__floordiv__(a, b)

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

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

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

   バージョン 3.10 で変更: 結果は常に厳密な "int" 型です。 以前は、結
   果は "int" のサブクラスのインスタンスのこともありました。

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

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

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.matmul(a, b)
operator.__matmul__(a, b)

   "a @ b" を返します。

   Added in version 3.5.

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" を返します。

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)

   2/3 が 0 ではなく 0.66 となるような "a / b"  を返します。 "真の" 除
   算としても知られています。

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" の判定結果を返します。被演算子が左右反転しているので注意し
   てください。

operator.countOf(a, b)

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

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

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

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

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

operator.indexOf(a, b)

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

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

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

operator.length_hint(obj, default=0)

   Return an estimated length for the object *obj*. First try to
   return its actual length, then an estimate using
   "object.__length_hint__()", and finally return the default value.

   Added in version 3.4.

The following operation works with callables:

operator.call(obj, /, *args, **kwargs)
operator.__call__(obj, /, *args, **kwargs)

   Return "obj(*args, **kwargs)".

   Added in version 3.11.

"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 any(not isinstance(item, str) for item in items):
              raise TypeError('attribute name must be a string')
          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

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

   Return a callable object that fetches *item* from its operand using
   the operand's "__getitem__()" method.  If multiple items are
   specified, returns a tuple of lookup values.  For example:

   * "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

   The items can be any type accepted by the operand's "__getitem__()"
   method.  Dictionaries accept any *hashable* value.  Lists, tuples,
   and strings accept an index or a slice:

   >>> itemgetter(1)('ABCDEFG')
   'B'
   >>> itemgetter(1, 3, 5)('ABCDEFG')
   ('B', 'D', 'F')
   >>> itemgetter(slice(2, None))('ABCDEFG')
   'CDEFG'
   >>> soldier = dict(rank='captain', name='dotterbart')
   >>> itemgetter('rank')(soldier)
   'captain'

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

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

operator.methodcaller(name, /, *args, **kwargs)

   引数の *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


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

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

+-------------------------+---------------------------+-----------------------------------------+
| 演算                    | 操作                      | 関数                                    |
|=========================|===========================|=========================================|
| 加算                    | "a + b"                   | "add(a, b)"                             |
+-------------------------+---------------------------+-----------------------------------------+
| 結合                    | "seq1 + seq2"             | "concat(seq1, seq2)"                    |
+-------------------------+---------------------------+-----------------------------------------+
| 包含判定                | "obj in seq"              | "contains(seq, obj)"                    |
+-------------------------+---------------------------+-----------------------------------------+
| 除算                    | "a / b"                   | "truediv(a, b)"                         |
+-------------------------+---------------------------+-----------------------------------------+
| 除算                    | "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 @ b"                   | "matmul(a, b)"                          |
+-------------------------+---------------------------+-----------------------------------------+
| (算術) 負               | "- a"                     | "neg(a)"                                |
+-------------------------+---------------------------+-----------------------------------------+
| (論理) 否               | "not a"                   | "not_(a)"                               |
+-------------------------+---------------------------+-----------------------------------------+
| 正                      | "+ a"                     | "pos(a)"                                |
+-------------------------+---------------------------+-----------------------------------------+
| 右シフト                | "a >> b"                  | "rshift(a, b)"                          |
+-------------------------+---------------------------+-----------------------------------------+
| スライス指定の代入      | "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)"                              |
+-------------------------+---------------------------+-----------------------------------------+


インプレース (in-place) 演算子
==============================

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

なお、これらの例では、インプレースメソッドが呼び出されたとき、計算と代
入は二段階に分けて行われます。以下に挙げるインプレース関数は、インプレ
ースメソッドを呼び出してその第一段階だけを行います。第二段階の代入は扱
われません。

文字列、数、タプルのようなイミュータブルなターゲットでは、更新された値
が計算されますが、入力変数に代入し返されはしません。

>>> a = 'hello'
>>> iadd(a, ' world')
'hello world'
>>> a
'hello'

リストや辞書のようなミュータブルなターゲットでは、インプレースメソッド
は更新を行うので、その後に代入をする必要はありません。

>>> s = ['h', 'e', 'l', 'l', 'o']
>>> iadd(s, [' ', 'w', 'o', 'r', 'l', 'd'])
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
>>> s
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']

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

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

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

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

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

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

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

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

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

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

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

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

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

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

operator.imatmul(a, b)
operator.__imatmul__(a, b)

   "a = imatmul(a, b)" は "a @= b" と等価です。

   Added in version 3.5.

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

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

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

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

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

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

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

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

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

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

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

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