RFC: Add an interfaces manual chapter #11794
Conversation
|
There's room at the |
|
This is great! Should the code blocks be doctests here? |
|
Ah, yes, thank you, they should. |
| Interfaces | ||
| ************ | ||
|
|
||
| A lot of the power and extensibility in Julia comes from a collection of informal interfaces. By extending few specific methods to work for a custom type, objects of that type not only receive those functionalities, but they are also able to be used in other methods that are written to generically build upon those behaviors. |
|
Conceptually, what separates these from a "formal" interface? That the type isn't directly annotated with something that says "Iterable"? |
| :func:`getindex(X, i) <getindex>` ``X[i]``, indexed element access | ||
| :func:`setindex!(X, v, i) <setindex!>` ``X[i] = v``, indexed assignment | ||
| :func:`endof(X) <endof>` The last index, used in ``X[end]`` | ||
| ====================================== ================================== |
There was a problem hiding this comment.
What happens with colons, like Squares[:]? Should that go here?
There was a problem hiding this comment.
Yeah, as I was writing it I briefly considered using that as a motivating segue into the AbstractArray section. Not sure why I didn't end up doing that… I guess I got distracted. S[:] now gets lowered to getindex(S, Colon()). So it's entirely up to the type to define the appropriate method. Definitely worth a mention.
Yes, I think so. See #6975. I guess it gets a little blurry for the |
Document the iterable, indexable, and abstract array interfaces. [av skip]
* Use sequence instead of collection in some places * Change eltype and length descriptions * Indentation fixes * Talk about how defining getindex manually is a game of whackamole without support from AbstractArray * Link to Array Indexing section [av skip]
|
This is really awesome. Well done, @mbauman. |
| :func:`similar(A, ::Type{S}, dims::NTuple{Int}) <similar>` ``Array(S, dims)`` Return a mutable array with the specified element type and dimensions | ||
| ========================================================== ============================================ ======================================================================================= | ||
|
|
||
| If a type is defined as a subtype of ``AbstractArray``, it inherits a very large set of complicated behaviors including iteration and multidimensional indexing built on top of single-element access. |
There was a problem hiding this comment.
"Complicated" doesn't make it very appealing. :-) Maybe you could make it more obvious that you benefit from "rich" automatic fallbacks by simply defining basic methods?
|
Really cool! Don't you think the titles of the sections could be changed to |
* complicated -> rich * fix linearindexing description coherence between phrases by changing the first part of the phrase * add a paragraph about how linearindexing impacts which getindex method(s) must get defined * Fix missing *what* * each other [av skip]
[av skip]
|
Thanks, looks good! |
|
Thanks @nalimilan! Updated (oh, you already found it as I was writing this!). I like the words iteration and indexing much better than iterable and indexable, but if others think the latter vocabulary is clearer I'll happily change it. I've also added more cross-links to and from other sections of the manual and standard library. In doing so, I rediscovered http://docs.julialang.org/en/latest/manual/arrays/#implementation. That page and section are written more in a descriptive how-to-use-it fashion instead of the way this is more of a how-to-implement-it. I think they can both live together nicely, but perhaps some of the information could be consolidated. Thoughts? Also, I'm very tempted to document And I really cannot wait for #11242 to get merged. A syntax is really needed to talk about these things simply and clearly. |
|
I'll merge this now. It's documentation and there are clamors for hashing/equality, comparison, and display interfaces. I don't have time to add those myself in the short term, but maybe once there's an obvious place for them to live others will be able to add it. |
RFC: Add an interfaces manual chapter
|
Shoot, sorry, should have squashed. |
|
There is no requirement that an AbstractArray implement a hash function, is there? |
|
They get the default implementation for free. Should be added. |
Document the iterable, indexable, and abstract array interfaces.
I'm open to suggestions on the tables. I like the way they summarize the requirements, and I think the iterable and indexable ones work well, but the array table is nearly unreadable since it needs to scroll horizontally.