Regex.Split Method (String, Int32, Int32)

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. The search for the regular expression pattern starts at a specified character position in the input string.

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

public string[] Split(
	string input,
	int count,
	int startat
)

Parameters

input
Type: System.String

The string to be split.

count
Type: System.Int32

The maximum number of times the split can occur.

startat
Type: System.Int32

The character position in the input string where the search will begin.

Return Value

Type: System.String[]
An array of strings.

ExceptionCondition
ArgumentNullException

input is null.

ArgumentOutOfRangeException

startat is less than zero or greater than the length of input.

RegexMatchTimeoutException

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 is 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. The startat parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space).

If no matches are found from the count+1 position in the string, the method returns a one-element array that contains the input string. If one or more matches are found, the first element of the returned array contains the first portion of the string from the first character up to one character before the match.

If multiple matches are adjacent to one another and the number of matches found is at least two less than count, an empty string is inserted into the array. Similarly, if a match is found at startat, which is the first character in the string, the first element of the returned array is an empty string. That is, empty strings that result from adjacent matches are counted in determining whether the number of matched substrings equals count. In the following example, the regular expression \d+ is used to find the starting position of the first substring of numeric characters in a string, and then to split the string a maximum of three times starting at that position. Because the regular expression pattern matches the beginning of the input string, the returned string array consists of an empty string, a five-character alphabetic string, and the remainder of the string,

using System;
using System.Text.RegularExpressions;

public class Example
{
   public static void Main()
   {
      string pattern = @"\d+";
      Regex rgx = new Regex(pattern);
      string input = "123ABCDE456FGHIJ789KLMNO012PQRST";
      Match m = rgx.Match(input);
      if (m.Success) { 
         int startAt = m.Index;
         string[] result = rgx.Split(input, 3, startAt);
         for (int ctr = 0; ctr < result.Length; ctr++) {
            Console.Write("'{0}'", result[ctr]);
            if (ctr < result.Length - 1)
               Console.Write(", ");
         }
         Console.WriteLine();
      }
   }
}
// The example displays the following output: 
//       '', 'ABCDE', 'FGHIJKL789MNOPQ012'

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-pomegranate-pineapple-peach" into a maximum of four substrings beginning at character 15 in the string results in a seven-element array, as the following code shows.

Imports System.Text.RegularExpressions

Module Example
   Public Sub Main()
      Dim pattern As String = "(-)" 
      Dim input As String = "apple-apricot-plum-pear-pomegranate-pineapple-peach" 

      Dim regex As Regex = New Regex(pattern)    
      ' Split on hyphens from 15th character on 
      Dim substrings() As String = regex.Split(input, 4, 15)
      For Each match As String In substrings
         Console.WriteLine("'{0}'", match)
      Next 
   End Sub   
End Module 
' The example displays the following output: 
'    'apple-apricot-plum' 
'    '-' 
'    'pear' 
'    '-' 
'    'pomegranate' 
'    '-' 
'    'pineapple-peach'      

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 .NET Framework 1.0 and 1.1, if a match is not found within the first set of capturing parentheses, captured text from additional capturing parentheses is not included in the returned array. Starting with the .NET Framework 2.0, all captured text is also added to the returned array. For example, the following code uses two sets of capturing parentheses to extract the individual words in a string. The first set of capturing parentheses captures the hyphen, and the second set captures the vertical bar. If the example code is compiled and run under the .NET Framework 1.0 or 1.1, it excludes the vertical bar characters; if it is compiled and run under the .NET Framework 2.0 or later versions, it includes them.

using System;
using System.Text.RegularExpressions;

public class Example
{
   public static void Main()
   {
      string pattern = "(-)|([|])";     // possible delimiters found in string 
      string input = "apple|apricot|plum|pear|pomegranate|pineapple|peach";

      Regex regex = new Regex(pattern);    
      // Split on delimiters from 15th character on 
      string[] substrings = regex.Split(input, 4, 15);
      foreach (string match in substrings)
      {
         Console.WriteLine("'{0}'", match);
      }
   }
}
// In .NET 2.0 and later, the method returns an array of 
// 7 elements, as follows: 
//    apple|apricot|plum' 
//    '|' 
//    'pear' 
//    '|' 
//    'pomegranate' 
//    '|' 
//    'pineapple|peach' 
// In .NET 1.0 and 1.1, the method returns an array of 
// 4 elements, as follows: 
//    'apple|apricot|plum' 
//    'pear' 
//    'pomegranate' 
//    'pineapple|peach'

If the regular expression can match the empty string, Split 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 the input string contains, starting with the character "a". Because the null string matches the end of the input string, a null string is inserted at the end of the returned array.

using System;
using System.Text.RegularExpressions;

public class Example
{
   public static void Main()
   {
      string input = "characters";
      Regex regex = new Regex("");
      string[] substrings = regex.Split(input, input.Length, input.IndexOf("a"));
      Console.Write("{");
      for(int ctr = 0; ctr < substrings.Length; ctr++)
      {
         Console.Write(substrings[ctr]);
         if (ctr < substrings.Length - 1)
            Console.Write(", ");
      }
      Console.WriteLine("}");
   }
}
// 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

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft