types: add Struct iteration, and Extend for Struct, ListValue and FieldMask (#712)

Fixes #704.

Adds the collection items the issue lists, as one change:

- `Struct`: `len`, `is_empty`, `contains_key`, `iter`, `IntoIterator`
for `&Struct`, `&mut Struct` and `Struct`, and `Extend<(K, V)>` with the
`Into<String>` / `Into<Value>` bounds of `from_fields`. A key that is
already present has its value replaced, as `insert` does. The docs state
that iteration order is unspecified.
- `ListValue`: `Extend<V: Into<Value>>`, matching `from_values`.
- `FieldMask`: `Extend<T: Into<String>>`, appending without normalizing,
as `from_paths` does.

Two additions beyond the plan I posted on the issue:

- **`Struct::iter_mut`.** `IntoIterator for &mut Struct` needs a mutable
iterator anyway, and `ListValue` pairs the two the same way.
- **Three public iterator types, `StructIter`, `StructIterMut` and
`StructIntoIter`,** re-exported at the crate root. `Struct::fields` is
`buffa::__private::HashMap`, whose iterators are `std`'s or
`hashbrown`'s depending on the `std` feature, so the `IntoIterator`
impls need a type of their own to name. `serde_json::Map` takes the same
approach. They forward `fold` and `count` to the map's iterators,
implement `ExactSizeIterator` and `FusedIterator` (checked against the
inner types in a test), and are `#[must_use]`.

`FromIterator` keeps its existing item types (`(String, Value)` and
`Value`). Widening it to match `Extend` could break inference in
existing `collect` calls, so the crate docs describe the difference
instead.

Tests don't depend on hash order. One generic test checks that `C:
Extend<T> + IntoIterator` works for all three types, which is the
issue's motivation.

**Verification**

- `task lint`, `task doc`, `task check-nostd` and `task test-local`
(4211 passed, 0 failed), with the repository-pinned protoc 33.5. `cargo
+1.75 check -p buffa-types --all-features` with an MSRV-resolved
lockfile, as the `msrv-check` job does.
- Reviewed with the repo's `rust-code-reviewer` and
`rust-api-ergonomics-reviewer` per CLAUDE.md: no Critical or High
findings. Addressed the Mediums: the iterators forward `fold`/`count`,
and the docs no longer overstate the `FromIterator`/`Extend` symmetry.
Also addressed the Lows: a static check of the fused/exact-size claims,
`#[must_use]`, `Extend` doc wording, and `HashMap::extend` delegation.

---------

Co-authored-by: Iain McGinniss <iain@anthropic.com>

Author: farmer-data

.changes/unreleased/added-20261013-collection-impls.yaml

@@ -0,0 +1,4 @@
+kind: Added
+body: |-
+    **`Struct` gains `len`, `iter`, `IntoIterator` and related methods, and `Struct`, `ListValue` and `FieldMask` gain `Extend`** (#712, closes #704). `Struct` gains `len`, `is_empty`, `contains_key`, `iter`, `iter_mut`, `IntoIterator` for `&Struct`, `&mut Struct` and `Struct` (yielding the new `StructIter`, `StructIterMut` and `StructIntoIter`), and `Extend<(K, V)>` with the bounds of `from_fields`; an extended key that is already present takes the new value, as `insert` does. `ListValue` gains `Extend<V: Into<Value>>` and `FieldMask` gains `Extend<T: Into<String>>`, which appends without normalizing, as `from_paths` does. `FromIterator` keeps its existing item types (`(String, Value)` for `Struct`, `Value` for `ListValue`). `Struct::fields` is a hash map, so `Struct`'s iteration order is unspecified.
+time: 2026-10-13T08:58:19+08:00

buffa-types/src/field_mask_ext.rs

@@ -270,6 +270,14 @@ impl<T: Into<String>> FromIterator<T> for FieldMask {
     }
 }
 
+impl<T: Into<String>> Extend<T> for FieldMask {
+    /// Appends each path in iteration order, without validating or
+    /// normalizing, as [`FieldMask::from_paths`] does.
+    fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
+        self.paths.extend(iter.into_iter().map(Into::into));
+    }
+}
+
 impl<'a> IntoIterator for &'a FieldMask {
     type Item = &'a String;
     type IntoIter = core::slice::Iter<'a, String>;
@@ -404,6 +412,14 @@ mod tests {
         assert_eq!(mask, FieldMask::default());
     }
 
+    #[test]
+    fn extend_appends_without_normalizing() {
+        let mut mask = FieldMask::from_paths(["user"]);
+        mask.extend(["user.name", "user"]);
+        mask.extend(vec![String::from("settings")]);
+        assert_eq!(mask.paths, ["user", "user.name", "user", "settings"]);
+    }
+
     #[test]
     fn from_paths_empty() {
         let mask = FieldMask::from_paths(core::iter::empty::<&str>());

buffa-types/src/lib.rs

@@ -50,6 +50,12 @@
 //! - [`FieldMask`] path helpers: [`FieldMask::covers`], [`FieldMask::overlaps`],
 //!   [`FieldMask::normalize`], [`FieldMask::union`], [`FieldMask::intersection`]
 //! - `Value` constructors: [`Value::null`](google::protobuf::Value::null), `From<f64>`, `From<String>`, `From<bool>`, etc.
+//! - Collection impls: [`Struct`], [`ListValue`] and [`FieldMask`] each have
+//!   `len`, `is_empty`, `iter`, `IntoIterator`, `FromIterator` and `Extend`.
+//!   `Extend` accepts anything `Into` the element type, while `FromIterator`
+//!   on [`Struct`] and [`ListValue`] takes `(String, Value)` and [`Value`]
+//!   items. [`Struct`] iterates through [`StructIter`], [`StructIterMut`] and
+//!   [`StructIntoIter`], in unspecified order.
 //! - Wrapper type `From`/`Into` impls
 //!
 //! # Equality and hashing
@@ -237,10 +243,12 @@ pub use google::protobuf::{
     Any, Duration, Empty, FieldMask, ListValue, NullValue, Struct, Timestamp, Value,
 };
 
-// Re-export error types from extension modules (these are hand-written types
-// in private modules, so re-exporting is the only way to make them accessible).
+// Re-export error and iterator types from extension modules (these are
+// hand-written types in private modules, so re-exporting is the only way to
+// make them accessible).
 pub use duration_ext::DurationError;
 pub use timestamp_ext::TimestampError;
+pub use value_ext::{StructIntoIter, StructIter, StructIterMut};
 
 #[cfg(feature = "chrono")]
 #[cfg_attr(docsrs, doc(cfg(feature = "chrono")))]