mirror of
https://github.com/sass/sass.git
synced 2024-09-21 18:47:25 +00:00
123 lines
3.2 KiB
Markdown
123 lines
3.2 KiB
Markdown
# `string.split()`: Draft 1.2
|
|
|
|
*([Issue](https://github.com/sass/sass/issues/1950), [Changelog](string-split.changes.md))*
|
|
|
|
This proposal adds `string.split()` to the `sass:string` module.
|
|
|
|
## Table of Contents
|
|
|
|
* [Background](#background)
|
|
* [Summary](#summary)
|
|
* [Semantics](#semantics)
|
|
* [`split()`](#split)
|
|
|
|
## Background
|
|
|
|
> This section is non-normative.
|
|
|
|
The `sass:string` module contains several functions for manipulating and finding
|
|
out information about strings. Currently, though, there is no built-in function
|
|
that splits one string into a list of substrings, and authors have been creating
|
|
their own versions of functions that achieve this functionality.
|
|
|
|
## Summary
|
|
|
|
> This section is non-normative.
|
|
|
|
This proposal adds the `string.split()` function to the `sass:string` module.
|
|
The function takes a string, splits it based on a provided separator, and
|
|
returns a bracketed, comma-separated list of substrings.
|
|
|
|
This could be used to take a string and repurpose parts of it for some other
|
|
use. For example, fonts contained in a font stack list could be split into
|
|
segments and then used as keys in a new map.
|
|
|
|
Examples:
|
|
|
|
```scss
|
|
$fonts: "Helvetica Neue, Helvetica, Arial";
|
|
string.split($fonts, ', '); // ["Helvetica Neue", "Helvetica", "Arial"]
|
|
```
|
|
|
|
A third argument can set a limit to the the number of splits performed on the
|
|
string:
|
|
|
|
```scss
|
|
string.split($fonts, ', ', 1); // ["Helvetica Neue", "Helvetica, Arial"]
|
|
```
|
|
|
|
An empty `$separator` returns all Unicode code points in the original string:
|
|
|
|
```scss
|
|
$font: "Helvetica"
|
|
string.split($font, ''); // ["H", "e", "l", "v", "e", "t", "i", "c", "a"]
|
|
```
|
|
|
|
## Semantics
|
|
|
|
### `split()`
|
|
|
|
```
|
|
split($string, $separator, $limit: null)
|
|
```
|
|
|
|
* If `$string` is not a string, throw an error.
|
|
|
|
* If `$separator` is not a string, throw an error.
|
|
|
|
* If `$limit` is a value other than an integer or `null`, throw an error.
|
|
|
|
* If `$limit` is less than 1, throw an error.
|
|
|
|
* If `$string` is an empty string, return a list with `$string` as the only
|
|
item.
|
|
|
|
* Let `split-list` be an empty list.
|
|
|
|
* If `$limit` is `null`, set `$limit` to the value of calling
|
|
`string.length($string)`.
|
|
|
|
* Let `split-counter` equal 0.
|
|
|
|
* While `split-counter <= $limit` and `string.length($string) > 0`:
|
|
|
|
* If `split-counter == $limit`:
|
|
|
|
* Append `$string` to `split-list`.
|
|
|
|
* Set `$string` to an empty string.
|
|
|
|
* Otherwise:
|
|
|
|
* If `$separator` is an empty string:
|
|
|
|
* Let `code-point` be the value of calling `string.slice($string, 1, 1)`.
|
|
|
|
* Append `code-point` to `split-list`.
|
|
|
|
* Set `$string` to `string.slice($string, 2)`.
|
|
|
|
* Increase `split-counter` by 1.
|
|
|
|
* Otherwise:
|
|
|
|
* Let `index` be the result of calling
|
|
`string.index($string, $separator)`.
|
|
|
|
* If `index` is `null`, append `$string` to `split-list` and set `$string`
|
|
to an empty string.
|
|
|
|
* Otherwise:
|
|
|
|
* Let `current-substring` be the result of calling
|
|
`string.slice($string, 1, index - 1)`.
|
|
|
|
* Append `current-substring` to `split-list`.
|
|
|
|
* Set `$string` to
|
|
`string.slice($string, index + string.length($separator))`.
|
|
|
|
* Increase `split-counter` by 1.
|
|
|
|
* Return `split-list` as a bracketed, comma-separated list.
|