Skip to content
ruby.help — home

Preview Ruby 4.1 is a preview. It can change before the final release. Switch to Ruby 4.0 →

instance method

String#split

(?::Regexp | ::string | nil pattern, ?::int limit) -> ::Array[::String]
(?::Regexp | ::string | nil pattern, ?::int limit) { (::String substring) -> void } -> self
split(field_sep = $;, limit = 0) → array_of_substrings
split(field_sep = $;, limit = 0) {|substring| ... } → self

Creates an array of substrings by splitting self at each occurrence of the given field separator field_sep.

With no arguments given, splits using the field separator $;, whose default value is nil.

With no block given, returns the array of substrings:

Example
'abracadabra'.split('a') # => ["", "br", "c", "d", "br"]

When field_sep is nil or ' ' (a single space), splits at each sequence of whitespace:

Example
'foo bar baz'.split(nil)          # => ["foo", "bar", "baz"]
'foo bar baz'.split(' ')          # => ["foo", "bar", "baz"]
"foo \n\tbar\t\n  baz".split(' ') # => ["foo", "bar", "baz"]
'foo  bar   baz'.split(' ')       # => ["foo", "bar", "baz"]
''.split(' ')                     # => []

When field_sep is an empty string, splits at every character:

Example
'abracadabra'.split('') # => ["a", "b", "r", "a", "c", "a", "d", "a", "b", "r", "a"]
''.split('')            # => []
'こんにちは'.split('')   # => ["こ", "ん", "に", "ち", "は"]

When field_sep is a non-empty string and different from ' ' (a single space), uses that string as the separator:

Example
'abracadabra'.split('a')  # => ["", "br", "c", "d", "br"]
'abracadabra'.split('ab') # => ["", "racad", "ra"]
''.split('a')             # => []
'こんにちは'.split('に')    # => ["こん", "ちは"]

When field_sep is a Regexp, splits at each occurrence of a matching substring:

Example
'abracadabra'.split(/ab/) # => ["", "racad", "ra"]
'1 + 1 == 2'.split(/\W+/) # => ["1", "1", "2"]
'abracadabra'.split(//)   # => ["a", "b", "r", "a", "c", "a", "d", "a", "b", "r", "a"]

If the Regexp contains groups, their matches are included in the returned array:

Example
'1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"]

Argument limit sets a limit on the size of the returned array; it also determines whether trailing empty strings are included in the returned array.

When limit is zero, there is no limit on the size of the array, but trailing empty strings are omitted:

Example
'abracadabra'.split('', 0)  # => ["a", "b", "r", "a", "c", "a", "d", "a", "b", "r", "a"]
'abracadabra'.split('a', 0) # => ["", "br", "c", "d", "br"]  # Empty string after last 'a' omitted.

When limit is a positive integer, there is a limit on the size of the array (no more than n - 1 splits occur), and trailing empty strings are included:

Example
'abracadabra'.split('', 3)   # => ["a", "b", "racadabra"]
'abracadabra'.split('a', 3)  # => ["", "br", "cadabra"]
'abracadabra'.split('', 30)  # => ["a", "b", "r", "a", "c", "a", "d", "a", "b", "r", "a", ""]
'abracadabra'.split('a', 30) # => ["", "br", "c", "d", "br", ""]
'abracadabra'.split('', 1)   # => ["abracadabra"]
'abracadabra'.split('a', 1)  # => ["abracadabra"]

When limit is negative, there is no limit on the size of the array, and trailing empty strings are included:

Example
'abracadabra'.split('', -1)  # => ["a", "b", "r", "a", "c", "a", "d", "a", "b", "r", "a", ""]
'abracadabra'.split('a', -1) # => ["", "br", "c", "d", "br", ""]

If a block is given, it is called with each substring and returns self:

Example
'foo bar baz'.split(' ') {|substring| p substring }

Output :

Example
"foo"
"bar"
"baz"

Note that the above example is functionally equivalent to:

Example
'foo bar baz'.split(' ').each {|substring| p substring }

Output :

Example
"foo"
"bar"
"baz"

But the latter:

  • Has poorer performance because it creates an intermediate array.

  • Returns an array (instead of self).

Related: see Converting to Non-String.

Ruby version changes

  1. 3.0
See also #slice! #squeeze #slice #squeeze! also in 4.0 · 3.4 · 3.3 · 3.2 · 3.1 · 3.0
‹ prev#slice! next ›#squeeze