names=flatten,flatten!
visibility=public
kind=defined

--- flatten(lv = nil)     -> Array
--- flatten!(lv = nil)    -> self | nil

flatten は自身を再帰的に平坦化した配列を生成して返します。flatten! は
自身を再帰的かつ破壊的に平坦化し、平坦化が行われた場合は self をそうでない
場合は nil を返します。
lv が指定された場合、lv の深さまで再帰的に平坦化します。

@param lv 平坦化の再帰の深さを整数で指定します。nil を指定した場合、再
          帰の深さの制限無しに平坦化します。
          整数以外のオブジェクトを指定した場合は to_int メソッドによる暗
          黙の型変換を試みます。

@raise TypeError 引数に整数以外の(暗黙の型変換が行えない)オブジェクトを
                 指定した場合に発生します。

@raise ArgumentError 配列要素が自身を含むような無限にネストした配列に対して flatten を呼んだ場合に発生します。

    # 自身を再帰的に平坦化する例。
    a = [1, [2, 3, [4], 5]]
    p a.flatten                     #=> [1, 2, 3, 4, 5]
    p a                             #=> [1, [2, 3, [4], 5]]

    # 自身を破壊的に平坦化する例。
    a = [[[1, [2, 3]]]]
    p a.flatten!                    #=> [1, 2, 3]
    p a                             #=> [1, 2, 3]

    # 平坦化が行われない場合は nil を返す。
    p [1, 2, 3].flatten!            #=> nil
 
    # 平坦化の再帰の深さを指定する例。
    a = [ 1, 2, [3, [4, 5] ] ]
    a.flatten(1)              #=> [1, 2, 3, [4, 5]]

