soroban_sdk/
vec.rs

1use core::{
2    borrow::Borrow,
3    cmp::Ordering,
4    convert::Infallible,
5    fmt::Debug,
6    iter::FusedIterator,
7    marker::PhantomData,
8    ops::{Bound, RangeBounds},
9};
10
11use crate::{
12    iter::{UnwrappedEnumerable, UnwrappedIter},
13    unwrap::{UnwrapInfallible, UnwrapOptimized},
14};
15
16use super::{
17    env::internal::{Env as _, EnvBase as _, VecObject},
18    ConversionError, Env, IntoVal, TryFromVal, TryIntoVal, Val,
19};
20
21#[cfg(doc)]
22use crate::{storage::Storage, Bytes, BytesN, Map};
23
24/// Create a [Vec] with the given items.
25///
26/// The first argument in the list must be a reference to an [Env], then the
27/// items follow.
28///
29/// ### Examples
30///
31/// ```
32/// use soroban_sdk::{Env, vec};
33///
34/// let env = Env::default();
35/// let vec = vec![&env, 0, 1, 2, 3];
36/// assert_eq!(vec.len(), 4);
37/// ```
38#[macro_export]
39macro_rules! vec {
40    ($env:expr $(,)?) => {
41        $crate::Vec::new($env)
42    };
43    ($env:expr, $($x:expr),+ $(,)?) => {
44        $crate::Vec::from_array($env, [$($x),+])
45    };
46}
47
48/// Vec is a sequential and indexable growable collection type.
49///
50/// Values are stored in the environment and are available to contract through
51/// the functions defined on Vec.  Values stored in the Vec are transmitted to
52/// the environment as [Val]s, and when retrieved from the Vec are
53/// transmitted back and converted from [Val] back into their type.
54///
55/// The values in a Vec are not guaranteed to be of type `T` and conversion will
56/// fail if they are not. Most functions on Vec have a `try_` variation that
57/// returns a `Result` that will be `Err` if the conversion fails. Functions
58/// that are not prefixed with `try_` will panic if conversion fails.
59///
60/// There are some cases where this lack of guarantee is important:
61///
62/// - When storing a Vec that has been provided externally as a contract
63/// function argument, be aware there is no guarantee that all items in the Vec
64/// will be of type `T`. It may be necessary to validate all values, either
65/// before storing, or when loading with `try_` variation functions.
66///
67/// - When accessing and iterating over a Vec that has been provided externally
68/// as a contract function input, and the contract needs to be resilient to
69/// failure, use the `try_` variation functions.
70///
71/// Functions with an `_unchecked` suffix will panic if called with indexes that
72/// are out-of-bounds.
73///
74/// To store `u8`s and binary data, use [Bytes]/[BytesN] instead.
75///
76/// Vec values can be stored as [Storage], or in other types like [Vec], [Map],
77/// etc.
78///
79/// ### Examples
80///
81/// ```
82/// use soroban_sdk::{vec, Env};
83///
84/// let env = Env::default();
85/// let vec = vec![&env, 0, 1, 2, 3];
86/// assert_eq!(vec.len(), 4);
87/// ```
88pub struct Vec<T> {
89    env: Env,
90    obj: VecObject,
91    _t: PhantomData<T>,
92}
93
94impl<T> Clone for Vec<T> {
95    fn clone(&self) -> Self {
96        Self {
97            env: self.env.clone(),
98            obj: self.obj,
99            _t: self._t,
100        }
101    }
102}
103
104impl<T> Eq for Vec<T> where T: IntoVal<Env, Val> + TryFromVal<Env, Val> {}
105
106impl<T> PartialEq for Vec<T>
107where
108    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
109{
110    fn eq(&self, other: &Self) -> bool {
111        self.partial_cmp(other) == Some(Ordering::Equal)
112    }
113}
114
115impl<T> PartialOrd for Vec<T>
116where
117    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
118{
119    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
120        Some(Ord::cmp(self, other))
121    }
122}
123
124impl<T> Ord for Vec<T>
125where
126    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
127{
128    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
129        #[cfg(not(target_family = "wasm"))]
130        if !self.env.is_same_env(&other.env) {
131            return ScVal::from(self).cmp(&ScVal::from(other));
132        }
133        let v = self
134            .env
135            .obj_cmp(self.obj.to_val(), other.obj.to_val())
136            .unwrap_infallible();
137        v.cmp(&0)
138    }
139}
140
141impl<T> Debug for Vec<T>
142where
143    T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Debug + Clone,
144    T::Error: Debug,
145{
146    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
147        write!(f, "Vec(")?;
148        let mut iter = self.try_iter();
149        if let Some(x) = iter.next() {
150            write!(f, "{:?}", x)?;
151        }
152        for x in iter {
153            write!(f, ", {:?}", x)?;
154        }
155        write!(f, ")")?;
156        Ok(())
157    }
158}
159
160impl<T> TryFromVal<Env, Vec<T>> for Vec<Val> {
161    type Error = Infallible;
162
163    fn try_from_val(env: &Env, v: &Vec<T>) -> Result<Self, Self::Error> {
164        Ok(unsafe { Vec::unchecked_new(env.clone(), v.obj) })
165    }
166}
167
168// This conflicts with the previous definition unless we add the spurious &,
169// which is not .. great. Maybe don't define this particular blanket, or add
170// a to_other<T>() method?
171impl<T> TryFromVal<Env, &Vec<Val>> for Vec<T> {
172    type Error = Infallible;
173
174    fn try_from_val(env: &Env, v: &&Vec<Val>) -> Result<Self, Self::Error> {
175        Ok(unsafe { Vec::unchecked_new(env.clone(), v.obj) })
176    }
177}
178
179impl<T> TryFromVal<Env, VecObject> for Vec<T>
180where
181    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
182{
183    type Error = Infallible;
184
185    #[inline(always)]
186    fn try_from_val(env: &Env, obj: &VecObject) -> Result<Self, Self::Error> {
187        Ok(unsafe { Vec::<T>::unchecked_new(env.clone(), *obj) })
188    }
189}
190
191impl<T> TryFromVal<Env, Val> for Vec<T>
192where
193    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
194{
195    type Error = ConversionError;
196
197    #[inline(always)]
198    fn try_from_val(env: &Env, val: &Val) -> Result<Self, Self::Error> {
199        Ok(VecObject::try_from_val(env, val)?
200            .try_into_val(env)
201            .unwrap_infallible())
202    }
203}
204
205impl<T> TryFromVal<Env, Vec<T>> for Val {
206    type Error = ConversionError;
207
208    fn try_from_val(_env: &Env, v: &Vec<T>) -> Result<Self, Self::Error> {
209        Ok(v.to_val())
210    }
211}
212
213impl<T> TryFromVal<Env, &Vec<T>> for Val {
214    type Error = ConversionError;
215
216    fn try_from_val(_env: &Env, v: &&Vec<T>) -> Result<Self, Self::Error> {
217        Ok(v.to_val())
218    }
219}
220
221impl<T> From<Vec<T>> for Val
222where
223    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
224{
225    #[inline(always)]
226    fn from(v: Vec<T>) -> Self {
227        v.obj.into()
228    }
229}
230
231impl<T> From<Vec<T>> for VecObject
232where
233    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
234{
235    #[inline(always)]
236    fn from(v: Vec<T>) -> Self {
237        v.obj
238    }
239}
240
241#[cfg(not(target_family = "wasm"))]
242use super::xdr::{ScVal, ScVec, VecM};
243
244#[cfg(not(target_family = "wasm"))]
245impl<T> From<&Vec<T>> for ScVal {
246    fn from(v: &Vec<T>) -> Self {
247        // This conversion occurs only in test utilities, and theoretically all
248        // values should convert to an ScVal because the Env won't let the host
249        // type to exist otherwise, unwrapping. Even if there are edge cases
250        // that don't, this is a trade off for a better test developer
251        // experience.
252        ScVal::try_from_val(&v.env, &v.obj.to_val()).unwrap()
253    }
254}
255
256#[cfg(not(target_family = "wasm"))]
257impl<T> From<&Vec<T>> for ScVec {
258    fn from(v: &Vec<T>) -> Self {
259        if let ScVal::Vec(Some(vec)) = ScVal::try_from(v).unwrap() {
260            vec
261        } else {
262            panic!("expected ScVec")
263        }
264    }
265}
266
267#[cfg(not(target_family = "wasm"))]
268impl<T> From<Vec<T>> for VecM<ScVal> {
269    fn from(v: Vec<T>) -> Self {
270        ScVec::from(v).0
271    }
272}
273
274#[cfg(not(target_family = "wasm"))]
275impl<T> From<Vec<T>> for ScVal {
276    fn from(v: Vec<T>) -> Self {
277        (&v).into()
278    }
279}
280
281#[cfg(not(target_family = "wasm"))]
282impl<T> From<Vec<T>> for ScVec {
283    fn from(v: Vec<T>) -> Self {
284        (&v).into()
285    }
286}
287
288#[cfg(not(target_family = "wasm"))]
289impl<T> TryFromVal<Env, ScVal> for Vec<T>
290where
291    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
292{
293    type Error = ConversionError;
294    fn try_from_val(env: &Env, val: &ScVal) -> Result<Self, ConversionError> {
295        Ok(VecObject::try_from_val(env, &Val::try_from_val(env, val)?)?
296            .try_into_val(env)
297            .unwrap_infallible())
298    }
299}
300
301#[cfg(not(target_family = "wasm"))]
302impl<T> TryFromVal<Env, ScVec> for Vec<T>
303where
304    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
305{
306    type Error = ConversionError;
307    fn try_from_val(env: &Env, val: &ScVec) -> Result<Self, Self::Error> {
308        ScVal::Vec(Some(val.clone())).try_into_val(env)
309    }
310}
311
312#[cfg(not(target_family = "wasm"))]
313impl<T> TryFromVal<Env, VecM<ScVal>> for Vec<T>
314where
315    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
316{
317    type Error = ConversionError;
318    fn try_from_val(env: &Env, val: &VecM<ScVal>) -> Result<Self, Self::Error> {
319        ScVec(val.clone()).try_into_val(env)
320    }
321}
322
323impl<T> Vec<T> {
324    #[inline(always)]
325    pub(crate) unsafe fn unchecked_new(env: Env, obj: VecObject) -> Self {
326        Self {
327            env,
328            obj,
329            _t: PhantomData,
330        }
331    }
332
333    pub fn env(&self) -> &Env {
334        &self.env
335    }
336
337    pub fn as_val(&self) -> &Val {
338        self.obj.as_val()
339    }
340
341    pub fn to_val(&self) -> Val {
342        self.obj.to_val()
343    }
344
345    pub fn as_object(&self) -> &VecObject {
346        &self.obj
347    }
348
349    pub fn to_object(&self) -> VecObject {
350        self.obj
351    }
352
353    pub fn to_vals(&self) -> Vec<Val> {
354        unsafe { Vec::<Val>::unchecked_new(self.env().clone(), self.obj) }
355    }
356}
357
358impl<T> Vec<T>
359where
360    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
361{
362    /// Create an empty Vec.
363    #[inline(always)]
364    pub fn new(env: &Env) -> Vec<T> {
365        unsafe { Self::unchecked_new(env.clone(), env.vec_new().unwrap_infallible()) }
366    }
367
368    /// Create a Vec from the array of items.
369    #[inline(always)]
370    pub fn from_array<const N: usize>(env: &Env, items: [T; N]) -> Vec<T> {
371        let mut tmp: [Val; N] = [Val::VOID.to_val(); N];
372        for (dst, src) in tmp.iter_mut().zip(items.iter()) {
373            *dst = src.into_val(env)
374        }
375        let vec = env.vec_new_from_slice(&tmp).unwrap_infallible();
376        unsafe { Self::unchecked_new(env.clone(), vec) }
377    }
378
379    /// Create a Vec from an iterator of items.
380    ///
381    /// This provides FromIterator-like functionality but requires an Env parameter.
382    ///
383    /// Note: This function iteratively adds each item one at a time, making a call to the Soroban
384    /// environment for each item making it inefficient for joining two [`Vec`]s. Use
385    /// [`Vec::append`] to join two [`Vec`]s.
386    ///
387    /// ### Examples
388    ///
389    /// ```
390    /// use soroban_sdk::{Env, Vec};
391    ///
392    /// let env = Env::default();
393    /// let items = vec![1, 2, 3, 4];
394    /// let vec = Vec::from_iter(&env, items.into_iter());
395    /// assert_eq!(vec.len(), 4);
396    /// ```
397    #[inline(always)]
398    pub fn from_iter<I: IntoIterator<Item = T>>(env: &Env, iter: I) -> Vec<T> {
399        let mut vec = Self::new(env);
400        vec.extend(iter);
401        vec
402    }
403
404    /// Create a Vec from the slice of items.
405    #[inline(always)]
406    pub fn from_slice(env: &Env, items: &[T]) -> Vec<T>
407    where
408        T: Clone,
409    {
410        let mut vec = Vec::new(env);
411        vec.extend_from_slice(items);
412        vec
413    }
414
415    /// Returns the item at the position or None if out-of-bounds.
416    ///
417    /// ### Panics
418    ///
419    /// If the value at the position cannot be converted to type T.
420    #[inline(always)]
421    pub fn get(&self, i: u32) -> Option<T> {
422        self.try_get(i).unwrap_optimized()
423    }
424
425    /// Returns the item at the position or None if out-of-bounds.
426    ///
427    /// ### Errors
428    ///
429    /// If the value at the position cannot be converted to type T.
430    #[inline(always)]
431    pub fn try_get(&self, i: u32) -> Result<Option<T>, T::Error> {
432        if i < self.len() {
433            self.try_get_unchecked(i).map(|val| Some(val))
434        } else {
435            Ok(None)
436        }
437    }
438
439    /// Returns the item at the position.
440    ///
441    /// ### Panics
442    ///
443    /// If the position is out-of-bounds.
444    ///
445    /// If the value at the position cannot be converted to type T.
446    #[inline(always)]
447    pub fn get_unchecked(&self, i: u32) -> T {
448        self.try_get_unchecked(i).unwrap_optimized()
449    }
450
451    /// Returns the item at the position.
452    ///
453    /// ### Errors
454    ///
455    /// If the value at the position cannot be converted to type T.
456    ///
457    /// ### Panics
458    ///
459    /// If the position is out-of-bounds.
460    #[inline(always)]
461    pub fn try_get_unchecked(&self, i: u32) -> Result<T, T::Error> {
462        let env = self.env();
463        let val = env.vec_get(self.obj, i.into()).unwrap_infallible();
464        T::try_from_val(env, &val)
465    }
466
467    /// Sets the item at the position with new value.
468    ///
469    /// ### Panics
470    ///
471    /// If the position is out-of-bounds.
472    #[inline(always)]
473    pub fn set(&mut self, i: u32, v: T) {
474        let env = self.env();
475        self.obj = env
476            .vec_put(self.obj, i.into(), v.into_val(env))
477            .unwrap_infallible();
478    }
479
480    /// Removes the item at the position.
481    ///
482    /// Returns `None` if out-of-bounds.
483    #[inline(always)]
484    pub fn remove(&mut self, i: u32) -> Option<()> {
485        if i < self.len() {
486            self.remove_unchecked(i);
487            Some(())
488        } else {
489            None
490        }
491    }
492
493    /// Removes the item at the position.
494    ///
495    /// ### Panics
496    ///
497    /// If the position is out-of-bounds.
498    #[inline(always)]
499    pub fn remove_unchecked(&mut self, i: u32) {
500        let env = self.env();
501        self.obj = env.vec_del(self.obj, i.into()).unwrap_infallible();
502    }
503
504    /// Adds the item to the front.
505    ///
506    /// Increases the length by one, shifts all items up by one, and puts the
507    /// item in the first position.
508    #[inline(always)]
509    pub fn push_front(&mut self, x: T) {
510        let env = self.env();
511        self.obj = env
512            .vec_push_front(self.obj, x.into_val(env))
513            .unwrap_infallible();
514    }
515
516    /// Removes and returns the first item or None if empty.
517    ///
518    /// ### Panics
519    ///
520    /// If the value at the first position cannot be converted to type T.
521    #[inline(always)]
522    pub fn pop_front(&mut self) -> Option<T> {
523        self.try_pop_front().unwrap_optimized()
524    }
525
526    /// Removes and returns the first item or None if empty.
527    ///
528    /// ### Errors
529    ///
530    /// If the value at the first position cannot be converted to type T.
531    #[inline(always)]
532    pub fn try_pop_front(&mut self) -> Result<Option<T>, T::Error> {
533        if self.is_empty() {
534            Ok(None)
535        } else {
536            self.try_pop_front_unchecked().map(|val| Some(val))
537        }
538    }
539
540    /// Removes and returns the first item.
541    ///
542    /// ### Panics
543    ///
544    /// If the vec is empty.
545    ///
546    /// If the value at the first position cannot be converted to type T.
547    #[inline(always)]
548    pub fn pop_front_unchecked(&mut self) -> T {
549        self.try_pop_front_unchecked().unwrap_optimized()
550    }
551
552    /// Removes and returns the first item.
553    ///
554    /// ### Errors
555    ///
556    /// If the value at the first position cannot be converted to type T.
557    ///
558    /// ### Panics
559    ///
560    /// If the vec is empty.
561    #[inline(always)]
562    pub fn try_pop_front_unchecked(&mut self) -> Result<T, T::Error> {
563        let last = self.try_first_unchecked()?;
564        let env = self.env();
565        self.obj = env.vec_pop_front(self.obj).unwrap_infallible();
566        Ok(last)
567    }
568
569    /// Adds the item to the back.
570    ///
571    /// Increases the length by one and puts the item in the last position.
572    #[inline(always)]
573    pub fn push_back(&mut self, x: T) {
574        let env = self.env();
575        self.obj = env
576            .vec_push_back(self.obj, x.into_val(env))
577            .unwrap_infallible();
578    }
579
580    /// Removes and returns the last item or None if empty.
581    ///
582    /// ### Panics
583    ///
584    /// If the value at the last position cannot be converted to type T.
585    #[inline(always)]
586    pub fn pop_back(&mut self) -> Option<T> {
587        self.try_pop_back().unwrap_optimized()
588    }
589
590    /// Removes and returns the last item or None if empty.
591    ///
592    /// ### Errors
593    ///
594    /// If the value at the last position cannot be converted to type T.
595    #[inline(always)]
596    pub fn try_pop_back(&mut self) -> Result<Option<T>, T::Error> {
597        if self.is_empty() {
598            Ok(None)
599        } else {
600            self.try_pop_back_unchecked().map(|val| Some(val))
601        }
602    }
603
604    /// Removes and returns the last item.
605    ///
606    /// ### Panics
607    ///
608    /// If the vec is empty.
609    ///
610    /// If the value at the last position cannot be converted to type T.
611    #[inline(always)]
612    pub fn pop_back_unchecked(&mut self) -> T {
613        self.try_pop_back_unchecked().unwrap_optimized()
614    }
615
616    /// Removes and returns the last item.
617    ///
618    /// ### Errors
619    ///
620    /// If the value at the last position cannot be converted to type T.
621    ///
622    /// ### Panics
623    ///
624    /// If the vec is empty.
625    #[inline(always)]
626    pub fn try_pop_back_unchecked(&mut self) -> Result<T, T::Error> {
627        let last = self.try_last_unchecked()?;
628        let env = self.env();
629        self.obj = env.vec_pop_back(self.obj).unwrap_infallible();
630        Ok(last)
631    }
632
633    /// Returns the first item or None if empty.
634    ///
635    /// ### Panics
636    ///
637    /// If the value at the first position cannot be converted to type T.
638    #[inline(always)]
639    pub fn first(&self) -> Option<T> {
640        self.try_first().unwrap_optimized()
641    }
642
643    /// Returns the first item or None if empty.
644    ///
645    /// ### Errors
646    ///
647    /// If the value at the first position cannot be converted to type T.
648    #[inline(always)]
649    pub fn try_first(&self) -> Result<Option<T>, T::Error> {
650        if self.is_empty() {
651            Ok(None)
652        } else {
653            self.try_first_unchecked().map(|val| Some(val))
654        }
655    }
656
657    /// Returns the first item.
658    ///
659    /// ### Panics
660    ///
661    /// If the vec is empty.
662    ///
663    /// If the value at the first position cannot be converted to type T.
664    #[inline(always)]
665    pub fn first_unchecked(&self) -> T {
666        self.try_first_unchecked().unwrap_optimized()
667    }
668
669    /// Returns the first item.
670    ///
671    /// ### Errors
672    ///
673    /// If the value at the first position cannot be converted to type T.
674    ///
675    /// ### Panics
676    ///
677    /// If the vec is empty.
678    #[inline(always)]
679    pub fn try_first_unchecked(&self) -> Result<T, T::Error> {
680        let env = &self.env;
681        let val = env.vec_front(self.obj).unwrap_infallible();
682        T::try_from_val(env, &val)
683    }
684
685    /// Returns the last item or None if empty.
686    ///
687    /// ### Panics
688    ///
689    /// If the value at the last position cannot be converted to type T.
690    #[inline(always)]
691    pub fn last(&self) -> Option<T> {
692        self.try_last().unwrap_optimized()
693    }
694
695    /// Returns the last item or None if empty.
696    ///
697    /// ### Errors
698    ///
699    /// If the value at the last position cannot be converted to type T.
700    #[inline(always)]
701    pub fn try_last(&self) -> Result<Option<T>, T::Error> {
702        if self.is_empty() {
703            Ok(None)
704        } else {
705            self.try_last_unchecked().map(|val| Some(val))
706        }
707    }
708
709    /// Returns the last item.
710    ///
711    /// ### Panics
712    ///
713    /// If the vec is empty.
714    ///
715    /// If the value at the last position cannot be converted to type T.
716    #[inline(always)]
717    pub fn last_unchecked(&self) -> T {
718        self.try_last_unchecked().unwrap_optimized()
719    }
720
721    /// Returns the last item.
722    ///
723    /// ### Errors
724    ///
725    /// If the value at the last position cannot be converted to type T.
726    ///
727    /// ### Panics
728    ///
729    /// If the vec is empty.
730    #[inline(always)]
731    pub fn try_last_unchecked(&self) -> Result<T, T::Error> {
732        let env = self.env();
733        let val = env.vec_back(self.obj).unwrap_infallible();
734        T::try_from_val(env, &val)
735    }
736
737    /// Inserts an item at the position.
738    ///
739    /// ### Panics
740    ///
741    /// If the position is out-of-bounds.
742    #[inline(always)]
743    pub fn insert(&mut self, i: u32, x: T) {
744        let env = self.env();
745        self.obj = env
746            .vec_insert(self.obj, i.into(), x.into_val(env))
747            .unwrap_infallible();
748    }
749
750    /// Append the items.
751    #[inline(always)]
752    pub fn append(&mut self, other: &Vec<T>) {
753        let env = self.env();
754        self.obj = env.vec_append(self.obj, other.obj).unwrap_infallible();
755    }
756
757    /// Extend with the items in the array.
758    #[inline(always)]
759    pub fn extend_from_array<const N: usize>(&mut self, items: [T; N]) {
760        self.append(&Self::from_array(&self.env, items))
761    }
762
763    /// Extend with the items in the slice.
764    #[inline(always)]
765    pub fn extend_from_slice(&mut self, items: &[T])
766    where
767        T: Clone,
768    {
769        for item in items {
770            self.push_back(item.clone());
771        }
772    }
773}
774
775impl<T> Vec<T> {
776    /// Returns a subset of the bytes as defined by the start and end bounds of
777    /// the range.
778    ///
779    /// ### Panics
780    ///
781    /// If the range is out-of-bounds.
782    #[must_use]
783    pub fn slice(&self, r: impl RangeBounds<u32>) -> Self {
784        let start_bound = match r.start_bound() {
785            Bound::Included(s) => *s,
786            Bound::Excluded(s) => s
787                .checked_add(1)
788                .expect_optimized("attempt to add with overflow"),
789            Bound::Unbounded => 0,
790        };
791        let end_bound = match r.end_bound() {
792            Bound::Included(s) => s
793                .checked_add(1)
794                .expect_optimized("attempt to add with overflow"),
795            Bound::Excluded(s) => *s,
796            Bound::Unbounded => self.len(),
797        };
798        let env = self.env();
799        let obj = env
800            .vec_slice(self.obj, start_bound.into(), end_bound.into())
801            .unwrap_infallible();
802        unsafe { Self::unchecked_new(env.clone(), obj) }
803    }
804
805    /// Returns copy of the vec shuffled using the NOT-SECURE PRNG.
806    ///
807    /// In tests, must be called from within a running contract.
808    ///
809    /// # Warning
810    ///
811    /// **The pseudo-random generator used to perform the shuffle is not
812    /// suitable for security-sensitive work.**
813    pub fn shuffle(&mut self) {
814        let env = self.env();
815        env.prng().shuffle(self);
816    }
817
818    /// Returns copy of the vec shuffled using the NOT-SECURE PRNG.
819    ///
820    /// In tests, must be called from within a running contract.
821    ///
822    /// # Warning
823    ///
824    /// **The pseudo-random generator used to perform the shuffle is not
825    /// suitable for security-sensitive work.**
826    #[must_use]
827    pub fn to_shuffled(&self) -> Self {
828        let mut copy = self.clone();
829        copy.shuffle();
830        copy
831    }
832
833    /// Returns true if the vec is empty and contains no items.
834    #[inline(always)]
835    pub fn is_empty(&self) -> bool {
836        self.len() == 0
837    }
838
839    /// Returns the number of items in the vec.
840    #[inline(always)]
841    pub fn len(&self) -> u32 {
842        self.env.vec_len(self.obj).unwrap_infallible().into()
843    }
844}
845
846impl<T> Vec<T>
847where
848    T: IntoVal<Env, Val>,
849{
850    /// Returns true if the Vec contains the item.
851    #[inline(always)]
852    pub fn contains(&self, item: impl Borrow<T>) -> bool {
853        let env = self.env();
854        let val = item.borrow().into_val(env);
855        !env.vec_first_index_of(self.obj, val)
856            .unwrap_infallible()
857            .is_void()
858    }
859
860    /// Returns the index of the first occurrence of the item.
861    ///
862    /// If the item cannot be found [None] is returned.
863    #[inline(always)]
864    pub fn first_index_of(&self, item: impl Borrow<T>) -> Option<u32> {
865        let env = self.env();
866        let val = item.borrow().into_val(env);
867        env.vec_first_index_of(self.obj, val)
868            .unwrap_infallible()
869            .try_into_val(env)
870            .unwrap()
871    }
872
873    /// Returns the index of the last occurrence of the item.
874    ///
875    /// If the item cannot be found [None] is returned.
876    #[inline(always)]
877    pub fn last_index_of(&self, item: impl Borrow<T>) -> Option<u32> {
878        let env = self.env();
879        let val = item.borrow().into_val(env);
880        env.vec_last_index_of(self.obj, val)
881            .unwrap_infallible()
882            .try_into_val(env)
883            .unwrap()
884    }
885
886    /// Returns the index of an occurrence of the item in an already sorted
887    /// [Vec], or the index of where the item can be inserted to keep the [Vec]
888    /// sorted.
889    ///
890    /// If the item is found, [Result::Ok] is returned containing the index of
891    /// the item.
892    ///
893    /// If the item is not found, [Result::Err] is returned containing the index
894    /// of where the item could be inserted to retain the sorted ordering.
895    #[inline(always)]
896    pub fn binary_search(&self, item: impl Borrow<T>) -> Result<u32, u32> {
897        let env = self.env();
898        let val = item.borrow().into_val(env);
899        let high_low = env.vec_binary_search(self.obj, val).unwrap_infallible();
900        let high: u32 = (high_low >> u32::BITS) as u32;
901        let low: u32 = high_low as u32;
902        if high == 1 {
903            Ok(low)
904        } else {
905            Err(low)
906        }
907    }
908}
909
910impl<T> Vec<Vec<T>>
911where
912    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
913    T: Clone,
914{
915    #[inline(always)]
916    pub fn concat(&self) -> Vec<T> {
917        let mut concatenated = vec![self.env()];
918        for vec in self.iter() {
919            concatenated.append(&vec);
920        }
921        concatenated
922    }
923}
924
925impl<T> IntoIterator for Vec<T>
926where
927    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
928{
929    type Item = T;
930    type IntoIter = UnwrappedIter<VecTryIter<T>, T, T::Error>;
931
932    fn into_iter(self) -> Self::IntoIter {
933        VecTryIter::new(self).unwrapped()
934    }
935}
936
937impl<T> IntoIterator for &Vec<T>
938where
939    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
940{
941    type Item = T;
942    type IntoIter = UnwrappedIter<VecTryIter<T>, T, T::Error>;
943
944    fn into_iter(self) -> Self::IntoIter {
945        self.clone().into_iter()
946    }
947}
948
949impl<T> Extend<T> for Vec<T>
950where
951    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
952{
953    fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
954        for item in iter {
955            self.push_back(item);
956        }
957    }
958}
959
960impl<T> Vec<T>
961where
962    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
963{
964    /// Returns an iterator over the elements of the vec.
965    ///
966    /// Each element is converted from [Val] to `T` as it is yielded.
967    ///
968    /// ### Panics
969    ///
970    /// If any element cannot be converted to type `T`. Use
971    /// [`try_iter`](Vec::try_iter) to handle conversion errors.
972    #[inline(always)]
973    pub fn iter(&self) -> UnwrappedIter<VecTryIter<T>, T, T::Error>
974    where
975        T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
976        T::Error: Debug,
977    {
978        self.try_iter().unwrapped()
979    }
980
981    /// Returns an iterator over the elements of the vec, yielding
982    /// `Result<T, ConversionError>` for each element.
983    #[inline(always)]
984    pub fn try_iter(&self) -> VecTryIter<T>
985    where
986        T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
987    {
988        VecTryIter::new(self.clone())
989    }
990
991    #[inline(always)]
992    pub fn into_try_iter(self) -> VecTryIter<T>
993    where
994        T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
995        T::Error: Debug,
996    {
997        VecTryIter::new(self)
998    }
999}
1000
1001#[derive(Clone)]
1002pub struct VecTryIter<T> {
1003    vec: Vec<T>,
1004    start: u32, // inclusive
1005    end: u32,   // exclusive
1006}
1007
1008impl<T> VecTryIter<T> {
1009    fn new(vec: Vec<T>) -> Self {
1010        Self {
1011            start: 0,
1012            end: vec.len(),
1013            vec,
1014        }
1015    }
1016
1017    fn into_vec(self) -> Vec<T> {
1018        self.vec.slice(self.start..self.end)
1019    }
1020}
1021
1022impl<T> Iterator for VecTryIter<T>
1023where
1024    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
1025{
1026    type Item = Result<T, T::Error>;
1027
1028    fn next(&mut self) -> Option<Self::Item> {
1029        if self.start < self.end {
1030            let val = self.vec.try_get_unchecked(self.start);
1031            self.start += 1;
1032            Some(val)
1033        } else {
1034            None
1035        }
1036    }
1037
1038    fn size_hint(&self) -> (usize, Option<usize>) {
1039        let len = (self.end - self.start) as usize;
1040        (len, Some(len))
1041    }
1042
1043    // TODO: Implement other functions as optimizations since the iterator is
1044    // backed by an indexable collection.
1045}
1046
1047impl<T> DoubleEndedIterator for VecTryIter<T>
1048where
1049    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
1050{
1051    fn next_back(&mut self) -> Option<Self::Item> {
1052        if self.start < self.end {
1053            let val = self.vec.try_get_unchecked(self.end - 1);
1054            self.end -= 1;
1055            Some(val)
1056        } else {
1057            None
1058        }
1059    }
1060
1061    // TODO: Implement other functions as optimizations since the iterator is
1062    // backed by an indexable collection.
1063}
1064
1065impl<T> FusedIterator for VecTryIter<T> where T: IntoVal<Env, Val> + TryFromVal<Env, Val> {}
1066
1067impl<T> ExactSizeIterator for VecTryIter<T>
1068where
1069    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
1070{
1071    fn len(&self) -> usize {
1072        (self.end - self.start) as usize
1073    }
1074}
1075
1076#[cfg(test)]
1077mod test {
1078    use super::*;
1079
1080    #[test]
1081    fn test_vec_macro() {
1082        let env = Env::default();
1083        assert_eq!(vec![&env], Vec::<i32>::new(&env));
1084        assert_eq!(vec![&env,], Vec::<i32>::new(&env));
1085        assert_eq!(vec![&env, 1], {
1086            let mut v = Vec::new(&env);
1087            v.push_back(1);
1088            v
1089        });
1090        assert_eq!(vec![&env, 1,], {
1091            let mut v = Vec::new(&env);
1092            v.push_back(1);
1093            v
1094        });
1095        assert_eq!(vec![&env, 3, 2, 1,], {
1096            let mut v = Vec::new(&env);
1097            v.push_back(3);
1098            v.push_back(2);
1099            v.push_back(1);
1100            v
1101        });
1102    }
1103
1104    #[test]
1105    fn test_vec_to_val() {
1106        let env = Env::default();
1107
1108        let vec = Vec::<u32>::from_slice(&env, &[0, 1, 2, 3]);
1109        let val: Val = vec.clone().into_val(&env);
1110        let rt: Vec<u32> = val.into_val(&env);
1111
1112        assert_eq!(vec, rt);
1113    }
1114
1115    #[test]
1116    fn test_ref_vec_to_val() {
1117        let env = Env::default();
1118
1119        let vec = Vec::<u32>::from_slice(&env, &[0, 1, 2, 3]);
1120        let val: Val = (&vec).into_val(&env);
1121        let rt: Vec<u32> = val.into_val(&env);
1122
1123        assert_eq!(vec, rt);
1124    }
1125
1126    #[test]
1127    fn test_double_ref_vec_to_val() {
1128        let env = Env::default();
1129
1130        let vec = Vec::<u32>::from_slice(&env, &[0, 1, 2, 3]);
1131        let val: Val = (&&vec).into_val(&env);
1132        let rt: Vec<u32> = val.into_val(&env);
1133
1134        assert_eq!(vec, rt);
1135    }
1136
1137    #[test]
1138    fn test_vec_raw_val_type() {
1139        let env = Env::default();
1140
1141        let mut vec = Vec::<u32>::new(&env);
1142        assert_eq!(vec.len(), 0);
1143        vec.push_back(10);
1144        assert_eq!(vec.len(), 1);
1145        vec.push_back(20);
1146        assert_eq!(vec.len(), 2);
1147        vec.push_back(30);
1148        assert_eq!(vec.len(), 3);
1149
1150        let vec_ref = &vec;
1151        assert_eq!(vec_ref.len(), 3);
1152
1153        let mut vec_copy = vec.clone();
1154        assert!(vec == vec_copy);
1155        assert_eq!(vec_copy.len(), 3);
1156        vec_copy.push_back(40);
1157        assert_eq!(vec_copy.len(), 4);
1158        assert!(vec != vec_copy);
1159
1160        assert_eq!(vec.len(), 3);
1161        assert_eq!(vec_ref.len(), 3);
1162
1163        _ = vec_copy.pop_back_unchecked();
1164        assert!(vec == vec_copy);
1165    }
1166
1167    #[test]
1168    fn test_vec_env_val_type() {
1169        let env = Env::default();
1170
1171        let mut vec = Vec::<i64>::new(&env);
1172        assert_eq!(vec.len(), 0);
1173        vec.push_back(-10);
1174        assert_eq!(vec.len(), 1);
1175        vec.push_back(20);
1176        assert_eq!(vec.len(), 2);
1177        vec.push_back(-30);
1178        assert_eq!(vec.len(), 3);
1179
1180        let vec_ref = &vec;
1181        assert_eq!(vec_ref.len(), 3);
1182
1183        let mut vec_copy = vec.clone();
1184        assert!(vec == vec_copy);
1185        assert_eq!(vec_copy.len(), 3);
1186        vec_copy.push_back(40);
1187        assert_eq!(vec_copy.len(), 4);
1188        assert!(vec != vec_copy);
1189
1190        assert_eq!(vec.len(), 3);
1191        assert_eq!(vec_ref.len(), 3);
1192
1193        _ = vec_copy.pop_back_unchecked();
1194        assert!(vec == vec_copy);
1195    }
1196
1197    #[test]
1198    fn test_vec_to_vals() {
1199        let env = Env::default();
1200        let vec = vec![&env, 0, 1, 2, 3, 4];
1201        let vals = vec.to_vals();
1202        assert_eq!(
1203            vals,
1204            vec![
1205                &env,
1206                Val::from_i32(0).to_val(),
1207                Val::from_i32(1).to_val(),
1208                Val::from_i32(2).to_val(),
1209                Val::from_i32(3).to_val(),
1210                Val::from_i32(4).to_val(),
1211            ]
1212        );
1213    }
1214
1215    #[test]
1216    fn test_vec_recursive() {
1217        let env = Env::default();
1218
1219        let mut vec_inner = Vec::<i64>::new(&env);
1220        vec_inner.push_back(-10);
1221        assert_eq!(vec_inner.len(), 1);
1222
1223        let mut vec_outer = Vec::<Vec<i64>>::new(&env);
1224        vec_outer.push_back(vec_inner);
1225        assert_eq!(vec_outer.len(), 1);
1226    }
1227
1228    #[test]
1229    fn test_vec_concat() {
1230        let env = Env::default();
1231        let vec_1: Vec<i64> = vec![&env, 1, 2, 3];
1232        let vec_2: Vec<i64> = vec![&env, 4, 5, 6];
1233        let vec = vec![&env, vec_1, vec_2].concat();
1234        assert_eq!(vec, vec![&env, 1, 2, 3, 4, 5, 6]);
1235    }
1236
1237    #[test]
1238    fn test_vec_slice() {
1239        let env = Env::default();
1240
1241        let vec = vec![&env, 0, 1, 2, 3, 4];
1242        assert_eq!(vec.len(), 5);
1243
1244        let slice = vec.slice(..);
1245        assert_eq!(slice, vec![&env, 0, 1, 2, 3, 4]);
1246
1247        let slice = vec.slice(0..5);
1248        assert_eq!(slice, vec![&env, 0, 1, 2, 3, 4]);
1249
1250        let slice = vec.slice(0..=4);
1251        assert_eq!(slice, vec![&env, 0, 1, 2, 3, 4]);
1252
1253        let slice = vec.slice(1..);
1254        assert_eq!(slice, vec![&env, 1, 2, 3, 4]);
1255
1256        let slice = vec.slice(..4);
1257        assert_eq!(slice, vec![&env, 0, 1, 2, 3]);
1258
1259        let slice = vec.slice(..=3);
1260        assert_eq!(slice, vec![&env, 0, 1, 2, 3]);
1261
1262        let slice = vec.slice(1..4);
1263        assert_eq!(slice, vec![&env, 1, 2, 3]);
1264
1265        let slice = vec.slice(1..=3);
1266        assert_eq!(slice, vec![&env, 1, 2, 3]);
1267
1268        // An exclusive start is technically possible due to the lack of
1269        // constraints in the RangeBounds trait, however this is unlikely to
1270        // happen since no syntax shorthand exists for it.
1271        let slice = vec.slice((Bound::Excluded(0), Bound::Included(3)));
1272        assert_eq!(slice, vec![&env, 1, 2, 3]);
1273        let slice = vec.slice((Bound::Excluded(0), Bound::Excluded(3)));
1274        assert_eq!(slice, vec![&env, 1, 2]);
1275    }
1276
1277    #[test]
1278    fn test_vec_iter() {
1279        let env = Env::default();
1280
1281        let vec: Vec<()> = vec![&env];
1282        let mut iter = vec.iter();
1283        assert_eq!(iter.len(), 0);
1284        assert_eq!(iter.next(), None);
1285        assert_eq!(iter.next(), None);
1286
1287        let vec = vec![&env, 0, 1, 2, 3, 4];
1288
1289        let mut iter = vec.iter();
1290        assert_eq!(iter.len(), 5);
1291        assert_eq!(iter.next(), Some(0));
1292        assert_eq!(iter.len(), 4);
1293        assert_eq!(iter.next(), Some(1));
1294        assert_eq!(iter.len(), 3);
1295        assert_eq!(iter.next(), Some(2));
1296        assert_eq!(iter.len(), 2);
1297        assert_eq!(iter.next(), Some(3));
1298        assert_eq!(iter.len(), 1);
1299        assert_eq!(iter.next(), Some(4));
1300        assert_eq!(iter.len(), 0);
1301        assert_eq!(iter.next(), None);
1302        assert_eq!(iter.next(), None);
1303
1304        let mut iter = vec.iter();
1305        assert_eq!(iter.len(), 5);
1306        assert_eq!(iter.next(), Some(0));
1307        assert_eq!(iter.len(), 4);
1308        assert_eq!(iter.next_back(), Some(4));
1309        assert_eq!(iter.len(), 3);
1310        assert_eq!(iter.next_back(), Some(3));
1311        assert_eq!(iter.len(), 2);
1312        assert_eq!(iter.next(), Some(1));
1313        assert_eq!(iter.len(), 1);
1314        assert_eq!(iter.next(), Some(2));
1315        assert_eq!(iter.len(), 0);
1316        assert_eq!(iter.next(), None);
1317        assert_eq!(iter.next(), None);
1318        assert_eq!(iter.next_back(), None);
1319        assert_eq!(iter.next_back(), None);
1320
1321        let mut iter = vec.iter().rev();
1322        assert_eq!(iter.next(), Some(4));
1323        assert_eq!(iter.next_back(), Some(0));
1324        assert_eq!(iter.next_back(), Some(1));
1325        assert_eq!(iter.next(), Some(3));
1326        assert_eq!(iter.next(), Some(2));
1327        assert_eq!(iter.next(), None);
1328        assert_eq!(iter.next(), None);
1329        assert_eq!(iter.next_back(), None);
1330        assert_eq!(iter.next_back(), None);
1331    }
1332
1333    #[test]
1334    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1335    fn test_vec_iter_panic_on_conversion() {
1336        let env = Env::default();
1337
1338        let vec: Val = (1i32,).try_into_val(&env).unwrap();
1339        let vec: Vec<i64> = vec.try_into_val(&env).unwrap();
1340
1341        let mut iter = vec.iter();
1342        iter.next();
1343    }
1344
1345    #[test]
1346    fn test_vec_try_iter() {
1347        let env = Env::default();
1348
1349        let vec: Vec<()> = vec![&env];
1350        let mut iter = vec.try_iter();
1351        assert_eq!(iter.len(), 0);
1352        assert_eq!(iter.next(), None);
1353        assert_eq!(iter.next(), None);
1354
1355        let vec = vec![&env, 0, 1, 2, 3, 4];
1356
1357        let mut iter = vec.try_iter();
1358        assert_eq!(iter.len(), 5);
1359        assert_eq!(iter.next(), Some(Ok(0)));
1360        assert_eq!(iter.len(), 4);
1361        assert_eq!(iter.next(), Some(Ok(1)));
1362        assert_eq!(iter.len(), 3);
1363        assert_eq!(iter.next(), Some(Ok(2)));
1364        assert_eq!(iter.len(), 2);
1365        assert_eq!(iter.next(), Some(Ok(3)));
1366        assert_eq!(iter.len(), 1);
1367        assert_eq!(iter.next(), Some(Ok(4)));
1368        assert_eq!(iter.len(), 0);
1369        assert_eq!(iter.next(), None);
1370        assert_eq!(iter.next(), None);
1371
1372        let mut iter = vec.try_iter();
1373        assert_eq!(iter.len(), 5);
1374        assert_eq!(iter.next(), Some(Ok(0)));
1375        assert_eq!(iter.len(), 4);
1376        assert_eq!(iter.next_back(), Some(Ok(4)));
1377        assert_eq!(iter.len(), 3);
1378        assert_eq!(iter.next_back(), Some(Ok(3)));
1379        assert_eq!(iter.len(), 2);
1380        assert_eq!(iter.next(), Some(Ok(1)));
1381        assert_eq!(iter.len(), 1);
1382        assert_eq!(iter.next(), Some(Ok(2)));
1383        assert_eq!(iter.len(), 0);
1384        assert_eq!(iter.next(), None);
1385        assert_eq!(iter.next(), None);
1386        assert_eq!(iter.next_back(), None);
1387        assert_eq!(iter.next_back(), None);
1388
1389        let mut iter = vec.try_iter().rev();
1390        assert_eq!(iter.next(), Some(Ok(4)));
1391        assert_eq!(iter.next_back(), Some(Ok(0)));
1392        assert_eq!(iter.next_back(), Some(Ok(1)));
1393        assert_eq!(iter.next(), Some(Ok(3)));
1394        assert_eq!(iter.next(), Some(Ok(2)));
1395        assert_eq!(iter.next(), None);
1396        assert_eq!(iter.next(), None);
1397        assert_eq!(iter.next_back(), None);
1398        assert_eq!(iter.next_back(), None);
1399    }
1400
1401    #[test]
1402    fn test_vec_try_iter_error_on_conversion() {
1403        let env = Env::default();
1404
1405        let vec: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1406        let vec: Vec<i64> = vec.try_into_val(&env).unwrap();
1407
1408        let mut iter = vec.try_iter();
1409        assert_eq!(iter.next(), Some(Ok(1)));
1410        assert_eq!(iter.next(), Some(Err(ConversionError.into())));
1411    }
1412
1413    #[test]
1414    fn test_vec_iter_into_vec() {
1415        let env = Env::default();
1416
1417        let vec = vec![&env, 0, 1, 2, 3, 4];
1418
1419        let mut iter = vec.try_iter();
1420        assert_eq!(iter.next(), Some(Ok(0)));
1421        assert_eq!(iter.next(), Some(Ok(1)));
1422        assert_eq!(iter.into_vec(), vec![&env, 2, 3, 4]);
1423    }
1424
1425    #[test]
1426    fn test_contains() {
1427        let env = Env::default();
1428        let vec = vec![&env, 0, 3, 5, 7, 9, 5];
1429        assert_eq!(vec.contains(&2), false);
1430        assert_eq!(vec.contains(2), false);
1431        assert_eq!(vec.contains(&3), true);
1432        assert_eq!(vec.contains(3), true);
1433        assert_eq!(vec.contains(&5), true);
1434        assert_eq!(vec.contains(5), true);
1435    }
1436
1437    #[test]
1438    fn test_first_index_of() {
1439        let env = Env::default();
1440
1441        let vec = vec![&env, 0, 3, 5, 7, 9, 5];
1442        assert_eq!(vec.first_index_of(&2), None);
1443        assert_eq!(vec.first_index_of(2), None);
1444        assert_eq!(vec.first_index_of(&3), Some(1));
1445        assert_eq!(vec.first_index_of(3), Some(1));
1446        assert_eq!(vec.first_index_of(&5), Some(2));
1447        assert_eq!(vec.first_index_of(5), Some(2));
1448    }
1449
1450    #[test]
1451    fn test_last_index_of() {
1452        let env = Env::default();
1453
1454        let vec = vec![&env, 0, 3, 5, 7, 9, 5];
1455        assert_eq!(vec.last_index_of(&2), None);
1456        assert_eq!(vec.last_index_of(2), None);
1457        assert_eq!(vec.last_index_of(&3), Some(1));
1458        assert_eq!(vec.last_index_of(3), Some(1));
1459        assert_eq!(vec.last_index_of(&5), Some(5));
1460        assert_eq!(vec.last_index_of(5), Some(5));
1461    }
1462
1463    #[test]
1464    fn test_binary_search() {
1465        let env = Env::default();
1466
1467        let vec = vec![&env, 0, 3, 5, 5, 7, 9];
1468        assert_eq!(vec.binary_search(&2), Err(1));
1469        assert_eq!(vec.binary_search(2), Err(1));
1470        assert_eq!(vec.binary_search(&3), Ok(1));
1471        assert_eq!(vec.binary_search(3), Ok(1));
1472        assert_eq!(vec.binary_search(&5), Ok(3));
1473        assert_eq!(vec.binary_search(5), Ok(3));
1474    }
1475
1476    #[cfg(not(target_family = "wasm"))]
1477    #[test]
1478    fn test_scval_accessibility_from_udt_types() {
1479        use crate::TryFromVal;
1480        let env = Env::default();
1481        let v = vec![&env, 1];
1482        let val: ScVal = v.clone().try_into().unwrap();
1483        let roundtrip = Vec::<i64>::try_from_val(&env, &val).unwrap();
1484        assert_eq!(v, roundtrip);
1485    }
1486
1487    #[test]
1488    fn test_insert_and_set() {
1489        let env = Env::default();
1490        let mut v = Vec::<i64>::new(&env);
1491        v.insert(0, 3);
1492        v.insert(0, 1);
1493        v.insert(1, 4);
1494        v.insert(3, 6);
1495        assert_eq!(v, vec![&env, 1, 4, 3, 6]);
1496        v.set(0, 7);
1497        v.set(1, 6);
1498        v.set(2, 2);
1499        v.set(3, 5);
1500        assert_eq!(v, vec![&env, 7, 6, 2, 5]);
1501    }
1502
1503    #[test]
1504    fn test_is_empty_and_len() {
1505        let env = Env::default();
1506
1507        let mut v: Vec<i32> = vec![&env, 1, 4, 3];
1508        assert_eq!(v.is_empty(), false);
1509        assert_eq!(v.len(), 3);
1510
1511        v = vec![&env];
1512        assert_eq!(v.is_empty(), true);
1513        assert_eq!(v.len(), 0);
1514    }
1515
1516    #[test]
1517    fn test_push_pop_front() {
1518        let env = Env::default();
1519
1520        let mut v = Vec::<i64>::new(&env);
1521        v.push_front(42);
1522        assert_eq!(v, vec![&env, 42]);
1523        v.push_front(1);
1524        assert_eq!(v, vec![&env, 1, 42]);
1525        v.push_front(5);
1526        assert_eq!(v, vec![&env, 5, 1, 42]);
1527        v.push_front(7);
1528        assert_eq!(v, vec![&env, 7, 5, 1, 42]);
1529
1530        let popped = v.pop_front();
1531        assert_eq!(popped, Some(7));
1532        assert_eq!(v, vec![&env, 5, 1, 42]);
1533
1534        let popped = v.try_pop_front();
1535        assert_eq!(popped, Ok(Some(5)));
1536        assert_eq!(v, vec![&env, 1, 42]);
1537
1538        let popped = v.pop_front_unchecked();
1539        assert_eq!(popped, 1);
1540        assert_eq!(v, vec![&env, 42]);
1541
1542        let popped = v.try_pop_front_unchecked();
1543        assert_eq!(popped, Ok(42));
1544        assert_eq!(v, vec![&env]);
1545
1546        assert_eq!(v.pop_front(), None);
1547    }
1548
1549    #[test]
1550    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1551    fn test_pop_front_panics_on_conversion() {
1552        let env = Env::default();
1553
1554        let v: Val = (1i32,).try_into_val(&env).unwrap();
1555        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1556
1557        v.pop_front();
1558    }
1559
1560    #[test]
1561    fn test_try_pop_front_errors_on_conversion() {
1562        let env = Env::default();
1563
1564        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1565        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1566
1567        assert_eq!(v.try_pop_front(), Ok(Some(1)));
1568        assert_eq!(v.try_pop_front(), Err(ConversionError.into()));
1569    }
1570
1571    #[test]
1572    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1573    fn test_pop_front_unchecked_panics_on_conversion() {
1574        let env = Env::default();
1575
1576        let v: Val = (1i32,).try_into_val(&env).unwrap();
1577        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1578
1579        v.pop_front_unchecked();
1580    }
1581
1582    #[test]
1583    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1584    fn test_pop_front_unchecked_panics_on_out_of_bounds() {
1585        let env = Env::default();
1586
1587        let mut v = Vec::<i64>::new(&env);
1588
1589        v.pop_front_unchecked();
1590    }
1591
1592    #[test]
1593    fn test_try_pop_front_unchecked_errors_on_conversion() {
1594        let env = Env::default();
1595
1596        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1597        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1598
1599        assert_eq!(v.try_pop_front_unchecked(), Ok(1));
1600        assert_eq!(v.try_pop_front_unchecked(), Err(ConversionError.into()));
1601    }
1602
1603    #[test]
1604    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1605    fn test_try_pop_front_unchecked_panics_on_out_of_bounds() {
1606        let env = Env::default();
1607
1608        let mut v = Vec::<i64>::new(&env);
1609
1610        let _ = v.try_pop_front_unchecked();
1611    }
1612
1613    #[test]
1614    fn test_push_pop_back() {
1615        let env = Env::default();
1616
1617        let mut v = Vec::<i64>::new(&env);
1618        v.push_back(42);
1619        assert_eq!(v, vec![&env, 42]);
1620        v.push_back(1);
1621        assert_eq!(v, vec![&env, 42, 1]);
1622        v.push_back(5);
1623        assert_eq!(v, vec![&env, 42, 1, 5]);
1624        v.push_back(7);
1625        assert_eq!(v, vec![&env, 42, 1, 5, 7]);
1626
1627        let popped = v.pop_back();
1628        assert_eq!(popped, Some(7));
1629        assert_eq!(v, vec![&env, 42, 1, 5]);
1630
1631        let popped = v.try_pop_back();
1632        assert_eq!(popped, Ok(Some(5)));
1633        assert_eq!(v, vec![&env, 42, 1]);
1634
1635        let popped = v.pop_back_unchecked();
1636        assert_eq!(popped, 1);
1637        assert_eq!(v, vec![&env, 42]);
1638
1639        let popped = v.try_pop_back_unchecked();
1640        assert_eq!(popped, Ok(42));
1641        assert_eq!(v, vec![&env]);
1642
1643        assert_eq!(v.pop_back(), None);
1644    }
1645
1646    #[test]
1647    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1648    fn test_pop_back_panics_on_conversion() {
1649        let env = Env::default();
1650
1651        let v: Val = (1i32,).try_into_val(&env).unwrap();
1652        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1653
1654        v.pop_back();
1655    }
1656
1657    #[test]
1658    fn test_try_pop_back_errors_on_conversion() {
1659        let env = Env::default();
1660
1661        let v: Val = (1i32, 2i64).try_into_val(&env).unwrap();
1662        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1663
1664        assert_eq!(v.try_pop_back(), Ok(Some(2)));
1665        assert_eq!(v.try_pop_back(), Err(ConversionError.into()));
1666    }
1667
1668    #[test]
1669    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1670    fn test_pop_back_unchecked_panics_on_conversion() {
1671        let env = Env::default();
1672
1673        let v: Val = (1i32,).try_into_val(&env).unwrap();
1674        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1675
1676        v.pop_back_unchecked();
1677    }
1678
1679    #[test]
1680    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1681    fn test_pop_back_unchecked_panics_on_out_of_bounds() {
1682        let env = Env::default();
1683
1684        let mut v = Vec::<i64>::new(&env);
1685
1686        v.pop_back_unchecked();
1687    }
1688
1689    #[test]
1690    fn test_try_pop_back_unchecked_errors_on_conversion() {
1691        let env = Env::default();
1692
1693        let v: Val = (1i32, 2i64).try_into_val(&env).unwrap();
1694        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1695
1696        assert_eq!(v.try_pop_back_unchecked(), Ok(2));
1697        assert_eq!(v.try_pop_back_unchecked(), Err(ConversionError.into()));
1698    }
1699
1700    #[test]
1701    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1702    fn test_try_pop_back_unchecked_panics_on_out_of_bounds() {
1703        let env = Env::default();
1704
1705        let mut v = Vec::<i64>::new(&env);
1706
1707        let _ = v.try_pop_back_unchecked();
1708    }
1709
1710    #[test]
1711    fn test_get() {
1712        let env = Env::default();
1713
1714        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1715
1716        // get each item
1717        assert_eq!(v.get(3), Some(5));
1718        assert_eq!(v.get(0), Some(0));
1719        assert_eq!(v.get(1), Some(3));
1720        assert_eq!(v.get(2), Some(5));
1721        assert_eq!(v.get(5), Some(9));
1722        assert_eq!(v.get(4), Some(7));
1723
1724        assert_eq!(v.get(v.len()), None);
1725        assert_eq!(v.get(v.len() + 1), None);
1726        assert_eq!(v.get(u32::MAX), None);
1727
1728        // tests on an empty vec
1729        let v = Vec::<i64>::new(&env);
1730        assert_eq!(v.get(0), None);
1731        assert_eq!(v.get(v.len()), None);
1732        assert_eq!(v.get(v.len() + 1), None);
1733        assert_eq!(v.get(u32::MAX), None);
1734    }
1735
1736    #[test]
1737    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1738    fn test_get_panics_on_conversion() {
1739        let env = Env::default();
1740
1741        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1742        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1743
1744        // panic because element one is not of the expected type
1745        assert_eq!(v.get(1), Some(5));
1746    }
1747
1748    #[test]
1749    fn test_try_get() {
1750        let env = Env::default();
1751
1752        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1753
1754        // get each item
1755        assert_eq!(v.try_get(3), Ok(Some(5)));
1756        assert_eq!(v.try_get(0), Ok(Some(0)));
1757        assert_eq!(v.try_get(1), Ok(Some(3)));
1758        assert_eq!(v.try_get(2), Ok(Some(5)));
1759        assert_eq!(v.try_get(5), Ok(Some(9)));
1760        assert_eq!(v.try_get(4), Ok(Some(7)));
1761
1762        assert_eq!(v.try_get(v.len()), Ok(None));
1763        assert_eq!(v.try_get(v.len() + 1), Ok(None));
1764        assert_eq!(v.try_get(u32::MAX), Ok(None));
1765
1766        // tests on an empty vec
1767        let v = Vec::<i64>::new(&env);
1768        assert_eq!(v.try_get(0), Ok(None));
1769        assert_eq!(v.try_get(v.len()), Ok(None));
1770        assert_eq!(v.try_get(v.len() + 1), Ok(None));
1771        assert_eq!(v.try_get(u32::MAX), Ok(None));
1772
1773        // errors
1774        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1775        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1776        assert_eq!(v.try_get(0), Ok(Some(1)));
1777        assert_eq!(v.try_get(1), Err(ConversionError.into()));
1778    }
1779
1780    #[test]
1781    fn test_get_unchecked() {
1782        let env = Env::default();
1783
1784        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1785
1786        // get each item
1787        assert_eq!(v.get_unchecked(3), 5);
1788        assert_eq!(v.get_unchecked(0), 0);
1789        assert_eq!(v.get_unchecked(1), 3);
1790        assert_eq!(v.get_unchecked(2), 5);
1791        assert_eq!(v.get_unchecked(5), 9);
1792        assert_eq!(v.get_unchecked(4), 7);
1793    }
1794
1795    #[test]
1796    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1797    fn test_get_unchecked_panics_on_conversion() {
1798        let env = Env::default();
1799
1800        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1801        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1802
1803        // panic because element one is not of the expected type
1804        v.get_unchecked(1);
1805    }
1806
1807    #[test]
1808    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1809    fn test_get_unchecked_panics_on_out_of_bounds() {
1810        let env = Env::default();
1811
1812        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1813        _ = v.get_unchecked(v.len()); // out of bound get
1814    }
1815
1816    #[test]
1817    fn test_try_get_unchecked() {
1818        let env = Env::default();
1819
1820        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1821
1822        // get each item
1823        assert_eq!(v.try_get_unchecked(3), Ok(5));
1824        assert_eq!(v.try_get_unchecked(0), Ok(0));
1825        assert_eq!(v.try_get_unchecked(1), Ok(3));
1826        assert_eq!(v.try_get_unchecked(2), Ok(5));
1827        assert_eq!(v.try_get_unchecked(5), Ok(9));
1828        assert_eq!(v.try_get_unchecked(4), Ok(7));
1829
1830        // errors
1831        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1832        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1833        assert_eq!(v.try_get_unchecked(0), Ok(1));
1834        assert_eq!(v.try_get_unchecked(1), Err(ConversionError.into()));
1835    }
1836
1837    #[test]
1838    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1839    fn test_try_get_unchecked_panics() {
1840        let env = Env::default();
1841
1842        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1843        _ = v.try_get_unchecked(v.len()); // out of bound get
1844    }
1845
1846    #[test]
1847    fn test_remove() {
1848        let env = Env::default();
1849        let mut v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1850
1851        assert_eq!(v.remove(0), Some(()));
1852        assert_eq!(v.remove(2), Some(()));
1853        assert_eq!(v.remove(3), Some(()));
1854
1855        assert_eq!(v, vec![&env, 3, 5, 7]);
1856        assert_eq!(v.len(), 3);
1857
1858        // out of bound removes
1859        assert_eq!(v.remove(v.len()), None);
1860        assert_eq!(v.remove(v.len() + 1), None);
1861        assert_eq!(v.remove(u32::MAX), None);
1862
1863        // remove rest of items
1864        assert_eq!(v.remove(0), Some(()));
1865        assert_eq!(v.remove(0), Some(()));
1866        assert_eq!(v.remove(0), Some(()));
1867        assert_eq!(v, vec![&env]);
1868        assert_eq!(v.len(), 0);
1869
1870        // try remove from empty vec
1871        assert_eq!(v.remove(0), None);
1872        assert_eq!(v.remove(v.len()), None);
1873        assert_eq!(v.remove(v.len() + 1), None);
1874        assert_eq!(v.remove(u32::MAX), None);
1875    }
1876
1877    #[test]
1878    fn test_remove_unchecked() {
1879        let env = Env::default();
1880        let mut v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1881
1882        assert_eq!(v.remove_unchecked(0), ());
1883        assert_eq!(v.remove_unchecked(2), ());
1884        assert_eq!(v.remove_unchecked(3), ());
1885
1886        assert_eq!(v, vec![&env, 3, 5, 7]);
1887        assert_eq!(v.len(), 3);
1888
1889        // remove rest of items
1890        assert_eq!(v.remove_unchecked(0), ());
1891        assert_eq!(v.remove_unchecked(0), ());
1892        assert_eq!(v.remove_unchecked(0), ());
1893        assert_eq!(v, vec![&env]);
1894        assert_eq!(v.len(), 0);
1895    }
1896
1897    #[test]
1898    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1899    fn test_remove_unchecked_panics() {
1900        let env = Env::default();
1901        let mut v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1902        v.remove_unchecked(v.len())
1903    }
1904
1905    #[test]
1906    fn test_extend() {
1907        let env = Env::default();
1908        let mut v: Vec<i64> = vec![&env, 1, 2, 3];
1909
1910        // Extend with a std vector
1911        let items = std::vec![4, 5, 6];
1912        v.extend(items);
1913        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5, 6]);
1914        assert_eq!(v.len(), 6);
1915
1916        // Extend with an array
1917        v.extend([7, 8, 9]);
1918        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
1919        assert_eq!(v.len(), 9);
1920
1921        // Extend with an empty iterator
1922        let empty: std::vec::Vec<i64> = std::vec::Vec::new();
1923        v.extend(empty);
1924        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
1925        assert_eq!(v.len(), 9);
1926    }
1927
1928    #[test]
1929    fn test_extend_empty_vec() {
1930        let env = Env::default();
1931        let mut v: Vec<i64> = vec![&env];
1932
1933        // Extend empty vec with items
1934        v.extend([1, 2, 3, 4, 5]);
1935        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5]);
1936        assert_eq!(v.len(), 5);
1937    }
1938
1939    #[test]
1940    fn test_from_iter() {
1941        let env = Env::default();
1942
1943        // Create from std vector iterator
1944        let items = std::vec![1, 2, 3, 4, 5];
1945        let v = Vec::from_iter(&env, items);
1946        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5]);
1947        assert_eq!(v.len(), 5);
1948
1949        // Create from array iterator
1950        let v2 = Vec::from_iter(&env, [10, 20, 30]);
1951        assert_eq!(v2, vec![&env, 10, 20, 30]);
1952        assert_eq!(v2.len(), 3);
1953
1954        // Create from range
1955        let v3 = Vec::from_iter(&env, 1..=4);
1956        assert_eq!(v3, vec![&env, 1, 2, 3, 4]);
1957        assert_eq!(v3.len(), 4);
1958    }
1959
1960    #[test]
1961    fn test_from_iter_empty() {
1962        let env = Env::default();
1963
1964        // Create from empty iterator
1965        let empty: std::vec::Vec<i64> = std::vec::Vec::new();
1966        let v = Vec::from_iter(&env, empty);
1967        assert_eq!(v, vec![&env]);
1968        assert_eq!(v.len(), 0);
1969
1970        // Create from empty range
1971        let v2 = Vec::from_iter(&env, 1..1);
1972        assert_eq!(v2, vec![&env]);
1973        assert_eq!(v2.len(), 0);
1974    }
1975
1976    #[test]
1977    fn test_from_iter_different_types() {
1978        let env = Env::default();
1979
1980        // Test with strings
1981        let strings = std::vec!["hello".to_string(), "world".to_string(), "test".to_string()];
1982        let v = Vec::from_iter(&env, strings);
1983        assert_eq!(
1984            v,
1985            vec![
1986                &env,
1987                "hello".to_string(),
1988                "world".to_string(),
1989                "test".to_string()
1990            ]
1991        );
1992        assert_eq!(v.len(), 3);
1993
1994        // Test with booleans
1995        let bools = [true, false, true, false];
1996        let v2 = Vec::from_iter(&env, bools.into_iter());
1997        assert_eq!(v2, vec![&env, true, false, true, false]);
1998        assert_eq!(v2.len(), 4);
1999    }
2000}
soroban_sdk/vec.rs

soroban_sdk/
vec.rs
