Skip to content

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

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.

Sign up for GitHub

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

Merged
merged 5 commits into from
Jan 24, 2025
Merged

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

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dd46ead
Fix String.split/3 example in guide
sabiwara Jan 24, 2025
6f7c9ca
Be explicit about interaction btw :trim and :parts
sabiwara Jan 24, 2025
b0d76be
Update keywords-and-maps.md
josevalim Jan 24, 2025
126f450
Update explanation
sabiwara Jan 24, 2025
16724b4
Update keywords-and-maps.md
josevalim Jan 24, 2025
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
6 changes: 6 additions & 0 deletions lib/elixir/lib/string.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -488,6 +488,12 @@ defmodule String do
iex> String.split(String.normalize("é", :nfc), "e")
["é"]

When using both the `:trim` and the `:parts` option, note that the
trimming doesn't affect the last part:

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

"""
@spec split(t, pattern | Regex.t(), keyword) :: [t]
def split(string, pattern, options \\ [])
Expand Down
6 changes: 3 additions & 3 deletions lib/elixir/pages/getting-started/keywords-and-maps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ iex> String.split("1 2 3", " ")
["1", "", "2", "", "3"]
```

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, there are now empty strings in our results. Luckily, the `String.split/3` function allows the `trim` option to be set to true to remove empty entries from the result:

```elixir
iex> String.split("1 2 3", " ", [trim: true])
Expand All @@ -33,14 +33,14 @@ We can also use options to limit the splitting algorithm to a maximum number of

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should pick another example now? Although the only other option that comes to mind is inspect.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another option is to invert the examples: first we show the parts option and then we show the trimming one. It may be more logical.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how about to_timeout?
it's in Kernel, and very easy to understand

to_timeout(hour: 1, minute: 30)
5400000

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh but people who installed an old version might not have it

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or this example from inspect examples is nice

inspect([1, 2, 3], pretty: true, width: 0)
"[1,\n 2,\n 3]"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the other hand it requires additional context on where timeouts are used? There is always Date.shift though.

If we assume people have a recent enough version of Elixir, I think the context can be pretty minimal and the examples natural enough. We could say something like

Various functions in Elixir or Erlang libraries accept a timeout in milliseconds. For these cases, we can use the to_timeout helper:

iex> to_timeout([minute: 1])
60000

iex> to_timeout([minute: 1, second: 30])
90000

iex> to_timeout(minute: 1, second: 30)
90000

Copy link
Contributor Author

@sabiwara sabiwara Jan 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another example using just primitive types (I don't love it):

iex(1)> Base.encode32("foobar")
"MZXW6YTBOI======"
iex(2)> Base.encode32("foobar", case: :lower)
"mzxw6ytboi======"
iex(3)> Base.encode32("foobar", case: :lower, padding: false)
"mzxw6ytboi"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s try keeping as is but different order. Do you want me to push something?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that doesn’t work, I think Base can be a good second option.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s try keeping as is but different order.

Sorry I didn't get it 😅

Do you want me to push something?

Yes please 🙏

["1", "2 3"]
["1", " 2 3"]
```

`[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:

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

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