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 + 1,
787            Bound::Unbounded => 0,
788        };
789        let end_bound = match r.end_bound() {
790            Bound::Included(s) => *s + 1,
791            Bound::Excluded(s) => *s,
792            Bound::Unbounded => self.len(),
793        };
794        let env = self.env();
795        let obj = env
796            .vec_slice(self.obj, start_bound.into(), end_bound.into())
797            .unwrap_infallible();
798        unsafe { Self::unchecked_new(env.clone(), obj) }
799    }
800
801    /// Returns copy of the vec shuffled using the NOT-SECURE PRNG.
802    ///
803    /// In tests, must be called from within a running contract.
804    ///
805    /// # Warning
806    ///
807    /// **The pseudo-random generator used to perform the shuffle is not
808    /// suitable for security-sensitive work.**
809    pub fn shuffle(&mut self) {
810        let env = self.env();
811        env.prng().shuffle(self);
812    }
813
814    /// Returns copy of the vec shuffled using the NOT-SECURE PRNG.
815    ///
816    /// In tests, must be called from within a running contract.
817    ///
818    /// # Warning
819    ///
820    /// **The pseudo-random generator used to perform the shuffle is not
821    /// suitable for security-sensitive work.**
822    #[must_use]
823    pub fn to_shuffled(&self) -> Self {
824        let mut copy = self.clone();
825        copy.shuffle();
826        copy
827    }
828
829    /// Returns true if the vec is empty and contains no items.
830    #[inline(always)]
831    pub fn is_empty(&self) -> bool {
832        self.len() == 0
833    }
834
835    /// Returns the number of items in the vec.
836    #[inline(always)]
837    pub fn len(&self) -> u32 {
838        self.env.vec_len(self.obj).unwrap_infallible().into()
839    }
840}
841
842impl<T> Vec<T>
843where
844    T: IntoVal<Env, Val>,
845{
846    /// Returns true if the Vec contains the item.
847    #[inline(always)]
848    pub fn contains(&self, item: impl Borrow<T>) -> bool {
849        let env = self.env();
850        let val = item.borrow().into_val(env);
851        !env.vec_first_index_of(self.obj, val)
852            .unwrap_infallible()
853            .is_void()
854    }
855
856    /// Returns the index of the first occurrence of the item.
857    ///
858    /// If the item cannot be found [None] is returned.
859    #[inline(always)]
860    pub fn first_index_of(&self, item: impl Borrow<T>) -> Option<u32> {
861        let env = self.env();
862        let val = item.borrow().into_val(env);
863        env.vec_first_index_of(self.obj, val)
864            .unwrap_infallible()
865            .try_into_val(env)
866            .unwrap()
867    }
868
869    /// Returns the index of the last occurrence of the item.
870    ///
871    /// If the item cannot be found [None] is returned.
872    #[inline(always)]
873    pub fn last_index_of(&self, item: impl Borrow<T>) -> Option<u32> {
874        let env = self.env();
875        let val = item.borrow().into_val(env);
876        env.vec_last_index_of(self.obj, val)
877            .unwrap_infallible()
878            .try_into_val(env)
879            .unwrap()
880    }
881
882    /// Returns the index of an occurrence of the item in an already sorted
883    /// [Vec], or the index of where the item can be inserted to keep the [Vec]
884    /// sorted.
885    ///
886    /// If the item is found, [Result::Ok] is returned containing the index of
887    /// the item.
888    ///
889    /// If the item is not found, [Result::Err] is returned containing the index
890    /// of where the item could be inserted to retain the sorted ordering.
891    #[inline(always)]
892    pub fn binary_search(&self, item: impl Borrow<T>) -> Result<u32, u32> {
893        let env = self.env();
894        let val = item.borrow().into_val(env);
895        let high_low = env.vec_binary_search(self.obj, val).unwrap_infallible();
896        let high: u32 = (high_low >> u32::BITS) as u32;
897        let low: u32 = high_low as u32;
898        if high == 1 {
899            Ok(low)
900        } else {
901            Err(low)
902        }
903    }
904}
905
906impl<T> Vec<Vec<T>>
907where
908    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
909    T: Clone,
910{
911    #[inline(always)]
912    pub fn concat(&self) -> Vec<T> {
913        let mut concatenated = vec![self.env()];
914        for vec in self.iter() {
915            concatenated.append(&vec);
916        }
917        concatenated
918    }
919}
920
921impl<T> IntoIterator for Vec<T>
922where
923    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
924{
925    type Item = T;
926    type IntoIter = UnwrappedIter<VecTryIter<T>, T, T::Error>;
927
928    fn into_iter(self) -> Self::IntoIter {
929        VecTryIter::new(self).unwrapped()
930    }
931}
932
933impl<T> IntoIterator for &Vec<T>
934where
935    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
936{
937    type Item = T;
938    type IntoIter = UnwrappedIter<VecTryIter<T>, T, T::Error>;
939
940    fn into_iter(self) -> Self::IntoIter {
941        self.clone().into_iter()
942    }
943}
944
945impl<T> Extend<T> for Vec<T>
946where
947    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
948{
949    fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
950        for item in iter {
951            self.push_back(item);
952        }
953    }
954}
955
956impl<T> Vec<T>
957where
958    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
959{
960    #[inline(always)]
961    pub fn iter(&self) -> UnwrappedIter<VecTryIter<T>, T, T::Error>
962    where
963        T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
964        T::Error: Debug,
965    {
966        self.try_iter().unwrapped()
967    }
968
969    #[inline(always)]
970    pub fn try_iter(&self) -> VecTryIter<T>
971    where
972        T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
973    {
974        VecTryIter::new(self.clone())
975    }
976
977    #[inline(always)]
978    pub fn into_try_iter(self) -> VecTryIter<T>
979    where
980        T: IntoVal<Env, Val> + TryFromVal<Env, Val> + Clone,
981        T::Error: Debug,
982    {
983        VecTryIter::new(self.clone())
984    }
985}
986
987#[derive(Clone)]
988pub struct VecTryIter<T> {
989    vec: Vec<T>,
990    start: u32, // inclusive
991    end: u32,   // exclusive
992}
993
994impl<T> VecTryIter<T> {
995    fn new(vec: Vec<T>) -> Self {
996        Self {
997            start: 0,
998            end: vec.len(),
999            vec,
1000        }
1001    }
1002
1003    fn into_vec(self) -> Vec<T> {
1004        self.vec.slice(self.start..self.end)
1005    }
1006}
1007
1008impl<T> Iterator for VecTryIter<T>
1009where
1010    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
1011{
1012    type Item = Result<T, T::Error>;
1013
1014    fn next(&mut self) -> Option<Self::Item> {
1015        if self.start < self.end {
1016            let val = self.vec.try_get_unchecked(self.start);
1017            self.start += 1;
1018            Some(val)
1019        } else {
1020            None
1021        }
1022    }
1023
1024    fn size_hint(&self) -> (usize, Option<usize>) {
1025        let len = (self.end - self.start) as usize;
1026        (len, Some(len))
1027    }
1028
1029    // TODO: Implement other functions as optimizations since the iterator is
1030    // backed by an indexable collection.
1031}
1032
1033impl<T> DoubleEndedIterator for VecTryIter<T>
1034where
1035    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
1036{
1037    fn next_back(&mut self) -> Option<Self::Item> {
1038        if self.start < self.end {
1039            let val = self.vec.try_get_unchecked(self.end - 1);
1040            self.end -= 1;
1041            Some(val)
1042        } else {
1043            None
1044        }
1045    }
1046
1047    // TODO: Implement other functions as optimizations since the iterator is
1048    // backed by an indexable collection.
1049}
1050
1051impl<T> FusedIterator for VecTryIter<T> where T: IntoVal<Env, Val> + TryFromVal<Env, Val> {}
1052
1053impl<T> ExactSizeIterator for VecTryIter<T>
1054where
1055    T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
1056{
1057    fn len(&self) -> usize {
1058        (self.end - self.start) as usize
1059    }
1060}
1061
1062#[cfg(test)]
1063mod test {
1064    use super::*;
1065
1066    #[test]
1067    fn test_vec_macro() {
1068        let env = Env::default();
1069        assert_eq!(vec![&env], Vec::<i32>::new(&env));
1070        assert_eq!(vec![&env,], Vec::<i32>::new(&env));
1071        assert_eq!(vec![&env, 1], {
1072            let mut v = Vec::new(&env);
1073            v.push_back(1);
1074            v
1075        });
1076        assert_eq!(vec![&env, 1,], {
1077            let mut v = Vec::new(&env);
1078            v.push_back(1);
1079            v
1080        });
1081        assert_eq!(vec![&env, 3, 2, 1,], {
1082            let mut v = Vec::new(&env);
1083            v.push_back(3);
1084            v.push_back(2);
1085            v.push_back(1);
1086            v
1087        });
1088    }
1089
1090    #[test]
1091    fn test_vec_to_val() {
1092        let env = Env::default();
1093
1094        let vec = Vec::<u32>::from_slice(&env, &[0, 1, 2, 3]);
1095        let val: Val = vec.clone().into_val(&env);
1096        let rt: Vec<u32> = val.into_val(&env);
1097
1098        assert_eq!(vec, rt);
1099    }
1100
1101    #[test]
1102    fn test_ref_vec_to_val() {
1103        let env = Env::default();
1104
1105        let vec = Vec::<u32>::from_slice(&env, &[0, 1, 2, 3]);
1106        let val: Val = (&vec).into_val(&env);
1107        let rt: Vec<u32> = val.into_val(&env);
1108
1109        assert_eq!(vec, rt);
1110    }
1111
1112    #[test]
1113    fn test_double_ref_vec_to_val() {
1114        let env = Env::default();
1115
1116        let vec = Vec::<u32>::from_slice(&env, &[0, 1, 2, 3]);
1117        let val: Val = (&&vec).into_val(&env);
1118        let rt: Vec<u32> = val.into_val(&env);
1119
1120        assert_eq!(vec, rt);
1121    }
1122
1123    #[test]
1124    fn test_vec_raw_val_type() {
1125        let env = Env::default();
1126
1127        let mut vec = Vec::<u32>::new(&env);
1128        assert_eq!(vec.len(), 0);
1129        vec.push_back(10);
1130        assert_eq!(vec.len(), 1);
1131        vec.push_back(20);
1132        assert_eq!(vec.len(), 2);
1133        vec.push_back(30);
1134        assert_eq!(vec.len(), 3);
1135
1136        let vec_ref = &vec;
1137        assert_eq!(vec_ref.len(), 3);
1138
1139        let mut vec_copy = vec.clone();
1140        assert!(vec == vec_copy);
1141        assert_eq!(vec_copy.len(), 3);
1142        vec_copy.push_back(40);
1143        assert_eq!(vec_copy.len(), 4);
1144        assert!(vec != vec_copy);
1145
1146        assert_eq!(vec.len(), 3);
1147        assert_eq!(vec_ref.len(), 3);
1148
1149        _ = vec_copy.pop_back_unchecked();
1150        assert!(vec == vec_copy);
1151    }
1152
1153    #[test]
1154    fn test_vec_env_val_type() {
1155        let env = Env::default();
1156
1157        let mut vec = Vec::<i64>::new(&env);
1158        assert_eq!(vec.len(), 0);
1159        vec.push_back(-10);
1160        assert_eq!(vec.len(), 1);
1161        vec.push_back(20);
1162        assert_eq!(vec.len(), 2);
1163        vec.push_back(-30);
1164        assert_eq!(vec.len(), 3);
1165
1166        let vec_ref = &vec;
1167        assert_eq!(vec_ref.len(), 3);
1168
1169        let mut vec_copy = vec.clone();
1170        assert!(vec == vec_copy);
1171        assert_eq!(vec_copy.len(), 3);
1172        vec_copy.push_back(40);
1173        assert_eq!(vec_copy.len(), 4);
1174        assert!(vec != vec_copy);
1175
1176        assert_eq!(vec.len(), 3);
1177        assert_eq!(vec_ref.len(), 3);
1178
1179        _ = vec_copy.pop_back_unchecked();
1180        assert!(vec == vec_copy);
1181    }
1182
1183    #[test]
1184    fn test_vec_to_vals() {
1185        let env = Env::default();
1186        let vec = vec![&env, 0, 1, 2, 3, 4];
1187        let vals = vec.to_vals();
1188        assert_eq!(
1189            vals,
1190            vec![
1191                &env,
1192                Val::from_i32(0).to_val(),
1193                Val::from_i32(1).to_val(),
1194                Val::from_i32(2).to_val(),
1195                Val::from_i32(3).to_val(),
1196                Val::from_i32(4).to_val(),
1197            ]
1198        );
1199    }
1200
1201    #[test]
1202    fn test_vec_recursive() {
1203        let env = Env::default();
1204
1205        let mut vec_inner = Vec::<i64>::new(&env);
1206        vec_inner.push_back(-10);
1207        assert_eq!(vec_inner.len(), 1);
1208
1209        let mut vec_outer = Vec::<Vec<i64>>::new(&env);
1210        vec_outer.push_back(vec_inner);
1211        assert_eq!(vec_outer.len(), 1);
1212    }
1213
1214    #[test]
1215    fn test_vec_concat() {
1216        let env = Env::default();
1217        let vec_1: Vec<i64> = vec![&env, 1, 2, 3];
1218        let vec_2: Vec<i64> = vec![&env, 4, 5, 6];
1219        let vec = vec![&env, vec_1, vec_2].concat();
1220        assert_eq!(vec, vec![&env, 1, 2, 3, 4, 5, 6]);
1221    }
1222
1223    #[test]
1224    fn test_vec_slice() {
1225        let env = Env::default();
1226
1227        let vec = vec![&env, 0, 1, 2, 3, 4];
1228        assert_eq!(vec.len(), 5);
1229
1230        let slice = vec.slice(..);
1231        assert_eq!(slice, vec![&env, 0, 1, 2, 3, 4]);
1232
1233        let slice = vec.slice(0..5);
1234        assert_eq!(slice, vec![&env, 0, 1, 2, 3, 4]);
1235
1236        let slice = vec.slice(0..=4);
1237        assert_eq!(slice, vec![&env, 0, 1, 2, 3, 4]);
1238
1239        let slice = vec.slice(1..);
1240        assert_eq!(slice, vec![&env, 1, 2, 3, 4]);
1241
1242        let slice = vec.slice(..4);
1243        assert_eq!(slice, vec![&env, 0, 1, 2, 3]);
1244
1245        let slice = vec.slice(..=3);
1246        assert_eq!(slice, vec![&env, 0, 1, 2, 3]);
1247
1248        let slice = vec.slice(1..4);
1249        assert_eq!(slice, vec![&env, 1, 2, 3]);
1250
1251        let slice = vec.slice(1..=3);
1252        assert_eq!(slice, vec![&env, 1, 2, 3]);
1253
1254        // An exclusive start is technically possible due to the lack of
1255        // constraints in the RangeBounds trait, however this is unlikely to
1256        // happen since no syntax shorthand exists for it.
1257        let slice = vec.slice((Bound::Excluded(0), Bound::Included(3)));
1258        assert_eq!(slice, vec![&env, 1, 2, 3]);
1259        let slice = vec.slice((Bound::Excluded(0), Bound::Excluded(3)));
1260        assert_eq!(slice, vec![&env, 1, 2]);
1261    }
1262
1263    #[test]
1264    fn test_vec_iter() {
1265        let env = Env::default();
1266
1267        let vec: Vec<()> = vec![&env];
1268        let mut iter = vec.iter();
1269        assert_eq!(iter.len(), 0);
1270        assert_eq!(iter.next(), None);
1271        assert_eq!(iter.next(), None);
1272
1273        let vec = vec![&env, 0, 1, 2, 3, 4];
1274
1275        let mut iter = vec.iter();
1276        assert_eq!(iter.len(), 5);
1277        assert_eq!(iter.next(), Some(0));
1278        assert_eq!(iter.len(), 4);
1279        assert_eq!(iter.next(), Some(1));
1280        assert_eq!(iter.len(), 3);
1281        assert_eq!(iter.next(), Some(2));
1282        assert_eq!(iter.len(), 2);
1283        assert_eq!(iter.next(), Some(3));
1284        assert_eq!(iter.len(), 1);
1285        assert_eq!(iter.next(), Some(4));
1286        assert_eq!(iter.len(), 0);
1287        assert_eq!(iter.next(), None);
1288        assert_eq!(iter.next(), None);
1289
1290        let mut iter = vec.iter();
1291        assert_eq!(iter.len(), 5);
1292        assert_eq!(iter.next(), Some(0));
1293        assert_eq!(iter.len(), 4);
1294        assert_eq!(iter.next_back(), Some(4));
1295        assert_eq!(iter.len(), 3);
1296        assert_eq!(iter.next_back(), Some(3));
1297        assert_eq!(iter.len(), 2);
1298        assert_eq!(iter.next(), Some(1));
1299        assert_eq!(iter.len(), 1);
1300        assert_eq!(iter.next(), Some(2));
1301        assert_eq!(iter.len(), 0);
1302        assert_eq!(iter.next(), None);
1303        assert_eq!(iter.next(), None);
1304        assert_eq!(iter.next_back(), None);
1305        assert_eq!(iter.next_back(), None);
1306
1307        let mut iter = vec.iter().rev();
1308        assert_eq!(iter.next(), Some(4));
1309        assert_eq!(iter.next_back(), Some(0));
1310        assert_eq!(iter.next_back(), Some(1));
1311        assert_eq!(iter.next(), Some(3));
1312        assert_eq!(iter.next(), Some(2));
1313        assert_eq!(iter.next(), None);
1314        assert_eq!(iter.next(), None);
1315        assert_eq!(iter.next_back(), None);
1316        assert_eq!(iter.next_back(), None);
1317    }
1318
1319    #[test]
1320    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1321    fn test_vec_iter_panic_on_conversion() {
1322        let env = Env::default();
1323
1324        let vec: Val = (1i32,).try_into_val(&env).unwrap();
1325        let vec: Vec<i64> = vec.try_into_val(&env).unwrap();
1326
1327        let mut iter = vec.iter();
1328        iter.next();
1329    }
1330
1331    #[test]
1332    fn test_vec_try_iter() {
1333        let env = Env::default();
1334
1335        let vec: Vec<()> = vec![&env];
1336        let mut iter = vec.try_iter();
1337        assert_eq!(iter.len(), 0);
1338        assert_eq!(iter.next(), None);
1339        assert_eq!(iter.next(), None);
1340
1341        let vec = vec![&env, 0, 1, 2, 3, 4];
1342
1343        let mut iter = vec.try_iter();
1344        assert_eq!(iter.len(), 5);
1345        assert_eq!(iter.next(), Some(Ok(0)));
1346        assert_eq!(iter.len(), 4);
1347        assert_eq!(iter.next(), Some(Ok(1)));
1348        assert_eq!(iter.len(), 3);
1349        assert_eq!(iter.next(), Some(Ok(2)));
1350        assert_eq!(iter.len(), 2);
1351        assert_eq!(iter.next(), Some(Ok(3)));
1352        assert_eq!(iter.len(), 1);
1353        assert_eq!(iter.next(), Some(Ok(4)));
1354        assert_eq!(iter.len(), 0);
1355        assert_eq!(iter.next(), None);
1356        assert_eq!(iter.next(), None);
1357
1358        let mut iter = vec.try_iter();
1359        assert_eq!(iter.len(), 5);
1360        assert_eq!(iter.next(), Some(Ok(0)));
1361        assert_eq!(iter.len(), 4);
1362        assert_eq!(iter.next_back(), Some(Ok(4)));
1363        assert_eq!(iter.len(), 3);
1364        assert_eq!(iter.next_back(), Some(Ok(3)));
1365        assert_eq!(iter.len(), 2);
1366        assert_eq!(iter.next(), Some(Ok(1)));
1367        assert_eq!(iter.len(), 1);
1368        assert_eq!(iter.next(), Some(Ok(2)));
1369        assert_eq!(iter.len(), 0);
1370        assert_eq!(iter.next(), None);
1371        assert_eq!(iter.next(), None);
1372        assert_eq!(iter.next_back(), None);
1373        assert_eq!(iter.next_back(), None);
1374
1375        let mut iter = vec.try_iter().rev();
1376        assert_eq!(iter.next(), Some(Ok(4)));
1377        assert_eq!(iter.next_back(), Some(Ok(0)));
1378        assert_eq!(iter.next_back(), Some(Ok(1)));
1379        assert_eq!(iter.next(), Some(Ok(3)));
1380        assert_eq!(iter.next(), Some(Ok(2)));
1381        assert_eq!(iter.next(), None);
1382        assert_eq!(iter.next(), None);
1383        assert_eq!(iter.next_back(), None);
1384        assert_eq!(iter.next_back(), None);
1385    }
1386
1387    #[test]
1388    fn test_vec_try_iter_error_on_conversion() {
1389        let env = Env::default();
1390
1391        let vec: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1392        let vec: Vec<i64> = vec.try_into_val(&env).unwrap();
1393
1394        let mut iter = vec.try_iter();
1395        assert_eq!(iter.next(), Some(Ok(1)));
1396        assert_eq!(iter.next(), Some(Err(ConversionError.into())));
1397    }
1398
1399    #[test]
1400    fn test_vec_iter_into_vec() {
1401        let env = Env::default();
1402
1403        let vec = vec![&env, 0, 1, 2, 3, 4];
1404
1405        let mut iter = vec.try_iter();
1406        assert_eq!(iter.next(), Some(Ok(0)));
1407        assert_eq!(iter.next(), Some(Ok(1)));
1408        assert_eq!(iter.into_vec(), vec![&env, 2, 3, 4]);
1409    }
1410
1411    #[test]
1412    fn test_contains() {
1413        let env = Env::default();
1414        let vec = vec![&env, 0, 3, 5, 7, 9, 5];
1415        assert_eq!(vec.contains(&2), false);
1416        assert_eq!(vec.contains(2), false);
1417        assert_eq!(vec.contains(&3), true);
1418        assert_eq!(vec.contains(3), true);
1419        assert_eq!(vec.contains(&5), true);
1420        assert_eq!(vec.contains(5), true);
1421    }
1422
1423    #[test]
1424    fn test_first_index_of() {
1425        let env = Env::default();
1426
1427        let vec = vec![&env, 0, 3, 5, 7, 9, 5];
1428        assert_eq!(vec.first_index_of(&2), None);
1429        assert_eq!(vec.first_index_of(2), None);
1430        assert_eq!(vec.first_index_of(&3), Some(1));
1431        assert_eq!(vec.first_index_of(3), Some(1));
1432        assert_eq!(vec.first_index_of(&5), Some(2));
1433        assert_eq!(vec.first_index_of(5), Some(2));
1434    }
1435
1436    #[test]
1437    fn test_last_index_of() {
1438        let env = Env::default();
1439
1440        let vec = vec![&env, 0, 3, 5, 7, 9, 5];
1441        assert_eq!(vec.last_index_of(&2), None);
1442        assert_eq!(vec.last_index_of(2), None);
1443        assert_eq!(vec.last_index_of(&3), Some(1));
1444        assert_eq!(vec.last_index_of(3), Some(1));
1445        assert_eq!(vec.last_index_of(&5), Some(5));
1446        assert_eq!(vec.last_index_of(5), Some(5));
1447    }
1448
1449    #[test]
1450    fn test_binary_search() {
1451        let env = Env::default();
1452
1453        let vec = vec![&env, 0, 3, 5, 5, 7, 9];
1454        assert_eq!(vec.binary_search(&2), Err(1));
1455        assert_eq!(vec.binary_search(2), Err(1));
1456        assert_eq!(vec.binary_search(&3), Ok(1));
1457        assert_eq!(vec.binary_search(3), Ok(1));
1458        assert_eq!(vec.binary_search(&5), Ok(3));
1459        assert_eq!(vec.binary_search(5), Ok(3));
1460    }
1461
1462    #[cfg(not(target_family = "wasm"))]
1463    #[test]
1464    fn test_scval_accessibility_from_udt_types() {
1465        use crate::TryFromVal;
1466        let env = Env::default();
1467        let v = vec![&env, 1];
1468        let val: ScVal = v.clone().try_into().unwrap();
1469        let roundtrip = Vec::<i64>::try_from_val(&env, &val).unwrap();
1470        assert_eq!(v, roundtrip);
1471    }
1472
1473    #[test]
1474    fn test_insert_and_set() {
1475        let env = Env::default();
1476        let mut v = Vec::<i64>::new(&env);
1477        v.insert(0, 3);
1478        v.insert(0, 1);
1479        v.insert(1, 4);
1480        v.insert(3, 6);
1481        assert_eq!(v, vec![&env, 1, 4, 3, 6]);
1482        v.set(0, 7);
1483        v.set(1, 6);
1484        v.set(2, 2);
1485        v.set(3, 5);
1486        assert_eq!(v, vec![&env, 7, 6, 2, 5]);
1487    }
1488
1489    #[test]
1490    fn test_is_empty_and_len() {
1491        let env = Env::default();
1492
1493        let mut v: Vec<i32> = vec![&env, 1, 4, 3];
1494        assert_eq!(v.is_empty(), false);
1495        assert_eq!(v.len(), 3);
1496
1497        v = vec![&env];
1498        assert_eq!(v.is_empty(), true);
1499        assert_eq!(v.len(), 0);
1500    }
1501
1502    #[test]
1503    fn test_push_pop_front() {
1504        let env = Env::default();
1505
1506        let mut v = Vec::<i64>::new(&env);
1507        v.push_front(42);
1508        assert_eq!(v, vec![&env, 42]);
1509        v.push_front(1);
1510        assert_eq!(v, vec![&env, 1, 42]);
1511        v.push_front(5);
1512        assert_eq!(v, vec![&env, 5, 1, 42]);
1513        v.push_front(7);
1514        assert_eq!(v, vec![&env, 7, 5, 1, 42]);
1515
1516        let popped = v.pop_front();
1517        assert_eq!(popped, Some(7));
1518        assert_eq!(v, vec![&env, 5, 1, 42]);
1519
1520        let popped = v.try_pop_front();
1521        assert_eq!(popped, Ok(Some(5)));
1522        assert_eq!(v, vec![&env, 1, 42]);
1523
1524        let popped = v.pop_front_unchecked();
1525        assert_eq!(popped, 1);
1526        assert_eq!(v, vec![&env, 42]);
1527
1528        let popped = v.try_pop_front_unchecked();
1529        assert_eq!(popped, Ok(42));
1530        assert_eq!(v, vec![&env]);
1531
1532        assert_eq!(v.pop_front(), None);
1533    }
1534
1535    #[test]
1536    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1537    fn test_pop_front_panics_on_conversion() {
1538        let env = Env::default();
1539
1540        let v: Val = (1i32,).try_into_val(&env).unwrap();
1541        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1542
1543        v.pop_front();
1544    }
1545
1546    #[test]
1547    fn test_try_pop_front_errors_on_conversion() {
1548        let env = Env::default();
1549
1550        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1551        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1552
1553        assert_eq!(v.try_pop_front(), Ok(Some(1)));
1554        assert_eq!(v.try_pop_front(), Err(ConversionError.into()));
1555    }
1556
1557    #[test]
1558    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1559    fn test_pop_front_unchecked_panics_on_conversion() {
1560        let env = Env::default();
1561
1562        let v: Val = (1i32,).try_into_val(&env).unwrap();
1563        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1564
1565        v.pop_front_unchecked();
1566    }
1567
1568    #[test]
1569    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1570    fn test_pop_front_unchecked_panics_on_out_of_bounds() {
1571        let env = Env::default();
1572
1573        let mut v = Vec::<i64>::new(&env);
1574
1575        v.pop_front_unchecked();
1576    }
1577
1578    #[test]
1579    fn test_try_pop_front_unchecked_errors_on_conversion() {
1580        let env = Env::default();
1581
1582        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1583        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1584
1585        assert_eq!(v.try_pop_front_unchecked(), Ok(1));
1586        assert_eq!(v.try_pop_front_unchecked(), Err(ConversionError.into()));
1587    }
1588
1589    #[test]
1590    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1591    fn test_try_pop_front_unchecked_panics_on_out_of_bounds() {
1592        let env = Env::default();
1593
1594        let mut v = Vec::<i64>::new(&env);
1595
1596        let _ = v.try_pop_front_unchecked();
1597    }
1598
1599    #[test]
1600    fn test_push_pop_back() {
1601        let env = Env::default();
1602
1603        let mut v = Vec::<i64>::new(&env);
1604        v.push_back(42);
1605        assert_eq!(v, vec![&env, 42]);
1606        v.push_back(1);
1607        assert_eq!(v, vec![&env, 42, 1]);
1608        v.push_back(5);
1609        assert_eq!(v, vec![&env, 42, 1, 5]);
1610        v.push_back(7);
1611        assert_eq!(v, vec![&env, 42, 1, 5, 7]);
1612
1613        let popped = v.pop_back();
1614        assert_eq!(popped, Some(7));
1615        assert_eq!(v, vec![&env, 42, 1, 5]);
1616
1617        let popped = v.try_pop_back();
1618        assert_eq!(popped, Ok(Some(5)));
1619        assert_eq!(v, vec![&env, 42, 1]);
1620
1621        let popped = v.pop_back_unchecked();
1622        assert_eq!(popped, 1);
1623        assert_eq!(v, vec![&env, 42]);
1624
1625        let popped = v.try_pop_back_unchecked();
1626        assert_eq!(popped, Ok(42));
1627        assert_eq!(v, vec![&env]);
1628
1629        assert_eq!(v.pop_back(), None);
1630    }
1631
1632    #[test]
1633    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1634    fn test_pop_back_panics_on_conversion() {
1635        let env = Env::default();
1636
1637        let v: Val = (1i32,).try_into_val(&env).unwrap();
1638        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1639
1640        v.pop_back();
1641    }
1642
1643    #[test]
1644    fn test_try_pop_back_errors_on_conversion() {
1645        let env = Env::default();
1646
1647        let v: Val = (1i32, 2i64).try_into_val(&env).unwrap();
1648        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1649
1650        assert_eq!(v.try_pop_back(), Ok(Some(2)));
1651        assert_eq!(v.try_pop_back(), Err(ConversionError.into()));
1652    }
1653
1654    #[test]
1655    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1656    fn test_pop_back_unchecked_panics_on_conversion() {
1657        let env = Env::default();
1658
1659        let v: Val = (1i32,).try_into_val(&env).unwrap();
1660        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1661
1662        v.pop_back_unchecked();
1663    }
1664
1665    #[test]
1666    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1667    fn test_pop_back_unchecked_panics_on_out_of_bounds() {
1668        let env = Env::default();
1669
1670        let mut v = Vec::<i64>::new(&env);
1671
1672        v.pop_back_unchecked();
1673    }
1674
1675    #[test]
1676    fn test_try_pop_back_unchecked_errors_on_conversion() {
1677        let env = Env::default();
1678
1679        let v: Val = (1i32, 2i64).try_into_val(&env).unwrap();
1680        let mut v: Vec<i64> = v.try_into_val(&env).unwrap();
1681
1682        assert_eq!(v.try_pop_back_unchecked(), Ok(2));
1683        assert_eq!(v.try_pop_back_unchecked(), Err(ConversionError.into()));
1684    }
1685
1686    #[test]
1687    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1688    fn test_try_pop_back_unchecked_panics_on_out_of_bounds() {
1689        let env = Env::default();
1690
1691        let mut v = Vec::<i64>::new(&env);
1692
1693        let _ = v.try_pop_back_unchecked();
1694    }
1695
1696    #[test]
1697    fn test_get() {
1698        let env = Env::default();
1699
1700        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1701
1702        // get each item
1703        assert_eq!(v.get(3), Some(5));
1704        assert_eq!(v.get(0), Some(0));
1705        assert_eq!(v.get(1), Some(3));
1706        assert_eq!(v.get(2), Some(5));
1707        assert_eq!(v.get(5), Some(9));
1708        assert_eq!(v.get(4), Some(7));
1709
1710        assert_eq!(v.get(v.len()), None);
1711        assert_eq!(v.get(v.len() + 1), None);
1712        assert_eq!(v.get(u32::MAX), None);
1713
1714        // tests on an empty vec
1715        let v = Vec::<i64>::new(&env);
1716        assert_eq!(v.get(0), None);
1717        assert_eq!(v.get(v.len()), None);
1718        assert_eq!(v.get(v.len() + 1), None);
1719        assert_eq!(v.get(u32::MAX), None);
1720    }
1721
1722    #[test]
1723    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1724    fn test_get_panics_on_conversion() {
1725        let env = Env::default();
1726
1727        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1728        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1729
1730        // panic because element one is not of the expected type
1731        assert_eq!(v.get(1), Some(5));
1732    }
1733
1734    #[test]
1735    fn test_try_get() {
1736        let env = Env::default();
1737
1738        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1739
1740        // get each item
1741        assert_eq!(v.try_get(3), Ok(Some(5)));
1742        assert_eq!(v.try_get(0), Ok(Some(0)));
1743        assert_eq!(v.try_get(1), Ok(Some(3)));
1744        assert_eq!(v.try_get(2), Ok(Some(5)));
1745        assert_eq!(v.try_get(5), Ok(Some(9)));
1746        assert_eq!(v.try_get(4), Ok(Some(7)));
1747
1748        assert_eq!(v.try_get(v.len()), Ok(None));
1749        assert_eq!(v.try_get(v.len() + 1), Ok(None));
1750        assert_eq!(v.try_get(u32::MAX), Ok(None));
1751
1752        // tests on an empty vec
1753        let v = Vec::<i64>::new(&env);
1754        assert_eq!(v.try_get(0), Ok(None));
1755        assert_eq!(v.try_get(v.len()), Ok(None));
1756        assert_eq!(v.try_get(v.len() + 1), Ok(None));
1757        assert_eq!(v.try_get(u32::MAX), Ok(None));
1758
1759        // errors
1760        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1761        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1762        assert_eq!(v.try_get(0), Ok(Some(1)));
1763        assert_eq!(v.try_get(1), Err(ConversionError.into()));
1764    }
1765
1766    #[test]
1767    fn test_get_unchecked() {
1768        let env = Env::default();
1769
1770        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1771
1772        // get each item
1773        assert_eq!(v.get_unchecked(3), 5);
1774        assert_eq!(v.get_unchecked(0), 0);
1775        assert_eq!(v.get_unchecked(1), 3);
1776        assert_eq!(v.get_unchecked(2), 5);
1777        assert_eq!(v.get_unchecked(5), 9);
1778        assert_eq!(v.get_unchecked(4), 7);
1779    }
1780
1781    #[test]
1782    #[should_panic(expected = "Error(Value, UnexpectedType)")]
1783    fn test_get_unchecked_panics_on_conversion() {
1784        let env = Env::default();
1785
1786        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1787        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1788
1789        // panic because element one is not of the expected type
1790        v.get_unchecked(1);
1791    }
1792
1793    #[test]
1794    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1795    fn test_get_unchecked_panics_on_out_of_bounds() {
1796        let env = Env::default();
1797
1798        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1799        _ = v.get_unchecked(v.len()); // out of bound get
1800    }
1801
1802    #[test]
1803    fn test_try_get_unchecked() {
1804        let env = Env::default();
1805
1806        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1807
1808        // get each item
1809        assert_eq!(v.try_get_unchecked(3), Ok(5));
1810        assert_eq!(v.try_get_unchecked(0), Ok(0));
1811        assert_eq!(v.try_get_unchecked(1), Ok(3));
1812        assert_eq!(v.try_get_unchecked(2), Ok(5));
1813        assert_eq!(v.try_get_unchecked(5), Ok(9));
1814        assert_eq!(v.try_get_unchecked(4), Ok(7));
1815
1816        // errors
1817        let v: Val = (1i64, 2i32).try_into_val(&env).unwrap();
1818        let v: Vec<i64> = v.try_into_val(&env).unwrap();
1819        assert_eq!(v.try_get_unchecked(0), Ok(1));
1820        assert_eq!(v.try_get_unchecked(1), Err(ConversionError.into()));
1821    }
1822
1823    #[test]
1824    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1825    fn test_try_get_unchecked_panics() {
1826        let env = Env::default();
1827
1828        let v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1829        _ = v.try_get_unchecked(v.len()); // out of bound get
1830    }
1831
1832    #[test]
1833    fn test_remove() {
1834        let env = Env::default();
1835        let mut v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1836
1837        assert_eq!(v.remove(0), Some(()));
1838        assert_eq!(v.remove(2), Some(()));
1839        assert_eq!(v.remove(3), Some(()));
1840
1841        assert_eq!(v, vec![&env, 3, 5, 7]);
1842        assert_eq!(v.len(), 3);
1843
1844        // out of bound removes
1845        assert_eq!(v.remove(v.len()), None);
1846        assert_eq!(v.remove(v.len() + 1), None);
1847        assert_eq!(v.remove(u32::MAX), None);
1848
1849        // remove rest of items
1850        assert_eq!(v.remove(0), Some(()));
1851        assert_eq!(v.remove(0), Some(()));
1852        assert_eq!(v.remove(0), Some(()));
1853        assert_eq!(v, vec![&env]);
1854        assert_eq!(v.len(), 0);
1855
1856        // try remove from empty vec
1857        assert_eq!(v.remove(0), None);
1858        assert_eq!(v.remove(v.len()), None);
1859        assert_eq!(v.remove(v.len() + 1), None);
1860        assert_eq!(v.remove(u32::MAX), None);
1861    }
1862
1863    #[test]
1864    fn test_remove_unchecked() {
1865        let env = Env::default();
1866        let mut v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1867
1868        assert_eq!(v.remove_unchecked(0), ());
1869        assert_eq!(v.remove_unchecked(2), ());
1870        assert_eq!(v.remove_unchecked(3), ());
1871
1872        assert_eq!(v, vec![&env, 3, 5, 7]);
1873        assert_eq!(v.len(), 3);
1874
1875        // remove rest of items
1876        assert_eq!(v.remove_unchecked(0), ());
1877        assert_eq!(v.remove_unchecked(0), ());
1878        assert_eq!(v.remove_unchecked(0), ());
1879        assert_eq!(v, vec![&env]);
1880        assert_eq!(v.len(), 0);
1881    }
1882
1883    #[test]
1884    #[should_panic(expected = "HostError: Error(Object, IndexBounds)")]
1885    fn test_remove_unchecked_panics() {
1886        let env = Env::default();
1887        let mut v: Vec<i64> = vec![&env, 0, 3, 5, 5, 7, 9];
1888        v.remove_unchecked(v.len())
1889    }
1890
1891    #[test]
1892    fn test_extend() {
1893        let env = Env::default();
1894        let mut v: Vec<i64> = vec![&env, 1, 2, 3];
1895
1896        // Extend with a std vector
1897        let items = std::vec![4, 5, 6];
1898        v.extend(items);
1899        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5, 6]);
1900        assert_eq!(v.len(), 6);
1901
1902        // Extend with an array
1903        v.extend([7, 8, 9]);
1904        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
1905        assert_eq!(v.len(), 9);
1906
1907        // Extend with an empty iterator
1908        let empty: std::vec::Vec<i64> = std::vec::Vec::new();
1909        v.extend(empty);
1910        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
1911        assert_eq!(v.len(), 9);
1912    }
1913
1914    #[test]
1915    fn test_extend_empty_vec() {
1916        let env = Env::default();
1917        let mut v: Vec<i64> = vec![&env];
1918
1919        // Extend empty vec with items
1920        v.extend([1, 2, 3, 4, 5]);
1921        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5]);
1922        assert_eq!(v.len(), 5);
1923    }
1924
1925    #[test]
1926    fn test_from_iter() {
1927        let env = Env::default();
1928
1929        // Create from std vector iterator
1930        let items = std::vec![1, 2, 3, 4, 5];
1931        let v = Vec::from_iter(&env, items);
1932        assert_eq!(v, vec![&env, 1, 2, 3, 4, 5]);
1933        assert_eq!(v.len(), 5);
1934
1935        // Create from array iterator
1936        let v2 = Vec::from_iter(&env, [10, 20, 30]);
1937        assert_eq!(v2, vec![&env, 10, 20, 30]);
1938        assert_eq!(v2.len(), 3);
1939
1940        // Create from range
1941        let v3 = Vec::from_iter(&env, 1..=4);
1942        assert_eq!(v3, vec![&env, 1, 2, 3, 4]);
1943        assert_eq!(v3.len(), 4);
1944    }
1945
1946    #[test]
1947    fn test_from_iter_empty() {
1948        let env = Env::default();
1949
1950        // Create from empty iterator
1951        let empty: std::vec::Vec<i64> = std::vec::Vec::new();
1952        let v = Vec::from_iter(&env, empty);
1953        assert_eq!(v, vec![&env]);
1954        assert_eq!(v.len(), 0);
1955
1956        // Create from empty range
1957        let v2 = Vec::from_iter(&env, 1..1);
1958        assert_eq!(v2, vec![&env]);
1959        assert_eq!(v2.len(), 0);
1960    }
1961
1962    #[test]
1963    fn test_from_iter_different_types() {
1964        let env = Env::default();
1965
1966        // Test with strings
1967        let strings = std::vec!["hello".to_string(), "world".to_string(), "test".to_string()];
1968        let v = Vec::from_iter(&env, strings);
1969        assert_eq!(
1970            v,
1971            vec![
1972                &env,
1973                "hello".to_string(),
1974                "world".to_string(),
1975                "test".to_string()
1976            ]
1977        );
1978        assert_eq!(v.len(), 3);
1979
1980        // Test with booleans
1981        let bools = [true, false, true, false];
1982        let v2 = Vec::from_iter(&env, bools.into_iter());
1983        assert_eq!(v2, vec![&env, true, false, true, false]);
1984        assert_eq!(v2.len(), 4);
1985    }
1986}
soroban_sdk/vec.rs

soroban_sdk/
vec.rs
