add dsu document(ja)

[universato]

DSUのドキュメントの日本語版を追加します。

本家ACLは、本体コードのライセンスは決まっていますが、ドキュメントの方は現在まだです。
ドキュメントのライセンスも本体コードと同じだろうと推定しています。

しかし、もし本家のドキュメントのライセンスが想定よりも厳しければ、本家ACLを見ながら書いたせいで全く同じ文言になっているところもあるので変更する必要があるかもしれないです。

書いてて思ったのですが、本家ACLmerge(a, b)と書くと頂点aと頂点bぽく見えすが、leader(a)と書くと配列ぽく見えるので、頂点の変数がvやwにしたい気持ちがあります。本家ドキュメントに寄せたい気持ちもあるので、いったん本家に合わせました。

[9sako6]

実装にあわせるため、戻り値を Integer にして「a, bが連結だった場合はその代表元、非連結だった場合は新たな代表元を返します」といった説明を追加するのはどうでしょうか。（本家より引用した文です。）

[universato]

そうですね。本家の実装と合わせるようにコードが書かれているので、その説明の通りです。
ただ、今回のPRでmergeだけ戻り値を書いてないのは忘れているわけではなく、色々思うことがあり、実はあえて書かなかったです。
というのも、「元から連結だから新たに連結しなかったときはfalseで、非連結から連結できたときはtrueを返す」仕様にした方が使い勝手が良いと考えており、実際そういう問題は思い浮かぶのですが(ABC120 D - Decayed Bridges)、反対にmerge実行後に代表元が欲しい問題が思い浮かばなかったです。

1. 本家ACLに真偽値を返すように要請してもし真偽値を返す実装に変更してもらったら、こちらも実装を変更したい。
2. 1. 本家の実装から離れて1-based indexにして、新たに連結したときは正の値で頂点番号を返して、そうでないときは負の値で頂点番号を返して情報量を増やす。
   2. 0-based indexのまま、新たに連結したときは非負整数で頂点番号を返し、そうでないときは負の数で頂点番号を返す。こちらは線対称にならないのが、微妙ですね。
3. 本家にはないmerge?メソッドを加えて、merge?は真偽値を返す実装にする。

まだこれ以外にも選択肢がありそうですが、3の実装がちょっとRubyぽくて良いかなと思いました。2は1つのメソッドで情報量が増えて一挙両得な感じもしますが、一般的じゃなくオシャレな感じがしないので否定的です。

[9sako6]

ありがとうございます。
一旦ドキュメントとしては何も書かないまたは本家に合わせる、のどちらかに倒しておいて、issueで DSU#merge の挙動を議論するのもありかなと思いました。

[kotatsugame]

3でmerge?メソッドを加えて、返す値は新しく連結したとき代表元、そうでないときfalseにしたら情報量もそこそこあって面白いと思います。

[universato]

ドキュメントは本家に合わせる方向にして、kotatsugameさんの方針でmerge?メソッドを付け加えるPRだそうと思います！ ありがとうございます！

【追記】
ちょっと書き忘れたのですが、nonzero?がnilとselfを返すので、falseと代表元(integer)を返すのRubyらしい感じがします。

[universato]

勝手に「使っている人もいたよな」と思いunionメソッドをエイリアスとして追加してましたが、
uniteメソッドというエイリアスがあれば十分で、unionという名詞は使って欲しくないと思ったので、削除しました。
なお、本家ACLがmergeで、蟻本はunite、螺旋本はlinkでした。螺旋本のlinkというメソッドもいいなと思いましたが、いったん見送りです。
そろそろいったんマージします。