Make Area More Like List

[Chris3606]

Currently, Area works as an ordered list that is guaranteed to have distinct elements. Elements are returned in the order they are inserted via Position, while PositionsSet returns a HashSet<Point> of the points. Area also provides functions like Contains(Point). Finally, it implements IEnumerable<Point>. I feel this has a number of shortcomings.

• This API isn't consistent with collections in C#
• It creates more confusion that is necessary by providing multiple ways to do the same thing in some cases, while not in others. Examples:
  • You can access all points in the Area with either the Area.Positions property, or Area's implementation of IEnumerable.
  • You can determine in a Point is contained within the area with either Area.Contains(Point) or Area.PositionsSet.Contains(Point)
  • However, you cannot index into an area like so: myArea[12] = new Point(1, 2);
• The interface does not provide capabilities equivalent to what you can do with list; for example, Insert and Sort are missing
  • Even some read-only operations are unavailable because operations like BinarySearch that could be defined in IReadOnlyList are not

Proposal

I propose the following enhancements to remedy this difference and make Area more like what it claims to be: a list of points that cannot have duplicates and provides the fastest operations possible, while also providing some metadata about bounds.

Additions

• [ ] public Point this[int index] { get; set; } to allow getting/setting the Point at the given index
• [ ] BinarySearch functions with overloads comparable to List<T>.BinarySearch
• [ ] public void Clear() method to clear all Points
• [ ] public Point Find(Func<Point, bool> predicate) to get first item matching predicate, or Point.None if no item exists
• [ ] FindIndex overloads that match List<T>.FindIndex
• [ ] public Point FindLast(Func<Point, bool> predicate) to get last item matching predicate, or Point.None if no item exists
• [ ] FindLastIndex overloads that match List<T>.FindLastIndex
• [ ] IndexOf overloads that match List<T>.IndexOf
• [ ] public void Insert (int index, T item) to insert item at particular point
  • If item is already in the list, it would be removed from its current position and added to the new one
• [ ] public void InsertRange (int index, IEnumerable<Point> points) to insert a range of points
  • If any of the points are already in the list, they would be removed from its current position and added to the new one.
• [ ] LastIndexOf overloads that match List<T>.LastIndexOf
• [ ] public void RemoveAt (int index) to remove the Point at a given index
• [ ] public void RemoveRange (int index, int count) to remove a range of values (like the List function does)
• [ ] Reverse overloads that match List<T>.Reverse
• [ ] Sort overloads that match List<T>.Sort

Modifications

• [ ] Modify function public void Add(IEnumerable<Point> positions) to public void AddRange(IEnumerable<Point> positions)
• [ ] Modify function public void Add(Rectangle rectangle) to public void AddRange(params Rectangle[] rectangles)
• [ ] Modify function public void Add(IReadOnlyArea area) to public void AddRange(params IReadOnlyArea[] areas)
• [ ] Modify function ``
• [ ] Modify function public void Remove(Func<Point, bool> predicate) to public void RemoveAll(Func<Point, bool> predicate)
• [ ] Modify function public void Remove(HashSet<Point> positions) to public void RemoveAll(HashSet<Point> positions)
• [ ] Modify function public void Remove(public void Remove(IEnumerable<Point> positions) to public void RemoveAll(IEnumerable<Point> positions)
• [ ] Modify function public void Remove(IReadOnlyArea area) to public void RemoveAll(params IReadOnlyArea[] areas)
• [ ] Modify function public void Remove(Rectangle rectangle) to public void RemoveAll(params Rectangle[] rectangles)
• [ ] Modify Add functions to take a parameter on whether or not to move existing elements to the end, vs. simply ignoring duplicates

  Removals

• [ ] Remove Positions property (replaced by equivalent functions above and IEnumerable implementation)
• [ ] Remove PositionsSet property (replaced by equivalent functions above and IEnumerable implementation)

Notable Absent Functions

• List<T>.ConvertAll -- Point does not support inheritance so there is little point to this
  • For cases where this was desired, LINQ can do this
• List<T>.CopyTo -- Uncommonly used and typically you would not copy from Area to Array
• List<T>.FindAll` -- System.LINQ can do this type of operation and not allocate as much memory
• List<T>.ForEach: can be done using typical foreach loop and system.linq
• List<T>.GetRange -- can be done via LINQ construction and makes little sense to copy Areas like this
• List<T>.Exists -- this can be done via LINQ
• List<T>.TrueForAll -- Can be done vis LINQ
• Various HashSet functions: most of those operations don't seem to make sense to do to an area, or are covered by more Area-specific terminology like Intersection, Union

This is a very large restructure, so feedback is welcome; if it seems too extreme, feel free to say.

[fcheadle]

A couple thoughts stand out.

Insert: if area is already sorted, I see no reason to have this function (unless they're part of the dressing involved with IEnumerable).

I would like to propose some operators if I might: + and += to add all points together, - and -= to remove all overlapping points, & to return all overlapping points, ^ to return all points in one or the other but not both, | to return all points of both.

[Chris3606]

Insert: if area is already sorted, I see no reason to have this function

I would contest that this may apply to many use cases, but not all. The assumption that inserting an element implies a strict sortable order may not be valid; you may, for example, just want to insert elements at the beginning to create something like a queue. Also, there are different efficiency implications to sorting a list via calling Sort one or more times vs inserting elements in sorted order to begin with - in a use case where maximum performance is required, each of those options may be appropriate in some cases. List provides both of these methods and they have disparate use cases there, so my thinking is they may have disparate use cases here as well.

I would like to propose some operators if I might

The set operators are an interesting idea. There are already member and static functions that provide these operations currently, however the operators may be a convenient addition.

One caveat to the operators though is returning a new Area is not as efficient as modifying an existing one: for example, area -= area2 results in the allocation of a new Area, whereas area.RemoveAll(area2) does not, so area.RemoveAll may be measurably more performant.