########################################################################
#                                                                      #
#   finite-map.rb                                                      #
#                                                                      #
########################################################################
=begin
[((<index-ja|URL:index-ja.html>))] 
[((<finite-set-ja|URL:finite-set-ja.html>))] 
((<Algebra::Map>))

= Algebra::Map
((*写像クラス*))

写像を表現するクラスです。

== ファイル名:
* ((|finite-map.rb|))

== スーパークラス:
* ((|Set|))

== インクルードしているモジュール:

* ((|Powers|))

== クラスメソッド:

--- ::[]([x0 => y0, [x1 => y1, [x2 => y2, ...]]])
    ((|x0|)) の時 ((|y0|)), ((|x1|)) の時 ((|y1|)), ((|x2|)) の時 ((|y2|)),..
    という値を持つ写像を返します。
    
    例: 
      require "finite-map"
      include Algebra
      p Map[0 => 10, 1 => 11, 2 => 12]         #=> {0 => 10, 1 => 11, 2 => 12}
      p Map[{0 => 10, 1 => 11, 2 => 12}]       #=> {0 => 10, 1 => 11, 2 => 12}
      p Map.new(0 => 10, 1 => 11, 2 => 12)     #=> {0 => 10, 1 => 11, 2 => 12}
      p Map.new({0 => 10, 1 => 11, 2 => 12})   #=> {0 => 10, 1 => 11, 2 => 12}
      p Map.new_a([0, 10, 1, 11, 2, 12])       #=> {0 => 10, 1 => 11, 2 => 12}

--- ::new([x0 => y0, [x1 => y1, [x2 => y2, ...]]])
    ((|x0|)) の時 ((|y0|)), ((|x1|)) の時 ((|y1|)), ((|x2|)) の時 ((|y|)),..
    という値を持つ写像を返します。((<::[]>)) と同じです。

--- ::new_a(a)
    配列 a の偶数番目を定義域の元、奇数番目を値域の元として定義される
    写像を生成します。

--- ::phi([t])
    空写像（定義域が空集合である写像）を返します。集合 ((|t|)) を
    引数にすると、それを定義域 ((<target>)) にします。

    例: 
      p Map.phi #=> {}
      p Map.phi(Set[0, 1]) #=> {}
      p Map.phi(Set[0, 1]).target #=> {0, 1}

--- ::empty_set
    ((<::phi>)) のエイリアスです。

--- ::singleton(x, y)
    ただ一つの元で構成される集合 (({{x}})) 上で定義された ((|y|)) という
    値を取る関数を返します。


== メソッド:

--- target=(s)
    写像の値域を ((|s|)) に設定します。((<surjective?>)) などに
    利用されます。

--- codomain=(s)
    ((<target=>)) のエイリアスです。

--- target
    写像の値域を返します。

--- codomain
    ((<target>)) のエイリアスです。

--- source
    写像の定義域を返します。

    例: 
      require "finite-map"
      include Algebra
      m = Map[0 => 10, 1 => 11, 2 => 12]
      p m.source #=> {0, 1, 2}
      p m.target #=> nil
      m.target = Set[10, 11, 12, 13]
      p m.target #=> {10, 11, 12, 13}

--- domain
    ((<source>)) のエイリアスです。

--- phi([t])
    値域を ((|t|)) とする空の写像を返します。

--- empty_set
--- null
    ((<phi>)) のエイリアスです。

--- call(x)
    写像の ((|x|)) における値を返します。

--- act
--- []
    ((<call>)) のエイリアスです。

--- each
    すべての (({[原像, 像]})) について繰り返すイテレータです。

    例: 
      require "finite-map"
      include Algebra
      Map[0 => 10, 1 => 11, 2 => 12].each do |x, y|
        p [x, y] #=> [1, 11], [0, 10], [2, 12]
      end

--- compose(other)
    ((|self|)) と ((|other|)) の合成写像を返します。

    例: 
      require "finite-map"
      include Algebra
      f = Map.new(0 => 10, 1 => 11, 2 => 12)
      g = Map.new(10 => 20, 11 => 21, 12 => 22)
      p g * f #=> {0 => 20, 1 => 21, 2 => 22}

--- *
    ((<compose>)) のエイリアスです。

--- dup
    自身の複製を返します。値域の値も返します。

--- append!(x, y)
    ((|x|)) で ((|y|)) という値を取るように設定します。

    例: 
      require "finite-map"
      include Algebra
      m = Map[0 => 10, 1 => 11]
      m.append!(2, 12)
      p m #=> {0 => 10, 1 => 11, 2 => 12}

--- []=(x, y)
    ((<append!>)) のエイリアスです。

--- append(x, y)
    ((<dup>)) の後、((<append!>))(x, y) したものを返します。

--- include?(x)
    ((|x|)) が定義域に含まれるとき真を返します。

--- contains?(x)
    ((<include?>)) のエイリアスです。

--- member?(a)
    ((|a|)) を配列 (({[x, y]})) としたとき、((|x|)) における値が
    ((|y|)) となるとき、真を返します。

    例: 
      require "finite-map"
      include Algebra
      m = Map[0 => 10, 1 => 11]
      p m.include?(1)  #=> true
      p m.member?([1, 11]) #=> true

--- has?
    member? のエイリアスです。

--- image([s])
    写像の像を返します。定義域の部分集合 ((|s|)) が与えられれば、
    ((|s|)) の像を返します。

--- inv_image(s)
    集合 ((|s|)) の原像を返します。

--- map_s
    写像の各 [原像, 像] のペアについて繰り返し、ブロックで得た
    値の集合を返します。

    例: 
      require "finite-map"
      include Algebra
      p Map.new(0 => 10, 1 => 11, 2 => 12).map_s{|x, y| y - 2*x}
      #=> Set[10, 9, 8]

--- map_m
    写像の各 [原像, 像] のペアについて繰り返し、ブロックで得た
    値の配列で構成される写像を返します。

    例: 
      require "finite-map"
      include Algebra
      p Map.new(0 => 10, 1 => 11, 2 => 12).map_m{|x, y| [y, x]}
      #=> {10 => 0, 11 => 1, 12 => 2}

--- inverse
    逆写像を返します。

--- inv_coset
    各像に逆像の集合を対応させる写像を返します。

    例: 
      require "finite-map"
      include Algebra
      m = Map[0=>0, 1=>0, 2=>2, 3=>2, 4=>0]
      p m.inv_coset #=> {0=>{0, 1, 4}, 2=>{2, 3}}
      m.codomain = Set[0, 1, 2, 3]
      p m.inv_coset #=> {0=>{0, 1, 4}, 1=>{}, 2=>{2, 3}, 3=>{}}

--- indentity?
    恒等写像であるとき、真を返します。

--- surjective?
    全射である時、真を返します。あらかじめ ((<target>)) が指定されて
    いる必要があります。

--- injective?
    単射である時、真を返します。

--- bijective?
    全単射である時、真を返します。あらかじめ ((<target>)) が指定されて
    いる必要があります。

=end