Welcome! Please see the About page for a little more info on how this works.

0 votes
in Docs by

get's implementation checks in order for

  • ILookup
  • nil
  • Map
  • IPersistentSet
  • String or Java array

The docstring for get currently reads

"Returns the value mapped to key, not-found or nil if key not present."

That this works on maps and associative data can reasonably be inferred if one knows Clojure's data model. That it works on sets, Strings, and arrays is less obvious, and would be helpful to mention.

Patch: clj-2249-3.patch

7 Answers

0 votes
by

Comment made by: plexus

I've tried to stick to the same terse style, happy to take suggestions for phrasing. I also changed the first sentence slightly, because I found it difficult to parse, but that is an unrelated change that I can undo if that's preferred.

0 votes
by

Comment made by: alexmiller

I'd leave the first sentence as is.

All of these collection ops are kind of tricky in being able to succinctly state the intent, while also covering special cases (which are often related to Java types). Here I think the intent is to cover lookup in "associative data structures" which covers Clojure maps, records, vectors, Java maps, and other less obvious things like weird ILookup impls.

The non-obvious inclusions for me are: Clojure sets (I haven't reviewed but undoubtedly this is implicitly used in a bunch of special cases), and the Java special cases which are Strings and arrays. For an example of wording, I would point to count and nth, which are similarly weird.

So maybe a sentence like: "get also works on sets to return contained values, and on strings and arrays for value by index." ?

We'll need to answer these same questions in the spec too btw. I expect the act of spec'ing core fns to drive more of these tricky questions.

0 votes
by

Comment made by: daveliepmann

>I'd leave the first sentence as is.

Would a rephrase be welcome in its own issue? Right now the referent of "the value mapped to" is ambiguous. I agree it's difficult to parse.

0 votes
by

Comment made by: alexmiller

(link: ~daveliepmann) no thanks

0 votes
by

Comment made by: plexus

Appended new patch.

0 votes
by

Comment made by: alexmiller

Reworked docstring addition a bit

0 votes
by
Reference: https://clojure.atlassian.net/browse/CLJ-2249 (reported by plexus)
...