Make `Region` type iterable to allow destructuring assignment.

[Thom1729]

This is a very small feature that would provide a minor benefit for (I hope) a near-trivial effort.

Examples of use:

begin, end = view.line(my_region)

for begin, end in map(sorted, self.view.sel()):
for a, b in self.view.sel():

Without this feature:

region = view.line(my_region)
begin = region.begin()
end = region.end()

for region in self.view.sel():
    begin = region.begin()
    end = region.end()

Suggested implementation:

class Region():
    def __iter__(self):
        return iter( ( self.a, self.b ) )

[FichteFoll]

__iter__ should return an Iterator, not an Iterable, so return iter( (self.a, self.b) ) is better.

Regions that have a and b swapped are different, so to ensure their comparibility after iterating over them, a and b should be iterated over instead of begin and end, imho.

Edit: added section on a and b and swapped Iterator/Iterable

[Thom1729]

I've fixed the iterator thing. Thanks for the catch.

Regarding the ordering: speaking for myself, the vast majority of time I need begin and end, not a and b. In those cases, destructuring that provided a and b would be useless. In addition, two regions that match on a and b aren't necessarily equal, because they could differ on xpos, so no matter what, the tuple will only include a subset of the region information.

When does the distinction matter? Most API methods return forward-oriented regions with no xpos (counting empty regions as forward-oriented). Is the sole exception Selections? The Region.cover method preserves the orientation of the first region, but Region.intersection always returns a forward-oriented region. Region.size, of course, is always positive. All of the Region methods throw away xpos entirely. Overall, it seems that code that respects the orientation of selection regions requires extra care anyway.

[FichteFoll]

How about using this then:

for begin, end in map(sorted, view.sel()):
    pass

You can do that if the original structure order is returned, but you cannot go from the ordered to the unordered without requesting them manually like you have to currently. (If you worry about performance, the Region.begin and .end implementations also need to compare the two points and return either the minimum or maximum, so this could even be faster.)

[FichteFoll]

The distinction matters when you want to restor regions, mostly, or you are interested in the region's direction which has never occured to me.

Preserving the underlying data order in the general iteratable protocol allows for more flexibility and is more true to what the data actually represents, so I would always choose that, even if a different use case might be more common. I would supply a different method for that instead, if necessary, or like here just wrap them with a sorted call.

Edit: Region.xpos is only used by Selection.add and always defaults to -1 (i.e. it's not determined based on the .a and .b parameters). I'm not even sure what it represents.

[Thom1729]

It looks like Python has successfully trained me to do functional programming the hard way — I didn't think of using map/sorted. That makes the ergonomics work acceptably well in the common case.

[Thom1729]

Region.xpos

When you move your cursor over empty lines but it remembers the original x position, that's xpos at work. As far as I know, it's only relevant to selections.

I think that perhaps with the benefit of 20/20 hindsight, it would have made sense for Regions to be unoriented. Then, each SelectionItem (or whatever) could consist of a Region, an orientation, and an x position. The Region logic would be simpler. A SelectionItem would not implement cover, intersection, or the like; you could use the Region directly (leaving orientation and xpos behind) or if you needed special logic that handled orientation and xpos, you could write it explicitly. (Of course, there's no reason to change it now.)

[FichteFoll]

On the other hand, Region.b always represents the caret. Sure, this could have been a property, too, but personally I don't have any real issues with the current implementation. When methods such as intersection return an effectively unoriented region, the just pick forward by default.

Thanks for the xpos explanation though. I remember reading that a while ago, but it practically never comes up for plugins because you really don't need it 99% of the time.

[evandrocoan]

Examples of use:

begin, end = view.line(my_region)

for begin, end in map(sorted, self.view.sel()):
for a, b in self.view.sel():

Did you miss pass or some indentation?:

for begin, end in map(sorted, self.view.sel()): pass

And why iterating throughout map(sorted, self.view.sel()) with pass first, and then iterating throughout for a, b in self.view.sel() later? i.e., How one is related to the other?

---

Without this feature:

region = view.line(my_region)
begin = region.begin()
end = region.end()

Ok, here with view.line(my_region) you sorted the region and did nothing with, i.e., discarded the region before you start the next part of the code:

for region in self.view.sel():
begin = region.begin()
end = region.end()

How this for is related to the first code region = view.line(my_region) ...?

---

What do you mean by destructuring? Searching for it, I found this JavaScript example:

var a, b, rest;
[a, b] = [10, 20];

console.log(a);
// expected output: 10

console.log(b);
// expected output: 20

[a, b, ...rest] = [10, 20, 30, 40, 50];

console.log(rest);
// expected output: [30,40,50]

[Thom1729]

The examples are not complete or functional. Imagine that the for loops have a block and that the block does something useful.

[FichteFoll]

What do you mean by destructuring? Searching for it, I found this JavaScript example:

Yes, this is exactly what we're talking about.