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.

Documentation of clojure.string/split is confusing

2021-01-12 Thread Oliver 
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/d4fc8093-40aa-47d9-9a6d-db328d88c36an%40googlegroups.com.

2nd Call for Participation: BOB 2021 (February 26, online)

2021-01-12 Thread Michael Sperber 

Clojure content at BOB, among other great talks!


   BOB 2021
  Conference
 “What happens if we simply use what’s best?”
  February 26, 2021, online
  (UTC+0100)
   http://bobkonf.de/2021/
   Program: http://bobkonf.de/2021/program.html
  Registration: http://bobkonf.de/2021/registration.html

   
BOB conference is a place for developers, architects and decision-makers
to explore technologies beyond the mainstream in software development,
and to find the best tools available to software developers today. Our
goal is for all participants of BOB to return home with new insights
that enable them to improve their own software development
experience.

The program features 14 talks and 8 tutorials on current topics:

http://bobkonf.de/2021/program.html

The subject range includes functional programming, logic programming,
revision control, formal methods, mindfulness, event sourcing,
front-end development, and more.

Jeremy Gibbons will give the keynote talk.

BOB 2021 will take place online.  We are working towards fostering
lively exchange of exciting ideas and enable meaningful social
interactions.

Registration is open online:

http://bobkonf.de/2021/registration.html

Registration is €30 for a regular ticket, €15 for a student ticket.
(If you need financial aid, let us know.)  We intend to make this the
most diverse, colorful, fun BOB ever!



-- 
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/fc812dbc-9c15-4a39-9188-828eed3c197en%40googlegroups.com.