Document invariant on Ranges

[konstin]

Ranges keeps up certain invariants internally, we document which they are and why they exist. Currently, they can only be observed by iterating over segments.

Split out from #273.

[Eh2406]

this applies only to equality under pubgrub's model.

Is there a word missing here? I'm not sure what this was trying to say.

[Eh2406]

@mpizenberg is our resident wordsmith, so I will leave it up to him.

[mpizenberg]

Another way to describe: "list of non-overlapping, non-consecutive, intervals with strictly increasing values".

The described invariants are good to me.

I don’t understand what the last sentence means though. Could you elaborate?

Given that this type doesn't know the lower bound, upper bound, granularity or actual instances of V, this applies only to equality under pubgrub's model.

[mpizenberg]

Though maybe rule number 1: the sorting doesn’t make much sense until rule 2 and 3 are given. Once we have rules 2 and 3, we know that interval bounds can be sorted. So maybe it should be the last invariant?

[mpizenberg]

Oh maybe I get it.

Given that this type doesn't know the lower bound, upper bound, granularity or actual instances of V, this applies only to equality under pubgrub's model.

Do you mean that the provided invariants cannot guaranty that sets described by these invariants are actually equal if and only if their representation is equal. This is not an equivalence, just an implication. Because for example, In the set of natural numbers, both these sets representations are the valid under the above rule, yet they are different representation of the same:

1. [3, 7[
2. [3, 6]

[mpizenberg]

That’s why originally, we forced the rule that left bound is inclusive, and right bound is exclusive, and the set of values must have a strict ordering and every "next" value must be known. Which is annoying when you don’t really know what "next" can be.

[mpizenberg]

What do you think of replacing the last sentence with something like:

Remark: This representation cannot strictly guaranty equality of Ranges with equality of its representation without also knowing the nature of the underlying versions. In particular, if the version space is discrete, different representations, using different types of bounds (exclusive/inclusive) may correspond to the same set of existing versions. It is a tradeoff we acknowledge, but which makes representations of continuous version sets more accessible, to better handle features like pre-releases and other types of version modifiers.

[konstin]

I added an example too so it's more accessible for non-math-background people.