names=split
visibility=public
kind=defined

--- split(sep = $;, limit = 0) -> [String] | [[String]]

第 1 引数 sep で指定されたセパレータによって文字列を limit 個まで分割し、
結果を文字列の配列で返します。

第 1 引数 sep は以下のいずれかです。

: 正規表現
    正規表現にマッチする部分で分割する。
    特に、括弧によるグルーピングがあればそのグループにマッチした
    文字列も結果の配列に含まれる (後述)。
: 文字列
    その文字列自体にマッチする部分で分割する。
: 1 バイトの空白文字 ' '
    先頭と末尾の空白を除いたうえで、空白文字列で分割する。
: nil
    常に $; で分割する。 $; も nil の場合は、先頭と末尾の空白を除いたうえで、空白文字列で分割する。
: 空文字列 '' あるいは空文字列にマッチする正規表現
    文字列を 1 文字ずつに分割する。マルチバイト文字を認識する。

sep が正規表現で、かつその正規表現に括弧が含まれている場合には、
各括弧のパターンにマッチした文字列も配列に含まれます。
括弧が複数ある場合は、マッチしたものだけが配列に含まれます。

第 2 引数 limit は以下のいずれかです。

: limit > 0
     最大 limit 個の文字列に分割する
: limit == 0
     分割個数制限はなしで、配列末尾の空文字列を取り除く
: limit < 0
     分割個数の制限はなし

@param sep       文字列を分割するときのセパレータのパターン
@param limit     分割する最大個数

例:
    p "   a \t  b \n  c".split(/\s+/) # => ["", "a", "b", "c"]

    p "   a \t  b \n  c".split(nil)   # => ["a", "b", "c"]
    p "   a \t  b \n  c".split(' ')   # => ["a", "b", "c"]   # split(nil) と同じ
    p "   a \t  b \n  c".split        # => ["a", "b", "c"]   # split(nil) と同じ

    # 括弧を含む正規表現
    p '1-10,20'.split(/([-,])/)   # => ["1", "-", "10", ",", "20"]

    # 正規表現が空文字列にマッチする場合は 1 文字に分割
    p 'hi there'.split(/\s*/).join(':')  # => "h:i:t:h:e:r:e"

    # 文字列全体を 1 文字ずつに分割する例
    p 'hi there'.split(//).join(':')     # => "h:i: :t:h:e:r:e"

    # limit == 0 だと制限なく分割、配列末尾の空文字列は取り除かれる
    p "a,b,c,,,".split(/,/, 0)   # => ["a", "b", "c"]

    # limit 省略時は 0 と同じ (最もよく使われるパターン)
    p "a,b,c,,,".split(/,/)      # => ["a", "b", "c"]

    # 正の limit 使用例
    p "a,b,c,d,e".split(/,/, 1)  # => ["a,b,c,d,e"]
    p "a,b,c,d,e".split(/,/, 2)  # => ["a", "b,c,d,e"]
    p "a,b,c,d,e".split(/,/, 3)  # => ["a", "b", "c,d,e"]
    p "a,b,c,d,e".split(/,/, 4)  # => ["a", "b", "c", "d,e"]
    p "a,b,c,d,e".split(/,/, 5)  # => ["a", "b", "c", "d", "e"]
    p "a,b,c,d,e".split(/,/, 6)  # => ["a", "b", "c", "d", "e"]
    p "a,b,c,d,e".split(/,/, 7)  # => ["a", "b", "c", "d", "e"]

    # limit が負の数の場合は制限なく分割
    p "a,b,c,,,".split(/,/, -1)    # => ["a", "b", "c", "", "", ""]

@see [[m:String#partition]], [[m:String#rpartition]]

