Deprecate insert_many (and add splice?)

[mbrubeck]

The insert_many function is complicated, and has had several bugs and vulnerabilities (#96, #208, #252). Unlike most SmallVec methods, it does not correspond to a standard Vec method. Perhaps because of this, it is rarely used. Should we deprecate this method, and remove it in the next major version?

The standard Vec::splice method could be used in place of insert_many, but SmallVec does not yet implement this method. We could add this, possibly by copying the implementation from std::vec, if there is demand for it.

[lopopolo]

@mbrubeck I would like to put in a request for a Vec::splice equivalent API.

I've implemented a crate that exposes several types that would be appropriate to implement Ruby's Array class. This crate has multiple backends, including Vec and SmallVec. Ruby has an Array#[]= API which in one of its forms acts like Vec::splice: replace a subslice of the Array with another slice.

The SmallVec implementation is several times larger and scarier than the Vec implementation.

SmallVec: https://github.com/artichoke/artichoke/blob/ae3fa8adc8e26d74a6ee566e2065b79db5b09fc8/spinoso-array/src/array/smallvec/mod.rs#L1093L1157
Vec: https://github.com/artichoke/artichoke/blob/ae3fa8adc8e26d74a6ee566e2065b79db5b09fc8/spinoso-array/src/array/vec/mod.rs#L1124-L1141

spinoso_array::SmallArray::set_slice might be a starting point for a SmallVec::splice implementation (MIT licensed). It uses no unsafe code.