Add `push` that fails if upper bound is violated

[greenhat]

from #8 by @sethdusek:

This will be useful for using BoundedVec in sigma-rust. Also, I was wondering, what are your thoughts on adding a try_push function to BoundedVec? It'd make it a bit easier to use, it could return an Option or Result if there's no more room in the vector.

[greenhat]

This is an excellent question! Actually, I wonder if we should make all existing add/remove methods (e.g. push, pop, append, etc.) failable. I mean we have lower and upper bounds and we should error out in case we're going out of them. That'd make BoundVec API not so similar to Vec anymore, but I'm not sure it's worth sticking to it that much. What do you think?

[sethdusek]

There's some code in the WASM bindings for sigma-rust where I felt it would be useful, namely, Tokens, which currently wraps a Vec, but I plan on changing it to BoundedVec.

impl Tokens {
    /// Adds an elements to the collection
    pub fn add(&mut self, elem: &Token) {
        self.0.push(elem.clone());
    }
}

Without a try_add, this becomes a bit trickier since you need to take the BoundedVec, consume it, and create a new one. An additional suggestion is to also make Tokens::add fallable, thus this could become:

pub fn add(&mut self, elem: &Token) -> Result<(), OutOfBounds) {
    if let Some(tokens) = self.0 {
         tokens.try_add(elem.clone())?; // BoundedVec::try_add
    }
    else {
         self.0 = Some(BoundedVec::from([elem.clone()]));
    }
    Ok(())
}

[greenhat]

I totally understand the need for this. What I'm thinking is to name it not try_add but push like in Vec with a signature fn push(&mut self, elem: T) -> Result<(), OutOfBounds> {...}. Because any addition op is failable. Unless you think it might mess people up because everyone is got used to Vec::push is not failable. This is the only downside I found so far.

[sethdusek]

That seems pretty reasonable yea. By default rustc warns about unused Results anyways, so people would adapt quickly

[greenhat]

Good point! I can see that existing familiarity with Vec::push might even help.