about_Split

TOPIC
	about_Split

SHORT DESCRIPTION
	Explains how to use the split operator to split one or more strings into
	substrings. 

LONG DESCRIPTION
	The split operator splits one or more strings into substrings. You can
	change the following elements of the split operation:
	
		-- Delimiter. The default is whitespace, but you can specify characters,
		 strings, patterns, or script blocks that specify the delimiter.
	
		-- Maximum number of substrings. The default is to return all substrings. If 
		 you specify a number less than the number of substrings, the remaining
		 substrings are concatenated in the last substring. 

		-- Options that specify the conditions under which the delimiter is matched,
		 such as SimpleMatch and Multiline. 


  SYNTAX

   The following diagram shows the syntax for the -split operator.

   The parameter names do not appear in the command. Include only the
   parameter values. The values must appear in the order specified in the
   syntax diagram.

		-Split <String>

		<String> -Split <Delimiter>[,<Max-substrings>[,"<Options>"]]

		<String> -Split {<ScriptBlock>} [,<Max-substrings>]

   In any split statement, you can substitute -iSplit or -cSplit for -split.
   The -iSplit and -split operators are case-insensitive. The -cSplit operator
   is case-sensitive, meaning that case is considered when the delimiter rules
   are applied.


  PARAMETERS

   <String>
		Specifies one or more strings to be split. If you submit multiple
		strings, all the strings are split using the same delimiter rules.
		Example:

			-split "red yellow blue green"
			red
			yellow
			blue
			green

   <Delimiter>
		The characters that identify the end of a substring. The default
		delimiter is whitespace, including spaces and non-printable characters, such
		as newline (`n) and tab (`t). When the strings are split, the delimiter
		is omitted from all the substrings. Example:

			"Lastname:FirstName:Address" -split ":"
			Lastname
			FirstName
			Address
	
	<Max-substrings>
		Specifies the maximum number of substrings returned. The default is
		all the substrings split by the delimiter. If there are more substrings, 
		they are concatenated to the final substring. If there are fewer 
		substrings, all the substrings are returned. A value of 0 and negative values return
		all the substrings.

		If you submit more than one string (an array of strings) to the split operator ,
		the Max-substrings limit is applied to each string separately. Example:

			$c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune"
			$c -split ",", 5
			Mercury
			Venus
			Earth
			Mars
			Jupiter,Saturn,Uranus,Neptune
	

	<ScriptBlock>
		An expression that specifies rules for applying the delimiter. The
		expression must evaluate to $true or $false. Enclose the script 
		block in braces. Example:
	
			$c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune"
			$c -split {$_ -eq "e" -or $_ -eq "p"}
			M
			rcury,V
			nus,Earth,Mars,Ju
			it
			r,Saturn,Uranus,N
	
			tun

	<Options>
		Enclose the option name in quotation marks. Options are valid only
		when the <Max-substrings> parameter is used in the statement.

		The syntax for the Options parameter is:

			"SimpleMatch [,IgnoreCase]"

			"[RegexMatch] [,IgnoreCase] [,CultureInvariant]
			[,IgnorePatternWhitespace] [,ExplicitCapture] 
			[,Singleline | ,Multiline]"

 
		The SimpleMatch options are:
			
		-- SimpleMatch: Use simple string comparison when evaluating the
			 delimiter. Cannot be used with RegexMatch.

		-- IgnoreCase: Forces case-insensitive matching, even if the -cSplit 
			 operator is specified.


		The RegexMatch options are:

		-- RegexMatch: Use regular expression matching to evaluate the
			 delimiter. This is the default behavior. Cannot be used with
			 SimpleMatch.

		-- IgnoreCase: Forces case-insensitive matching, even if the -cSplit 
			 operator is specified.

		-- CultureInvariant: Ignores cultural differences in language
			 when evaluting the delimiter. Valid only with RegexMatch.

		-- IgnorePatternWhitespace: Ignores unescaped whitespace and
			 comments marked with the number sign (#). Valid only with 
			 RegexMatch.

		-- Multiline: Multiline mode recognizes the start and end of lines 
			 and strings. Valid only with RegexMatch. Singleline is the default.

		-- Singleline: Singleline mode recognizes only the start and end of
			 strings. Valid only with RegexMatch. Singleline is the default.

		-- ExplicitCapture: Ignores non-named match groups so that only
			 explicit capture groups are returned in the result list. Valid
			 only with RegexMatch.
	

  UNARY and BINARY SPLIT OPERATORS

	The unary split operator (-split <string>) has higher precedence than a 
	comma. As a result, if you submit a comma-separated list of strings to the
	unary split operator, only the first string (before the first comma) is 
	split.

	To split more than one string, use the binary split operator 
	(<string> -split <delimiter>). Enclose all the strings in parentheses,
	or store the strings in a variable, and then submit the variable to the
	split operator.

	Consider the following example:

		-split "1 2", "a b"
		1
		2
		a b


		"1 2", "a b" -split " "
		1
		2
		a
		b


		-split ("1 2", "a b")
		1
		2
		a
		b

		$a = "1 2", "a b"
		-split $a
		1
		2
		a
		b


  EXAMPLES

	The following statement splits the string at whitespace.

		C:\PS> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting"

		Windows
		PowerShell
		2.0
		Windows
		PowerShell
		with
		remoting


	The following statement splits the string at any comma.

		C:\PS> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ','

		Mercury
		Venus
		Earth 
		Mars
		Jupiter
		Saturn
		Uranus
		Neptune


	The following statement splits the string at the pattern "er".

		C:\PS>"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er'

		M
		cury,Venus,Earth,Mars,Jupit
		,Saturn,Uranus,Neptune



	The following statement performs a case-sensitive split at the 
	letter "N".

		C:\PS> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N'

		Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,
		eptune



	The following statement splits the string at "e" and "t".

		C:\PS> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]'

		M
		rcury,V
		nus,
		ar
		h,Mars,Jupi

		r,Sa
		urn,Uranus,N
		p
		un


	The following statement splits the string at "e" and "r", but limits the
	resulting substrings to six substrings.

		C:\PS> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6

		M

		cu
		y,V
		nus,
		arth,Mars,Jupiter,Saturn,Uranus,Neptune



	The following statement splits a string into three substrings. 
	
		C:\PS> "a,b,c,d,e,f,g,h" -split ",", 3

		a
		b
		c,d,e,f,g,h


	The following statement splits two strings into three substrings. 
	(The limit is applied to each string independently.)
	
		C:\PS> "a,b,c,d", "e,f,g,h" -split ",", 3

		a
		b
		c,d
		e
		f
		g,h


	The following statement splits each line in the here-string at the
	first digit. It uses the Multiline option to recognize the beginning
	of each line and string.

	The 0 represents the "return all" value of the Max-substrings parameter. You can
	use options, such as Multiline, only when the Max-substrings value
	is specified.

		C:\PS> $a = @'
		1The first line.
		2The second line.
		3The third of three lines.
		'@
	
		C:\PS> $a -split "^\d", 0, "multiline"
	
		The first line.


		The second line.


		The third of three lines.



	The following statement uses the SimpleMatch option to direct the -split 
	operator to interpret the dot (.) delimiter literally. 

	With the default, RegexMatch, the dot enclosed in quotation marks (".") is 
	interpreted to match any character except for a newline character. As a 
	result, the split statement returns a blank line for every character except
	newline.

	The 0 represents the "return all" value of the Max-substrings parameter. 
	You can use options, such as SimpleMatch, only when the Max-substrings 
	value is specified.

		C:\PS> "This.is.a.test" -split ".", 0, "simplematch"

		This
		is
		a 
		test



	The following statement splits the string at one of two delimiters, 
	depending on the value of a variable.

		C:\PS>  $i = 1
		C:\PS>  $c = "LastName, FirstName; Address, City, State, Zip"
		C:\PS>  $c -split {if ($i -lt 1) {$_ -eq ","} else {$_ -eq ";"}}

		LastName, FirstName
		 Address, City, State, Zip
			
	

	The following split statements split an XML file first at the angle bracket
	and then at the semicolon. The result is a readable version of the XML
	file.

		C:\PS>  get-process powershell | export-clixml ps.xml
		C:\PS>  $x = import-clixml ps.xml
		C:\PS>  $x = $x -split "<"
		C:\PS>  $x = $x -split ";"


	To display the result, type "$x".
	
		C:\PS> $x

		@{__NounName=Process
		Name=powershell
		Handles=428
		VM=150081536
		WS=34840576
		PM=36253696
		...


SEE ALSO
	Split-Path
	about_Operators
	about_Comparison_Operators
	about_Join