Document guarantees on common "interfaces"

[mratsim]

We have common idioms on types and collections and it would be useful to document what they imply so that new libraries avoid surprising their users.

For example for a long time the builtin sets (not hashsets) didn't provide len but instead card (cardinality). That was because counting the number of elements required checking all bits for 1.
From an old discussion with @Araq on IRC, len was supposed to be O(1) or very cheap.
Once Nim used the compiler builtin popcount instruction which counted that in 1 cycles (or 2 for 2 bytes sets) len could be used.

There are other assumptions that would be helpful to clarify.

For example items for large objects should return a borrowed element so that it does not copy, or we get this: nim-lang/Nim#14421.

get in Options, Result and other monad unwrappers should return a lent on get to avoid copies as well, or we get slowness (nim-lang/Nim#14417) or we can even run out of stack space nim-lang/Nim#15208. Additionally they likely should be inlined.

[haxscramper]

I could say some interfaces are partially documented in nep1 naming conventions, though it only implicitly hints that you should have names like len, []= etc. Adding a new section for style guide should not be particularly difficult, especially when it comes to specifying interfaces for common collections.

Such assumptions might potentially be formalized with use of concepts (when they are ready), and maybe even used in stdlib like it was proposed in #41, though I'm not sure how relevant this is overall. This is also related to #247 which describes needed interfaces using concepts.