Regex::Split Method (String^, Int32)


The .NET API Reference documentation has a new home. Visit the .NET API Browser on to see the new experience.

Splits an input string a specified maximum number of times into an array of substrings, at the positions defined by a regular expression specified in the Regex constructor.

Namespace:   System.Text.RegularExpressions
Assembly:  System (in System.dll)

array<String^>^ Split(
	String^ input,
	int count


Type: System::String^

The string to be split.

Type: System::Int32

The maximum number of times the split can occur.

Return Value

Type: array<System::String^>^

An array of strings.

Exception Condition

input is null.


A time-out occurred. For more information about time-outs, see the Remarks section.

The Regex::Split methods are similar to the String::Split method, except that Regex::Split splits the string at a delimiter determined by a regular expression instead of a set of characters. The count parameter specifies the maximum number of substrings into which the input string can be split; the last string contains the unsplit remainder of the string. A count value of zero provides the default behavior of splitting as many times as possible.

If multiple matches are adjacent to one another or if a match is found at the beginning or end of input, and the number of matches found is at least two less than count, an empty string is inserted into the array. That is, empty strings that result from adjacent matches or from matches at the beginning or end of the input string are counted in determining whether the number of matched substrings equals count. In the following example, the regular expression /d+ is used to split an input string that includes one or more decimal digits into a maximum of three substrings. Because the beginning of the input string matches the regular expression pattern, the first array element contains String::Empty, the second contains the first set of alphabetic characters in the input string, and the third contains the remainder of the string that follows the third match.

No code example is currently available or this language may not be supported.

If capturing parentheses are used in a regular expression, any captured text is included in the array of split strings. However, any array elements that contain captured text are not counted in determining whether the number of matches has reached count. For example, splitting the string "apple-apricot-plum-pear-banana" into a maximum of four substrings results in a seven-element array, as the following code shows.

No code example is currently available or this language may not be supported.

However, when the regular expression pattern includes multiple sets of capturing parentheses, the behavior of this method depends on the version of the .NET Framework. In the .NET Framework 1.0 and 1.1, only captured text from the first set of capturing parentheses is included in the returned array. Starting with the .NET Framework 2.0, all captured text is added to the returned array. However, elements in the returned array that contain captured text are not counted in determining whether the number of matched substrings equals count. For example, in the following code, a regular expression uses two sets of capturing parentheses to extract the elements of a date from a date string. The first set of capturing parentheses captures the hyphen, and the second set captures the forward slash. The call to the Split(String^, Int32) method then specifies a maximum of two elements in the returned array. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, the method returns a two-element string array. If it is compiled and run under the .NET Framework 2.0 or later versions, the method returns a three-element string array.

No code example is currently available or this language may not be supported.

If the regular expression can match the empty string, Split(String^, Int32) will split the string into an array of single-character strings because the empty string delimiter can be found at every location. The following example splits the string "characters" into as many elements as there are in the input string. Because the null string matches the beginning of the input string, a null string is inserted at the beginning of the returned array. This causes the tenth element to consist of the two characters at the end of the input string.

Imports System.Text.RegularExpressions

Module Example
   Public Sub Main()
      Dim input As String = "characters"
      Dim regex As New Regex("")
      Dim substrings() As String = regex.Split(input, input.Length)
      For ctr As Integer = 0 to substrings.Length - 1
         if ctr < substrings.Length - 1 Then Console.Write(", ")
   End Sub
End Module
' The example displays the following output:   
'    {, c, h, a, r, a, c, t, e, rs}

The RegexMatchTimeoutException exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the Regex::Regex(String^, RegexOptions, TimeSpan) constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the Regex object is created. If no time-out is defined in the Regex constructor call or in the application domain's properties, or if the time-out value is Regex::InfiniteMatchTimeout, no exception is thrown

Universal Windows Platform
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top