diff --git a/doc/filters/split.rst b/doc/filters/split.rst index 287f82392..14faf1fa3 100644 --- a/doc/filters/split.rst +++ b/doc/filters/split.rst @@ -1,16 +1,37 @@ ``split`` ======== -The ``split`` filter returns a list of items from a string that's separated by the provided delimiter or glue: +The ``split`` filter returns a list of items from a string that's separated by the provided delimiter: .. code-block:: jinja {{ "one,two,three"|split(',') }} {# returns [one, two, three] #} -A limit parameter is available which the returned list will contain a maximum of limit elements with the last element containing the rest of string. +A limit parameter is available which the returned list will contain a maximum of limit elements with the last element containing the rest of string. +If limit is set and positive, the returned array will contain a maximum of limit elements with the last element containing the rest of string. +If the limit parameter is negative, all components except the last -limit are returned. +If the limit parameter is zero, then this is treated as 1. .. code-block:: jinja {{ "one,two,three,four,five"|split(',', 3) }} {# returns [one, two, "three,four,five"] #} + +If delimiter is an empty string, then value will be splitted by equal chunks. Length is set by limit parameter (1 char by default). + +.. code-block:: jinja + + {{ "123"|split('') }} + {# returns [1, 2, 3] #} + + {{ "aabbcc"|split('', 2) }} + {# returns [aa, bb, cc] #} + +.. note:: + + Internally, Twig uses the PHP `explode`_ or `str_split`_ (if delimiter is empty) functions for string splitting. + +.. _`explode`: http://php.net/explode + +.. _`str_split`: http://php.net/str_split diff --git a/lib/Twig/Extension/Core.php b/lib/Twig/Extension/Core.php index 87b3a63d4..fe4652d44 100644 --- a/lib/Twig/Extension/Core.php +++ b/lib/Twig/Extension/Core.php @@ -652,9 +652,11 @@ function twig_join_filter($value, $glue = '') } /** - * Splits the values into an array. + * Splits the string into an array. * * The second parameter is option for the limit. + * If delimiter is an empty string, then string is split by equal chunks. Chunk length is 1 char by default, or set + * by limit * *
* {{ "one,two,three"|split(',') }}
@@ -662,25 +664,27 @@ function twig_join_filter($value, $glue = '')
*
* {{ "one,two,three,four,five"|split(',', 3) }}
* {# returns [one, two, "three,four,five"] #}
+ *
+ * {{ "123"|split('') }}
+ * {# returns [1, 2, 3] #}
+ *
+ * {{ "aabbcc"|split('', 2) }}
+ * {# returns [aa, bb, cc] #}
*
*
- * @param string $value A string
+ * @param string $value A string
* @param string $delimiter The separator to explode by
- * @param integer $limit The limit
+ * @param integer $limit The limit
*
* @return string The explode'ed string
*/
function twig_split_filter($value, $delimiter, $limit = null)
{
- if (is_empty($delimiter)) {
- throw new Twig_Error_Runtime('The string to split must be provided with a delimiter.');
+ if (empty($delimiter)) {
+ return str_split($value, null === $limit ? 1 : $limit);
}
- if (!is_null($limit)) {
- return explode($delimiter, $value, $limit);
- }
-
- return explode($delimiter, $value);
+ return null === $limit ? explode($delimiter, $value) : explode($delimiter, $value, $limit);
}
// The '_default' filter is used internally to avoid using the ternary operator
diff --git a/test/Twig/Tests/Fixtures/filters/split.test b/test/Twig/Tests/Fixtures/filters/split.test
index 2bdcdbf3c..ce8ec9cec 100644
--- a/test/Twig/Tests/Fixtures/filters/split.test
+++ b/test/Twig/Tests/Fixtures/filters/split.test
@@ -3,10 +3,16 @@
--TEMPLATE--
{{ "one,two,three,four,five"|split(',')|join('-') }}
{{ foo|split(',')|join('-') }}
-{{ bar|split(',', 3)|join('-') }}
+{{ foo|split(',', 3)|join('-') }}
+{{ baz|split('')|join('-') }}
+{{ baz|split('', 2)|join('-') }}
+{{ foo|split(',', -2)|join('-') }}
--DATA--
-return array('foo' => "one,two,three,four,five", 'bar' => "one,two,three,four,five")
+return array('foo' => "one,two,three,four,five", 'baz' => '12345',)
--EXPECT--
one-two-three-four-five
one-two-three-four-five
one-two-three,four,five
+1-2-3-4-5
+12-34-5
+one-two-three
\ No newline at end of file