Finish #17558, re-adding insert_children

[ElliottjPierce]

fixes #17478

Objective

• Complete Insert children #17558.
• the insert_children method was previously removed, and as Missing a method to insert related entities at a specific index (insert_children) #17478 points out, needs to be added back.

Solution

• Add a OrderedRelationshipSourceCollection, which allows sorting, ordering, rearranging, etc of a RelationshipSourceCollection.
• Implement insert_related
• Implement insert_children
• Tidy up some docs while I'm here.

Testing

@bjoernp116 set up a unit test, and I added a doc test to OrderedRelationshipSourceCollection.

[cart]

In theory we can improve the performance here by taking advantage of the fact that we can know if the entities in related are in the RelationshipSourceCollection based on whether or not they have R (if they do not have R, they aren't in it, if they do have R and it points to the target they are in it, and if they do have R and it does not point to the target they are not in it).

We could skip the insert hook (using RelationshipHookMode) and manually do the insert ourselves.

That would allow us to skip the O(nm) runtime that this currently has (for the remove op), in cases where the scan is not necessary (which should be most cases).

Edit: it would also allow us to skip the cost of the "initial" insert into the wrong location

In cases where there are no reorders, it would also in theory allow us to do an optimized "resize collection, shift everything after index over, and insert everything in related", which would be much faster than inserting one-by one (which requires a "list shift" on every insert).

[ElliottjPierce]

I'm still relatively new to relationships, but I think I've made the requested changes. Let me know if I missed something here though.

It now skips the re-inserting if it already exists, preventing hooks. If we do need to add it, it no longer has to search for it.

In cases where there are no reorders, it would also in theory allow us to do an optimized "resize collection, shift everything after index over, and insert everything in related", which would be much faster than inserting one-by one (which requires a "list shift" on every insert).

100% agree here, but I'm unsure how to practically do this. My best guess would be to remove all the duplicates from the new slice (which would allocate, maybe with bumpalo), then insert the relation component without hooks, then remove the entities in the passed slice from the target collection, and finally insert the slice into the vector directly. But between the allocation and removals IDK if that would be worth the performance. Maybe we could make it unsafe and presume that the entities have no duplicates and are not currently related?

[alice-i-cecile]

Oh good I was hoping that something like this would be used.

[bushrat011899]

Approved pending the documentation corrections already pointed out, nice work!