Re: Documentation of clojure.string/split is confusing

2021-01-13 Thread Oliver 
Awesome, thank you.

I'll use that in the future, and I voted for the issue with the proposed 
patch. I think "parts" makes it much clearer, and then the example also is 
spot on as it is.

Ciao!

On Wednesday, 13 January 2021 at 01:58:55 UTC+1 Alex Miller wrote:

> The best place to ask questions like this is at https://ask.clojure.org, 
> which is the official forum to file requests/bug reports (and get turned 
> into tickets after triage there).
>
> It turns out you are not the first to point this out and it has already 
> been filed at https://clojure.atlassian.net/browse/CLJ-1857 and was then 
> duped to include changes in https://clojure.atlassian.net/browse/CLJ-1360 
> which is still open. I will try to get that included in 1.11.
>
> You can (and should!) vote for this issue at 
> https://ask.clojure.org/index.php/4282/doc-that-clojure-string-split-strips-trailing-delimiters
>  
> (which is the ask.clojure question corresponding to that last ticket). 
> Votes really do matter in our prioritization!
>
> Alex
>
> On Tuesday, January 12, 2021 at 2:17:28 PM UTC-6 oliver...@gmail.com 
> wrote:
>
>> Happy new year, folks.
>>
>> (Might not be the best place to post this, but I failed to find a better 
>> one, please advise if there is. I've also tried to look for previous 
>> comments about this. If there are, then my Google-fu was simply too weak.)
>>
>> https://clojuredocs.org/clojure.string/split says:
>> --
>> Usage:
>> (split s re)
>> (split s re limit)
>>
>> Splits string on a regular expression. Optional argument limit is the 
>> maximum number of splits. Not lazy. Returns vector of the splits.
>> --
>>
>> Where I initially understand "number of splits" to be the number of 
>> matches acted upon, that's where a split occurs. I realize there's another 
>> meaning of "split", meaning fragment, and that is the one meant here. 
>> "Returns vector of the splits." hints at that as well, but it literally 
>> says "splits string on..., ... maximum number of splits.".
>>
>> And even in the same docs a few lines later the example for this is 
>> phrased like this:
>> --
>> ;; Note that the 'limit' arg is the maximum number of strings to
>> ;; return (not the number of splits)
>> user=> (str/split "q1w2e3r4t5y6u7i8o9p0" #"\d+" 5) ["q" "w" "e" "r" 
>> "t5y6u7i8o9p0"]
>> --
>> Contradicting the upper description with "(not the number of splits)".
>>
>> I've run into this more than once now, because different languages do 
>> this differently. Whenever I go to the documentation, I read the 
>> description and am satisfied that I've grokked it, just to be mocked by my 
>> off-by-one code minutes later.
>>
>> Does anyone agree that this might be worth changing?
>> I think at least the contradiction in the example should be addressed, 
>> but I think a better solution would be to rephrase the main description to 
>> be unambiguous.
>>
>> I've also looked up a few documentations in other languages. Those that 
>> limit the number of "splits" in my sense (number of matches at which to 
>> split) use the word "splits", those with a behaviour similar to that of 
>> Clojure explicitly talk about the maximum number of resulting 
>> elements/substrings/strings, and I think that would make it much clearer.
>>
>> Apologies for the length!
>>
>> Cheerio
>>   Oliver
>>
>>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/clojure/0d6a3739-8591-438e-b086-ad4cc8ae94e8n%40googlegroups.com.

Re: Documentation of clojure.string/split is confusing

2021-01-12 Thread Peter Strömberg 
About the examples. clojuredocs.org is a community driven, crowd sourced,
service. Clarifying some doc string ambiguities is *exactly* how an example
could help.

Den ons 13 jan. 2021 kl 01:58 skrev 'Alex Miller' via Clojure <
clojure@googlegroups.com>:

