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

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

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

The "operator" module exports a set of efficient functions
corresponding to the intrinsic operators of Python.  For example,
"operator.add(x, y)" is equivalent to the expression "x+y". Many
function names are those used for special methods, without the double
underscores.  For backward compatibility, many of these have a variant
with the double underscores kept. The variants without the double
underscores are preferred for clarity.

これらの関数は、オブジェクト比較、論理演算、数学演算、シーケンス演算を
するものに分類されます。

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

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)

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

operator.truth(obj)

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

operator.is_(a, b)

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

operator.is_not(a, b)

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

operator.is_none(a)

   Return "a is None".  Tests object identity.

   Added in version 3.14.

operator.is_not_none(a)

   Return "a is not None".  Tests object identity.

   Added in version 3.14.

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

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)

   オブジェクト *obj* の概算の長さを返します。最初に実際の長さを、次に
   "object.__length_hint__()" を使って概算の長さを、そして最後にデフォ
   ルトの値を返そうとします。

   Added in version 3.4.

次の操作は呼び出し可能オブジェクト (callable) で動作します。

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

   "obj(*args, **kwargs)" を返します。

   Added in version 3.11.

The "operator" module also defines tools for generalized attribute and
item lookups.  These are useful for making fast field extractors as
arguments for "map()", "sorted()", "itertools.groupby()", or other
functions that expect a function argument.

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)

   演算対象からその "__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'
   >>> 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


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

This table shows how abstract operations correspond to operator
symbols in the Python syntax and the functions in the "operator"
module.

+-------------------------+---------------------------+-----------------------------------------+
| 演算                    | 操作                      | 関数                                    |
|=========================|===========================|=========================================|
| 加算                    | "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)"                          |
+-------------------------+---------------------------+-----------------------------------------+
| 同一性                  | "a is None"               | "is_none(a)"                            |
+-------------------------+---------------------------+-----------------------------------------+
| 同一性                  | "a is not None"           | "is_not_none(a)"                        |
+-------------------------+---------------------------+-----------------------------------------+
| インデクス指定の代入    | "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" と等価です。
