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.