> The best place to ask questions like this is at https://ask.clojure.org,
> which is the official forum to file requests/bug reports (and get turned
> into tickets after triage there).
>
> It turns out you are not the first to point this out and it has already
> been filed at https://clojure.atlassian.net/browse/CLJ-1857 and was then
> duped to include changes in https://clojure.atlassian.net/browse/CLJ-1360
> which is still open. I will try to get that included in 1.11.
>
> You can (and should!) vote for this issue at
> https://ask.clojure.org/index.php/4282/doc-that-clojure-string-split-strips-trailing-delimiters
> (which is the ask.clojure question corresponding to that last ticket).
> Votes really do matter in our prioritization!
>
> Alex
>
> On Tuesday, January 12, 2021 at 2:17:28 PM UTC-6 oliver...@gmail.com
> wrote:
>
>> Happy new year, folks.
>>
>> (Might not be the best place to post this, but I failed to find a better
>> one, please advise if there is. I've also tried to look for previous
>> comments about this. If there are, then my Google-fu was simply too weak.)
>>
>> https://clojuredocs.org/clojure.string/split says:
>> --
>> Usage:
>> (split s re)
>> (split s re limit)
>>
>> Splits string on a regular expression. Optional argument limit is the
>> maximum number of splits. Not lazy. Returns vector of the splits.
>> --
>>
>> Where I initially understand "number of splits" to be the number of
>> matches acted upon, that's where a split occurs. I realize there's another
>> meaning of "split", meaning fragment, and that is the one meant here.
>> "Returns vector of the splits." hints at that as well, but it literally
>> says "splits string on..., ... maximum number of splits.".
>>
>> And even in the same docs a few lines later the example for this is
>> phrased like this:
>> --
>> ;; Note that the 'limit' arg is the maximum number of strings to
>> ;; return (not the number of splits)
>> user=> (str/split "q1w2e3r4t5y6u7i8o9p0" #"\d+" 5) ["q" "w" "e" "r"
>> "t5y6u7i8o9p0"]
>> --
>> Contradicting the upper description with "(not the number of splits)".
>>
>> I've run into this more than once now, because different languages do
>> this differently. Whenever I go to the documentation, I read the
>> description and am satisfied that I've grokked it, just to be mocked by my
>> off-by-one code minutes later.
>>
>> Does anyone agree that this might be worth changing?
>> I think at least the contradiction in the example should be addressed,
>> but I think a better solution would be to rephrase the main description to
>> be unambiguous.
>>
>> I've also looked up a few documentations in other languages. Those that
>> limit the number of "splits" in my sense (number of matches at which to
>> split) use the word "splits", those with a behaviour similar to that of
>> Clojure explicitly talk about the maximum number of resulting
>> elements/substrings/strings, and I think that would make it much clearer.
>>
>> Apologies for the length!
>>
>> Cheerio
>>   Oliver
>>
>> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@googlegroups.com
> Note that posts from new members are moderated - please be patient with
> your first post.
> To unsubscribe from this group, send email to
> clojure+unsubscr...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> ---
> You received this message because you are subscribed to the Google Groups
> "Clojure" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/clojure/0c8683ae-cb1a-4555-ad91-bd92095532abn%40googlegroups.com
> 
> .
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
To view this discussion on the web visit

Re: Documentation of clojure.string/split is confusing

2021-01-12 Thread 'Alex Miller' via Clojure 
The best place to ask questions like this is at https://ask.clojure.org, 
which is the official forum to file requests/bug reports (and get turned 
into tickets after triage there).

It turns out you are not the first to point this out and it has already 
been filed at https://clojure.atlassian.net/browse/CLJ-1857 and was then 
duped to include changes in https://clojure.atlassian.net/browse/CLJ-1360 
which is still open. I will try to get that included in 1.11.

You can (and should!) vote for this issue 
at 
https://ask.clojure.org/index.php/4282/doc-that-clojure-string-split-strips-trailing-delimiters
 
(which is the ask.clojure question corresponding to that last ticket). 
Votes really do matter in our prioritization!

Alex

On Tuesday, January 12, 2021 at 2:17:28 PM UTC-6 oliver...@gmail.com wrote:

> Happy new year, folks.
>
> (Might not be the best place to post this, but I failed to find a better 
> one, please advise if there is. I've also tried to look for previous 
> comments about this. If there are, then my Google-fu was simply too weak.)
>
> https://clojuredocs.org/clojure.string/split says:
> --
> Usage:
> (split s re)
> (split s re limit)
>
> Splits string on a regular expression. Optional argument limit is the 
> maximum number of splits. Not lazy. Returns vector of the splits.
> --
>
> Where I initially understand "number of splits" to be the number of 
> matches acted upon, that's where a split occurs. I realize there's another 
> meaning of "split", meaning fragment, and that is the one meant here. 
> "Returns vector of the splits." hints at that as well, but it literally 
> says "splits string on..., ... maximum number of splits.".
>
> And even in the same docs a few lines later the example for this is 
> phrased like this:
> --
> ;; Note that the 'limit' arg is the maximum number of strings to
> ;; return (not the number of splits)
> user=> (str/split "q1w2e3r4t5y6u7i8o9p0" #"\d+" 5) ["q" "w" "e" "r" 
> "t5y6u7i8o9p0"]
> --
> Contradicting the upper description with "(not the number of splits)".
>
> I've run into this more than once now, because different languages do this 
> differently. Whenever I go to the documentation, I read the description and 
> am satisfied that I've grokked it, just to be mocked by my off-by-one code 
> minutes later.
>
> Does anyone agree that this might be worth changing?
> I think at least the contradiction in the example should be addressed, but 
> I think a better solution would be to rephrase the main description to be 
> unambiguous.
>
> I've also looked up a few documentations in other languages. Those that 
> limit the number of "splits" in my sense (number of matches at which to 
> split) use the word "splits", those with a behaviour similar to that of 
> Clojure explicitly talk about the maximum number of resulting 
> elements/substrings/strings, and I think that would make it much clearer.
>
> Apologies for the length!
>
> Cheerio
>   Oliver
>
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/clojure/0c8683ae-cb1a-4555-ad91-bd92095532abn%40googlegroups.com.