[feature request] insert with hint for TreeContainers

Is your feature request related to a problem? Please describe.

I want to update the element in the TreeContainer (e.g. OrderedSet), but it is prohibited. It is reasonable because updated element could insert the different position.

However, users sometimes know the updated element is still the same position. For example,

Before update:
    V
[1, 3, 5]

After update:
    V
[1, 4, 5]

When I want to update the element, I need to do the following steps:

1. container.find(key) the element’s iterator. Then got it.
2. container.eraseElementByIterator(it)
3. Create the new element based on the gotten element and insert it.

Step1 and 3 are O(logN) time complexity. I want to eliminate Step3 cost.

Describe the solution you’d like js-sdsl’s design refers to C++ STL. C++ std::set::insert has insert(hint, value) overload. https://en.cppreference.com/w/cpp/container/set/insert See (3) (4) overloads.

Since C++ 11 3-4) Amortized constant if the insertion happens in the position just before the hint, logarithmic in the size of the container otherwise.

container.eraseElementByIterator(it) at the step2 returns the iterator just after the erased element. So if I use the returned iterator as the hint, then the hint iterator is the insertion happens in the position just before the hint.

So the steps become as follows:

1. container.find(key) the element’s iterator. Then got it.
2. it = container.eraseElementByIterator(it)
3. Create the new element based on the gotten element and insert it with hint. container.insertWithHint(it, 4)

Step3 becomes O(1) time complexity thanks to the hint it.

I guess that js-sdsl can implement similar way to the C++ one.

Describe alternatives you’ve considered

Directly modify the element value by user’s risk. However, insert() with hint achieves the same goal (eliminate extra O(logN) time complexity) more elegant way.

Additional context

libc++ implementation of std::set::insert(hint, value) https://github.com/llvm-mirror/libcxx/blob/2f961a057f1ecb29d40892fe9198fe4e4b5c5619/include/set#L704-L711

[ZLY201]

The test version 4.1.4-beta.0 has been released, if there are no bug reports within a week, we will released the official version.

[redboltz]

Thank you for implementing the feature !! I used it on my number-allocator and it works fine. https://github.com/redboltz/number-allocator/pull/31