Rename Rect inset() method to inflate()

[mnmaita]

Objective

• Fixes Rename Rect.inset() to Rect.inflate() #13092.

Solution

• Renamed the inset() method in Rect, IRect and URect to inflate().
• Added EMPTY constants to all Rect variants, represented by corners with the maximum numerical values for each kind.

---

Migration Guide

• Replace Rect::inset(), IRect::inset() and URect::inset() calls with inflate().

[alice-i-cecile]

Much clearer. Thanks for tackling this.

[alice-i-cecile]

Ah I see, not quite ready. The docs on inflate (just above the changes) for both Rect and IRect need to be revised.

[mnmaita]

Ah I see, not quite ready. The docs on inflate (just above the changes) for both Rect and IRect need to be revised.

Thanks for taking a look at this @alice-i-cecile. Since the behavior is the same, I wonder how I could make the docs clearer. Would it be better to refer simply to a "value" that makes the Rect bigger when positive, instead of using the word "inset"? If so, maybe I could rename the parameter in the methods too. Any other suggestions?

[alice-i-cecile]

Existing docs:

    /// Create a new rectangle with a constant inset.
    ///
    /// The inset is the extra border on all sides. A positive inset produces a larger rectangle,
    /// while a negative inset is allowed and produces a smaller rectangle. If the inset is negative
    /// and its absolute value is larger than the rectangle half-size, the created rectangle is empty.

Proposed replacement:

    /// Create a new rectangle by expanding it evenly on all sides.
    ///
    /// A positive expansion value produces a larger rectangle,
    /// while a negative expansion value produces a smaller rectangle.
    /// If this would result in zero or negative width or height, [`Rect::EMPTY`] is returned instead.

And then change the param name to expansion :) Does that sound reasonable to you?

[mnmaita]

@alice-i-cecile applied the suggested changes and also realized that the test could be renamed too.

[MrGVSV]

Why use the maximum value? The docs seem to indicate that negative or zero sizes will return this empty rect, but a user might assume that in those cases its size would be limited to zero, not jump to the max value.

Some users may be storing positional data and stuff in these rects, meaning that jumping to the max value could be an issue.

[mnmaita]

FWIW the behavior of the method was not changed, so it's not that we're explicitly returning these constants. It's a good point though, I just followed the requirements from the original issue. Might be good to open a new one if this is something we should address later, maybe?

[viridia]

The EMPTY rect should be one in which max is set to MIN and min is set to MAX. In other words, it's a rectangle of infinite negative size.

This is a common practice in many other geometry libraries. The reasoning is simple: an empty rectangle is often used when calculating the union of a series of rectangles (that is, the outer bounds of all of them.). The union of a finite rect A with a negative infinite rect B is just A. So we can start with an empty rect and successively union with each rectangle in turn, using a classic "reduce" or "fold" method.

Note that the EMPTY rect is not the same as a zero-size rect. The rect that is the result of too much negative inflation is not the same as EMPTY because it is still centered at the point of the original rect.

[alice-i-cecile]

Great, I like that convention. We should change to that and clearly document it.

[MrGVSV]

I agree with @mnmaita this might be better saved for a followup PR. Not sure we want to change these kinds of semantics in what's supposed to be a rename PR.