MONGOID-5098 Standardize/improve Range queries -- .where(field: 1..3)

[johnnyshields]

Behavior changes:

• Non-inclusive ranges 1...3 should use $lt operator.
  • Example: 1...3 should be $gte: 1, $lt: 3. Currently it does $gte: 1, $lte: 2 which will not query Floats correctly.
• Support beginning-less ..1 / ...1 and endless 1.. ranges, if Ruby version supports them.
• Make __evolve__ handling consistent across various methods, including consistent handling of Date/Time/TimeWithZone

Lastly, I considered supporting descending ranges such as 3..1 but I've held off on it for now since they basically don't work in Ruby (3..1).cover?(2) => false. I do think it would be nice-to-have however and I have the code for it so if desirable I can raise it as a follow-up PR.

Fixes half of MONGOID-5098

Related to MONGOID-5026 but can be merged independently

[johnnyshields]

@p-mongo __evolve_range_naive__ always returns a new Hash. Therefore it's safe (and better performance) to mutate the object.

[p-mongo]

It is true that the current implementation returns a new object every time, but this isn't stated in e.g. a docstring as a requirement for the method, therefore it is possible that at a future time someone might alter it to have different behavior. Looking at it again, given that it is a private method, I think it would be safe to mutate its value if it's given @api private annotation and the docstring explicitly said that a new object must be returned each time because it will be mutated.

[johnnyshields]

Since the method itself is private, it should be fine.

AFAIK @api private only used on public methods to declare that they should not be considered part of the public-facing API (even though they are in fact public.) Flagging a private method as @api private is redundant.

[p-mongo]

Unfortunately when methods are defined in modules which are included in user code (e.g. Mongoid::Document) there can be confusion as to whether a method is private to Mongoid or it is private to the class (but is usable by other methods of the same class). For this reason Mongoid frequently contains @api private annotations on private-visibility methods.

[johnnyshields]

In your most recent commit:

  context 'endless range' do
    ruby_version_gte '2.7'

    it 'Range<Integer> criteria vs Integer field' do
      expect(Band.where(likes: eval('..3')).to_a).to eq [band1, band2, band3, band4]
      expect(Band.where(likes: eval('...3')).to_a).to eq [band1, band2, band3]

These are actually "beginning-less" ranges.

Note that:

1.. --> works on Ruby 2.6+

..1 --> works on Ruby 2.7+

[p-mongo]

@johnnyshields Thanks for pointing that out, I suspected that some syntax was OK for 2.6 but I just wanted to make this PR mergeable and I didn't spend time investigating. I understand that on Ruby 2.6 it is possible to test some of the combinations, if you would like to adjust the tests so that they do that please go ahead.

Another aspect of this PR that I decided to leave as is is the context/it descriptions. In the example you quoted, Range<Integer> criteria vs Integer field should be a context, and it should refer to the behavior (sometimes I cheat and use phrasing like it "works as expected" when there is only one case).

Between these two changes there would be a bit more work in the test files to get them to be 100%, I opted to skip it so that I can move on to your other PRs but if you wish to make these adjustments I will appreciate it.

[johnnyshields]

@p-mongo I've updated the specs to use context and use Ruby 2.6 vs 2.7 correctly.