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

[sabiwara]

Close #14222

[sabiwara]

Will backport this after merge

[josevalim]

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

[josevalim]

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.

[sabiwara]

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

to_timeout(hour: 1, minute: 30)
5400000

[sabiwara]

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

[sabiwara]

Or this example from inspect examples is nice

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

[sabiwara]

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

[sabiwara]

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"

[josevalim]

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

[josevalim]

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

[sabiwara]

Let’s try keeping as is but different order.

Sorry I didn't get it 😅

Do you want me to push something?

Yes please 🙏

[sabiwara]

Backported