Split RawSlots and Slots

[chrysn]

RawSlots operate purely on unprotecetd indices, Slots gives all the protection around it.

---

This is yet an alternative proposal to #10.

I see its benefits in the reduced cognitive load (clearly distinct types rather than "which mode am I in"), with the downside that some operations (count, capacity, try_read/try_modify) being mere forwarders.

(The code could probably be structured better in terms of definition sequence, or possibly even in modules; this was not done here to keep the diff small and readable).

[codecov-io]

Codecov Report

Merging #11 into master will increase coverage by 4.95%.
The diff coverage is 72.00%.

@@            Coverage Diff             @@
##           master      #11      +/-   ##
==========================================
+ Coverage   64.46%   69.41%   +4.95%     
==========================================
  Files           2        2              
  Lines         197      206       +9     
  Branches       28       29       +1     
==========================================
+ Hits          127      143      +16     
+ Misses         32       23       -9     
- Partials       38       40       +2     

Flag	Coverage Δ
#unittests	69.41% <72.00%> (+4.95%)	⬆️

Impacted Files	Coverage Δ
src/lib.rs	66.10% <72.00%> (+9.22%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0bbad2e...426815e. Read the comment docs.

[bugadani]

These are just my first unsorted thoughts:

I'm not so sure about the clearly distinct types as a pro. While I understand where you come from, the types are present in the code in the same place so I don't necessarily see any advantage.

My main concern is the naming and I admit being partial towards myself, I think these two types represent the same data structure, so why have different names for them?

[chrysn]

The positive aspect of the distinct types which I see is the increased clarity in the documentation. For example, when you implement a SlotMap based on RawSlots, you don't see all the Key methods that don't affect you while you read the base type's documentation. Conversely, when using the fully protected Slots, you don't stumble on the try_take function just to later find that that method is absent with the given configuration.

Ad naming: While they represent the same data structure (to the point where raw.store(5) and slots.store(5) result in the same instructions), their usage pattern differs -- just as the usage pattern of a map and a set differ, even though they have some commonality in interfaces (capacity, length) and the latter may be implemented in terms of the former.

[bugadani]

I believe the difference between Map and Set is a great deal larger (i.e. in Rust even though they can have the exact same implementation, there's a huge conceptual difference) than between the strict and relaxed slots. You use both of the slots to insert some data and get back a key, then you use that key to access/modify/remove the data. The difference is that in the relaxed case you are allowed to copy and guess the key and using the "wrong" key doesn't kill your program. But to me this isn't the kind of difference that requires a different name.

I agree with the clarity of the documentation, but not completely: in the cases where I read automatically generated documentation, it was borderline useless anyway. I believe this is a simple enough crate where most of the information can be condensed in a bunch of examples.

[chrysn]

The difference is that in the relaxed case you are allowed to copy and guess the key [...]

Granted, it's not the difference between a set and a map, but "taking returns a value" vs. "taking returns an Option<value>" is a large enough difference to not make them drop-in replacements for each other either.

in the cases where I read automatically generated documentation, it was borderline useless anyway

I'm sorry your experience was bad there; mine (at least with Rust documentation, other languages do need lots of hand-holding through auto documentation processes) was always pleasant so far.

[bugadani]

"taking returns a value" vs. "taking returns an Option"

Well it makes little sense to return an Option that is either always Some or the program panics before returning it :)

[chrysn]

... which is precisely why I think that it makes sense to treat them as different things.

To illustrate what I mean by the useful documentation, I've added some to this branch, and copied a built version over to his to https://downloads.amsuess.com/doc-demo-20200430/slots/.

(capacity and count are the only full redundancies between the two.)

[bugadani]

I'll try to come up with a name I'm happy with instead of RawSlots and I have some small pain points but probably this will be the way forward.