Document behavior of clojure.core/get on strings and Java arrays

Description

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

Screened by: Alex Miller

Environment

None

Activity

Show:
Alex Miller
October 5, 2017, 7:14 PM

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.

import
October 5, 2017, 8:18 PM

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.

Alex Miller
October 5, 2017, 8:50 PM

no thanks

Arne Brasseur
October 9, 2017, 9:27 AM

Appended new patch.

Alex Miller
October 4, 2018, 8:12 PM

Reworked docstring addition a bit

Assignee

Unassigned

Reporter

Arne Brasseur

Labels

Approval

Screened

Patch

Code

Fix versions

Priority

Minor