Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix String.split/3 example in guide and add note in docs #14223

Merged
merged 5 commits into from
Jan 24, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions lib/elixir/lib/string.ex
Original file line number Diff line number Diff line change
Expand Up @@ -488,6 +488,15 @@ defmodule String do
iex> String.split(String.normalize("é", :nfc), "e")
["é"]

When using both the `:trim` and the `:parts` option, the empty values
are removed as the parts are computed (if any). No trimming happens
after all parts are computed:

iex> String.split(" a b c ", " ", trim: true, parts: 2)
["a", " b c "]
iex> String.split(" a b c ", " ", trim: true, parts: 3)
["a", "b", " c "]

"""
@spec split(t, pattern | Regex.t(), keyword) :: [t]
def split(string, pattern, options \\ [])
Expand Down
34 changes: 19 additions & 15 deletions lib/elixir/pages/getting-started/keywords-and-maps.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,44 +11,48 @@ Keyword lists are a data-structure used to pass options to functions. Let's see
Imagine you want to split a string of numbers. Initially, we can invoke `String.split/2` passing two strings as arguments:

```elixir
iex> String.split("1 2 3", " ")
["1", "2", "3"]
iex> String.split("1 2 3 4", " ")
["1", "2", "3", "4"]
```

However, what happens if there is an additional space between the numbers:
What if you only want to split at most 2 times? The `String.split/3` function allows the `parts` option to be set to the maximum number of entries in the result:

```elixir
iex> String.split("1 2 3", " ")
["1", "", "2", "", "3"]
iex> String.split("1 2 3 4", " ", [parts: 3])
["1", "2", "3 4"]
```

As you can see, there are now empty strings in our results. Luckily, the `String.split/3` function allows the `trim` option to be set to true:
As you can see, we got 3 parts, the last one containing the remaining of the input without splitting it.

Now imagine that some of the inputs you must split on contains additional spaces between the numbers:

```elixir
iex> String.split("1 2 3", " ", [trim: true])
["1", "2", "3"]
iex> String.split("1 2 3 4", " ", [parts: 3])
["1", "", "2 3 4"]
```

We can also use options to limit the splitting algorithm to a maximum number of parts, as shown next:
As you can see, the additional spaces lead to empty entries in the output. Luckily, we can also set the `trim` option to `true` to remove them:

```elixir
iex> String.split("1 2 3", " ", [trim: true, parts: 2])
["1", "2 3"]
iex> String.split("1 2 3 4", " ", [parts: 3, trim: true])
["1", "2", " 3 4"]
```

`[trim: true]` and `[trim: true, parts: 2]` are keyword lists. When a keyword list is the last argument of a function, we can skip the brackets and write:
Once again we got 3 parts, with the last one containing the leftovers.

`[parts: 3]` and `[parts: 3, trim: true]` are keyword lists. When a keyword list is the last argument of a function, we can skip the brackets and write:

```elixir
iex> String.split("1 2 3", " ", trim: true, parts: 2)
["1", "2 3"]
iex> String.split("1 2 3 4", " ", parts: 3, trim: true)
["1", "2", " 3 4"]
```

As shown in the example above, keyword lists are mostly used as optional arguments to functions.

As the name implies, keyword lists are simply lists. In particular, they are lists consisting of 2-item tuples where the first element (the key) is an atom and the second element can be any value. Both representations are the same:

```elixir
iex> [{:trim, true}, {:parts, 2}] == [trim: true, parts: 2]
iex> [{:parts, 3}, {:trim, true}] == [parts: 3, trim: true]
true
```

Expand Down
Loading