feat: HashTable::try_insert_unique_within_capacity

[morrisonlevi]

This implements #618 with this signature:

    pub fn try_insert_unique_within_capacity(
        &mut self,
        hash: u64,
        value: T,
    ) -> Result<OccupiedEntry<'_, T, A>, T>

This is safe-version from issue feedback, rather than the originally proposed unsafe version.

My personal motivation is to avoid panics. With HashTable::insert_unique, it calls RawTable::insert which calls self.reserve(1, hasher), which will panic out of necessity if allocation fails.

Today, you can call HashTable::try_reserve before calling HashTable::insert_unique to avoid the panic in practice. However, this is not compatible with techniques like using no-panic to detect at compile/link time that a function does not panic. I have verified with this patch that it's no_panic::no_panic compatible. This is not public yet, so I can't share the source for you to verify it yourself, but it's nothing too interesting.

This also has an impact on code size. I don't have concrete, trustworthy numbers for this. The compiler does not optimize away the memory growth path in insert_unique after a try_reserve, so it's easy to see that it should get smaller, it's just a matter of how much.

[morrisonlevi]

I used #[inline(always)] unconditionally because this is a helper method which was previously written in line, so I didn't want to worry about abstraction overhead.

[Amanieu]

A simple #[inline] would be sufficient here. We don't want to over-inline in debug builds since this can hurt build times.

[morrisonlevi]

I suppose someone should check if the unlikely from the new helper find_insert_slot carries over here.

[Amanieu]

You can use core::hint::cold_path for this (with a wrapper so it works on stable).

[morrisonlevi]

I used pub(crate) because I wasn't sure if we wanted to grow the RawTable API surface at all.