vec: remove code duplication due to VecView.

[Dirbaio]

I'm a bit concerned about the code duplication introduced by #425. Most Vec
methods forward to their VecView counterparts, but the function signature
and the doc comments are still duplicated. This means every time we do a doc
fix or add a new method we have to remember to do it on both sides.

It has worked fine for for experimenting and proving the concept. However,
now we're at a stage where it's proven and we have to commit to
add it to all the other containers: #452 #459 #479 #480 #481 #485.
Each of these PRs adds 400-600 lines to the codebase, mostly duplicated
signatures and docs.

IMO we should find a way of adding View types without so much duplication
first, then add it to all containers.

This PR implements a possible solution I've found that removes all the duplication:

• Added a Storage trait with two impls, for sized and unsized.
• Vec is now generic over Storage instead of over the buffer type. The buffer type is now a Buffer associated type.
• Storage is sealed. The Buffer associated type is private. The user cannot learn the Buffer type for the
  Storage impls, they can just use it with VecInner and it makes it behave differently magically.
• Most methods are implemented for VecInner<S> for any S: Storage. This makes them
  available on both Vec and VecView without duplicating anything.

Advantages:

• No duplication.
• No macros.
• Trait impls are generic over Storage now, so you can e.g. compare a Vec with a VecView. Before you couldn't, you could only do Vec-Vec or VecView-VecView.
• Users can now write code or trait impls generic over the storage.

Docs work fine on latest stable, it doesn't seem to need any workarounds:

• docs for Vec show the Vec-only methods and the storage-independent methods.
• docs for VecView show the VecView-only methods (if we had some, we don't) and the storage-independent methods.
• docs for Vecinner show all methods.

I also propose making mod vec public, including Storage, VecInner. The reasons are:

• vec::IntoIter was already in the public API, but was previously unnameable.
• Exposing Storage, VecInner can be useful for users that want to write code or trait impls generic over the storage.
• Now that Storage is a sealed trait and the Buffer type is hidden, it's not leaking implementation details anymore. There's no [MaybeUninit<T>] in the public API, we can change it at any time without it being a breaking change.

I think we also should remove the Vec, VecView reexports in the crate root, but this is left for a future PR.

cc @sosthene-nitrokey

[Dirbaio]

Tested code size on company firmware:

   text    data     bss     dec     hex filename
 378136    1796  182436  562368   894c0 heapless git v0.8.0
 378168    1796  182436  562400   894e0 heapless git main
 378232    1796  182436  562464   89520 heapless git vecview-dedup

slight 0.02% bloat, but imo it's within the margin of error.

[sosthene-nitrokey]

I thought about this approach initially but didn't go for it because:

• had concerns about the documentation generated, but there were bugs with Rust doc that have been fixed since then, so it may be actually better now
• The initial reasoning behind this PR was to reduce binary size by reducing the need for monomorphization for each value N. I'll re-run the comparison again but if I remember correctly this lead to 2% size reduction in our firmware, i'm testing this again.

• Users can now write code or trait impls generic over the storage.

I'm not sure I see the benefits of that. My idea was that we would end up using VecView pretty much everywhere we can, and when we can't it would be because it's !Sized, and thus not

On the other hand, I agree with the benefits of this approach:

• Less code (thus more maintainable)
• The Storage trait could also be implemented for a VecSlice<'a> type, that would be backed by a &'a [MaybeUninit<T>], thus providing also the implementation for Feature: Support a fixed-dynamic-capacity Vec #353

[sosthene-nitrokey]

Ok, on our firmware (we have 4 versions) we see the following sizes (in bytes):

Current main

1397551
2007561
501460
576036

Heapless 0.8

1398803
2014626
502048
576516

This PR

1397543
2010261
501312
575940

The biggest difference we can see is from heapless 0.8 to heapless main, with a difference of 0.3% smaller firmware size. The difference is lower that what I measured previously, but I'm not sure why (I tested with heapless 0.7 at the time).

[sosthene-nitrokey]

I think It would make sense to for these structs be moved in a common module for the crate, and rename the structs to Owned and View, so that the same structs can be used for other containers ?

I think it's clearer to use the same structs for all containers.

[Dirbaio]

good point, done!

[sosthene-nitrokey]

I would instead use:

trait SealedStorage {
    type Buffer<T>: ?Sized + Borrow<[T]> + BorrowMut<[T]>;
}

And have VecInner be defined to be:

pub struct VecInner<T, S: Storage> 
    len: usize,
    buffer: S::Buffer<MaybeUninit<T>>,
}

That would make the Storage more generic, and make it usable for all container structures. For example mpmc would be defined as:

pub struct MpMcQueueInner<S: Storage> {
    pub(super) dequeue_pos: AtomicTargetSize,
    pub(super) enqueue_pos: AtomicTargetSize,
    pub(super) buffer: UnsafeCell<S::Buffer<Cell<T>>>,
}

Which can't be done if the Buffer always introduces a MaybeUninit.

[Dirbaio]

I'm not sure I see the benefits of that. My idea was that we would end up using VecView pretty much everywhere we can, and when we can't it would be because it's !Sized, and thus not

yeah it's a rather weak advantage, but I can't see why not allow it.

I would instead use: ... type Buffer<T>: ?Sized + Borrow<[T]> + BorrowMut<[T]>

very true, not all containers use MaybeUninit. Changed!

[sosthene-nitrokey]

I would add an intra-doc link to the documentation of VecView and Vec::as_view to explain what these traits are used for.

[Dirbaio]

done!

[sosthene-nitrokey]

That is indeed much cleaner for maintenance than the current duplicated documentation.
Since the size benefits are minor, I'm all for this PR.

I just wish it were possible to have the examples in the documentation of VecView to actually use VecView and not Vec but well, we can live with that.

[sosthene-nitrokey]

The implementation for Serialize for Vec should be over VecInner and generic over the Storage

[sosthene-nitrokey]

Using Storage for other implementations becomes so efficient with this !

For example String: c053490

[Dirbaio]

The implementation for Serialize for Vec should be over VecInner and generic over the Storage

done. I was also missing defmt, ufmt, done that too.