diff --git a/proposals/draft/jep-016-string-manipulation.md b/proposals/draft/jep-016-string-manipulation.md new file mode 100644 index 0000000..c6279f5 --- /dev/null +++ b/proposals/draft/jep-016-string-manipulation.md @@ -0,0 +1,61 @@ +# String Manipulation (GorillaStack) + +||| +|---|--- +| **JEP** | 16 +| **Author** | Chris Armstrong (Gorilla Stack) +| **Status** | draft +| **Created**| 31-10-2019 + +## Abstract + +This document proposes expanding the list of available string manipulation +functions in the spec. + +## Motivation + +The specification only contains basic string search and manipulation functions, +such as starts_with() and contains(), which are insufficient for other use +cases, such as replacing parts of strings, splitting strings, using regular expressions +for searching or manipulation of strings, or other common string manipulations +found in the common libraries of mainstream languages such as Python or JavaScript. + +## Specification + +The following functions will be added to the specification: + +### split + +``` +array[string] split(string $subject, string $split_str, number $max = -1) +``` + +Given string `$subject`, split will split on occurrences string `$split_str`, up to and including +$max times (if specified). + +The result is an array containing each partial string between occurrences of `$split_str`. If the +string contains no occurrences of $split_str, an array containing just the original `$subject` +string will be returned. + +`$max` is a optional parameter. When specified as an integer greater than zero, it will split the +string up to `($max - 1)` times, with the last string in the array containing the remaining +contents of `$subject` unmodified. + +If not specified or it is less than zero, the string will be split on every occurrence of `$split_str`. + +When `$max` is equal to zero, it will behave as if the string is not split at all, and return +an array containing one element, the original string. + +### Examples + +| Expression | Result +|---|--- +| `split('average\|-\|min\|-\|max\|-\|mean\|-\|mode\|-\|median', '\|-\|')` | `["average", "min", "max", "mean", "mode", "median"]`| +| `split('average\|-\|min\|-\|max\|-\|mean\|-\|mode\|-\|median', '\|-\|', 3)` | `["average", "min", "max\|-\|mean\|-\|mode\|-\|median"]` +| `split('average\|-\|min\|-\|max\|-\|mean\|-\|mode\|-\|median', '-')` | `["average\|", "\|min\|", "\|max\|", "\|mean\|", "\|mode\|", "\|median"]` +| `split('average\|-\|min\|-\|max\|-\|mean\|-\|mode\|-\|median', '\|-\|', 0)` | `["average\|-\|min\|-\|max\|-\|mean\|-\|mode\|-\|median"]` +| `split('every character', '')` | `["e", "v", "e", "r", "y", " ", "c", "h", "a", "r", "a", "c", "t", "e", "r"]` + +## Impact + +There should be no impact to existing users, as these are new functions.