Merge branch 'main' into associated-type-errors

Author: mootz12

soroban-sdk/build.rs

@@ -5,10 +5,14 @@ pub fn main() {
     // hash.
     println!("cargo::rustc-check-cfg=cfg(soroban_sdk_internal_no_rssdkver_meta)");
 
-    #[cfg(all(target_family = "wasm", target_os = "unknown"))]
-    if let Ok(version) = rustc_version::version() {
-        if version.major == 1 && version.minor >= 82 {
-            panic!("Rust compiler 1.82+ with target 'wasm32-unknown-unknown' is unsupported by the Soroban Environment, because the 'wasm32-unknown-unknown' target in Rust 1.82+ has features enabled that are not yet supported and not easily disabled: reference-types, multi-value. Use Rust 1.81 to build for the 'wasm32-unknown-unknown' target.");
+    // Check if we're building for wasm32-unknown-unknown target (cross-compilation safe)
+    if std::env::var("CARGO_CFG_TARGET_FAMILY").as_deref() == Ok("wasm")
+        && std::env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("unknown")
+    {
+        if let Ok(version) = rustc_version::version() {
+            if version.major == 1 && version.minor >= 82 {
+                panic!("Rust compiler 1.82+ with target 'wasm32-unknown-unknown' is unsupported by the Soroban Environment, use 'wasm32v1-none' available with Rust 1.84+. The 'wasm32-unknown-unknown' target in Rust 1.82+ has features enabled that are not yet supported and not easily disabled: reference-types, multi-value. If you must build for the 'wasm32-unknown-unknown' use Rust 1.81 or earlier.");
+            }
         }
     }
 

soroban-sdk/src/iter.rs

@@ -1,6 +1,14 @@
 //! Iterators for use with collections like [Map], [Vec].
+//!
+//! Collections are not guaranteed to contain values of the expected type as
+//! they are stored on the host as [Val]s, so two iterators are provided:
+//!
+//! - **`try_iter()`** returns an iterator that yields `Result<T, E>` for each
+//!   element, allowing the caller to handle conversion errors.
+//! - **`iter()`** returns an iterator that unwraps each result,
+//!   panicking if any element cannot be converted to the declared type.
 #[cfg(doc)]
-use crate::{Map, Vec};
+use crate::{Map, Val, Vec};
 
 use core::fmt::Debug;
 use core::iter::FusedIterator;

soroban-sdk/src/map.rs

@@ -53,8 +53,9 @@ macro_rules! map {
 /// converted from [Val] back into their type.
 ///
 /// The pairs of keys and values in a Map are not guaranteed to be of type
-/// `K`/`V` and conversion will fail if they are not. Most functions on Map
-/// return a `Result` due to this.
+/// `K`/`V` and conversion will fail if they are not. Most functions on Map have
+/// a try_ variation that returns a Result that will be Err if the conversion fails.
+/// Functions that are not prefixed with try_ will panic if conversion fails."
 ///
 /// There are some cases where this lack of guarantee is important:
 ///
@@ -445,15 +446,23 @@ where
         self.obj = env.map_del(self.obj, k.into_val(env)).unwrap_infallible();
     }
 
-    /// Returns a [Vec] of all keys in the map.
+    /// Returns a [Vec] of all keys in the map, ordered in the map's key-sorted order.
+    ///
+    /// This method does not validate that the keys in the map are of type `K`. Since [Map]
+    /// keys are not guaranteed to be of type `K`, it is not guaranteed that all values
+    /// in the returned [Vec] will be of type `K`.
     #[inline(always)]
     pub fn keys(&self) -> Vec<K> {
         let env = self.env();
         let vec = env.map_keys(self.obj).unwrap_infallible();
         Vec::<K>::try_from_val(env, &vec).unwrap()
     }
 
-    /// Returns a [Vec] of all values in the map.
+    /// Returns a [Vec] of all values in the map, ordered in the map's key-sorted order.
+    ///
+    /// This method does not validate that the values in the map are of type `V`. Since [Map]
+    /// values are not guaranteed to be of type `V`, it is not guaranteed that all values
+    /// in the returned [Vec] will be of type `V`.
     #[inline(always)]
     pub fn values(&self) -> Vec<V> {
         let env = self.env();
@@ -495,6 +504,14 @@ where
     K: IntoVal<Env, Val> + TryFromVal<Env, Val>,
     V: IntoVal<Env, Val> + TryFromVal<Env, Val>,
 {
+    /// Returns an iterator over the key-value pairs of the map.
+    ///
+    /// Each entry is converted from [Val] to `(K, V)` as it is yielded.
+    ///
+    /// ### Panics
+    ///
+    /// If any key or value cannot be converted to its declared type.
+    /// Use [`try_iter`](Map::try_iter) to handle conversion errors.
     #[inline(always)]
     pub fn iter(&self) -> UnwrappedIter<MapTryIter<K, V>, (K, V), ConversionError>
     where
@@ -504,6 +521,8 @@ where
         self.clone().into_iter()
     }
 
+    /// Returns an iterator over the key-value pairs of the map, yielding
+    /// `Result<(K, V), ConversionError>` for each entry.
     #[inline(always)]
     pub fn try_iter(&self) -> MapTryIter<K, V>
     where

soroban-sdk/src/vec.rs

@@ -961,6 +961,14 @@ impl<T> Vec<T>
 where
     T: IntoVal<Env, Val> + TryFromVal<Env, Val>,
 {
+    /// Returns an iterator over the elements of the vec.
+    ///
+    /// Each element is converted from [Val] to `T` as it is yielded.
+    ///
+    /// ### Panics
+    ///
+    /// If any element cannot be converted to type `T`. Use
+    /// [`try_iter`](Vec::try_iter) to handle conversion errors.
     #[inline(always)]
     pub fn iter(&self) -> UnwrappedIter<VecTryIter<T>, T, T::Error>
     where
@@ -970,6 +978,8 @@ where
         self.try_iter().unwrapped()
     }
 
+    /// Returns an iterator over the elements of the vec, yielding
+    /// `Result<T, ConversionError>` for each element.
     #[inline(always)]
     pub fn try_iter(&self) -> VecTryIter<T>
     where

soroban-sdk/src/xdr.rs

@@ -29,18 +29,68 @@ use crate::{
 // Re-export all the XDR from the environment.
 pub use crate::env::xdr::*;
 
-/// Implemented by types that can be serialized to [Bytes].
+/// Implemented by types that can be serialized to [Bytes] as XDR.
 ///
-/// All types that are convertible to [Val] are implemented.
+/// All types that are convertible to [Val] implement this trait. The value is
+/// first converted to a [Val], then serialized to XDR in its [ScVal] form.
+///
+/// ### Examples
+///
+/// ```
+/// use soroban_sdk::{xdr::ToXdr, Env};
+///
+/// let env = Env::default();
+///
+/// let value: u32 = 5;
+/// let bytes = value.to_xdr(&env);
+/// assert_eq!(bytes.len(), 8);
+/// ```
 pub trait ToXdr {
+    /// Serializes the value to XDR as [Bytes].
     fn to_xdr(self, env: &Env) -> Bytes;
 }
 
-/// Implemented by types that can be deserialized from [Bytes].
+/// Implemented by types that can be deserialized from [Bytes] containing XDR.
+///
+/// All types that are convertible from [Val] implement this trait. The bytes
+/// are deserialized from their [ScVal] XDR form into a [Val], then converted
+/// to the target type.
+///
+/// ### Errors
+///
+/// Returns an error if the [Val] cannot be converted into the target type.
+///
+/// ### Panics
+///
+/// Panics if the provided bytes are not valid XDR for an [ScVal].
+///
+/// ### Examples
+///
+/// ```
+/// use soroban_sdk::{xdr::{ToXdr, FromXdr}, Env};
+///
+/// let env = Env::default();
+///
+/// let value: u32 = 5;
+/// let bytes = value.to_xdr(&env);
 ///
-/// All types that are convertible from [Val] are implemented.
+/// let roundtrip = u32::from_xdr(&env, &bytes);
+/// assert_eq!(roundtrip, Ok(5));
+/// ```
 pub trait FromXdr: Sized {
+    /// The error type returned if the [Val] cannot be converted into the
+    /// target type.
     type Error;
+    /// Deserializes the value from XDR [Bytes].
+    ///
+    /// ### Errors
+    ///
+    /// Returns an error if the [Val] cannot be converted into the target
+    /// type.
+    ///
+    /// ### Panics
+    ///
+    /// Panics if the provided bytes are not valid XDR for an [ScVal].
     fn from_xdr(env: &Env, b: &Bytes) -> Result<Self, Self::Error>;
 }