<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Split string by a regular expression</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.preg-replace.html">preg_replace</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.regex.html">POSIX Regex</a></div>
<div class="up"><a href="ref.pcre.html">PCRE Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.preg-split" class="refentry">
<div class="refnamediv">
<h1 class="refname">preg_split</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">preg_split</span> — <span class="dc-title">Split string by a regular expression</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.preg-split-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">array</span> <span class="methodname"><strong>preg_split</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$pattern</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$subject</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$limit</code><span class="initializer"> = -1</span></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$flags</code><span class="initializer"> = 0</span></span>
]] )</div>
<p class="para rdfs-comment">
Split the given string by a regular expression.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.preg-split-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">pattern</code></em></span>
<dd>
<p class="para">
The pattern to search for, as a string.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">subject</code></em></span>
<dd>
<p class="para">
The input string.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">limit</code></em></span>
<dd>
<p class="para">
If specified, then only substrings up to <em><code class="parameter">limit</code></em>
are returned with the rest of the string being placed in the last
substring. A <em><code class="parameter">limit</code></em> of -1, 0 or <strong><code>NULL</code></strong> means "no limit"
and, as is standard across PHP, you can use <strong><code>NULL</code></strong> to skip to the
<em><code class="parameter">flags</code></em> parameter.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">flags</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">flags</code></em> can be any combination of the following
flags (combined with the <em>|</em> bitwise operator):
<dl>
<dt>
<span class="term"><strong><code>PREG_SPLIT_NO_EMPTY</code></strong></span>
<dd>
<span class="simpara">
If this flag is set, only non-empty pieces will be returned by
<span class="function"><strong>preg_split()</strong></span>.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>PREG_SPLIT_DELIM_CAPTURE</code></strong></span>
<dd>
<span class="simpara">
If this flag is set, parenthesized expression in the delimiter pattern
will be captured and returned as well.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>PREG_SPLIT_OFFSET_CAPTURE</code></strong></span>
<dd>
<p class="para">
If this flag is set, for every occurring match the appendant string
offset will also be returned. Note that this changes the return
value in an array where every element is an array consisting of the
matched string at offset <em>0</em> and its string offset
into <em><code class="parameter">subject</code></em> at offset <em>1</em>.
</p>
</dd>
</dt>
</dl>
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.preg-split-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns an array containing substrings of <em><code class="parameter">subject</code></em>
split along boundaries matched by <em><code class="parameter">pattern</code></em>.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.preg-split-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>4.3.0</td>
<td>
The <strong><code>PREG_SPLIT_OFFSET_CAPTURE</code></strong> was added
</td>
</tr>
<tr>
<td>4.0.5</td>
<td>
The <strong><code>PREG_SPLIT_DELIM_CAPTURE</code></strong> was added
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.preg-split-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4802">
<p><strong>Example #1 <span class="function"><strong>preg_split()</strong></span> example : Get the parts of a search string</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// split the phrase by any number of commas or space characters,<br />// which include " ", \r, \t, \n and \f<br /></span><span style="color: #0000BB">$keywords </span><span style="color: #007700">= </span><span style="color: #0000BB">preg_split</span><span style="color: #007700">(</span><span style="color: #DD0000">"/[\s,]+/"</span><span style="color: #007700">, </span><span style="color: #DD0000">"hypertext language, programming"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$keywords</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[0] => hypertext
[1] => language
[2] => programming
)
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4803">
<p><strong>Example #2 Splitting a string into component characters</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$str </span><span style="color: #007700">= </span><span style="color: #DD0000">'string'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$chars </span><span style="color: #007700">= </span><span style="color: #0000BB">preg_split</span><span style="color: #007700">(</span><span style="color: #DD0000">'//'</span><span style="color: #007700">, </span><span style="color: #0000BB">$str</span><span style="color: #007700">, -</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">PREG_SPLIT_NO_EMPTY</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$chars</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[0] => s
[1] => t
[2] => r
[3] => i
[4] => n
[5] => g
)
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4804">
<p><strong>Example #3 Splitting a string into matches and their offsets</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$str </span><span style="color: #007700">= </span><span style="color: #DD0000">'hypertext language programming'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$chars </span><span style="color: #007700">= </span><span style="color: #0000BB">preg_split</span><span style="color: #007700">(</span><span style="color: #DD0000">'/ /'</span><span style="color: #007700">, </span><span style="color: #0000BB">$str</span><span style="color: #007700">, -</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">PREG_SPLIT_OFFSET_CAPTURE</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$chars</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Array
(
[0] => Array
(
[0] => hypertext
[1] => 0
)
[1] => Array
(
[0] => language
[1] => 10
)
[2] => Array
(
[0] => programming
[1] => 19
)
)
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.preg-split-notes">
<h3 class="title">Notes</h3>
<div class="tip"><strong class="tip">Tip</strong>
<p class="para">
If you don't need the power of regular expressions, you can choose
faster (albeit simpler) alternatives like <span class="function"><a href="function.explode.html" class="function">explode()</a></span>
or <span class="function"><a href="function.str-split.html" class="function">str_split()</a></span>.
</p>
</div>
<div class="tip"><strong class="tip">Tip</strong>
<p class="para">
If matching fails, an array with a single element containing the input string will be returned.
</p>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-function.preg-split-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><a href="pcre.pattern.html" class="link">PCRE Patterns</a></li>
<li class="member"> <span class="function"><a href="function.implode.html" class="function" rel="rdfs-seeAlso">implode()</a> - Join array elements with a string</span></li>
<li class="member"> <span class="function"><a href="function.preg-match.html" class="function" rel="rdfs-seeAlso">preg_match()</a> - Perform a regular expression match</span></li>
<li class="member"> <span class="function"><a href="function.preg-match-all.html" class="function" rel="rdfs-seeAlso">preg_match_all()</a> - Perform a global regular expression match</span></li>
<li class="member"> <span class="function"><a href="function.preg-replace.html" class="function" rel="rdfs-seeAlso">preg_replace()</a> - Perform a regular expression search and replace</span></li>
<li class="member"> <span class="function"><a href="function.preg-last-error.html" class="function" rel="rdfs-seeAlso">preg_last_error()</a> - Returns the error code of the last PCRE regex execution</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.preg-replace.html">preg_replace</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.regex.html">POSIX Regex</a></div>
<div class="up"><a href="ref.pcre.html">PCRE Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
