Skip to content

CEP-0019: Owned Dynamic Iterator Construction

Draft

Draft proposal for constructing owned dynamic iterators directly from moved or rvalue receivers. V1 dynamic iteration uses explicit borrowed receiver setup.

Summary

Catalyst should eventually decide whether APIs such as iter_dyn_owned can construct Box(dyn Iterator(Item)) from moved or rvalue receivers.

V1 dynamic iteration supports explicit borrowed receivers and explicit allocator arguments. Owned dynamic iterator construction from moved/rvalue receivers is deferred.

Example

Possible future shape:

fn stream_lines(file: File, allocator: *std.mem.Allocator) Box(dyn Iterator(String))!Error {
  return move file.iter_dyn_owned(String, allocator)
}

The proposal must decide where ownership is transferred and which allocator owns the erased iterator state.

Motivation

Owned dynamic iterator construction can be ergonomic for pipelines and one-shot streams. It also touches ownership transfer, resource cleanup, allocator authority, dynamic metadata, and boxed dynamic values.

Those rules deserve a focused proposal instead of being hidden inside the canonical iterator contracts.

Proposed Direction

The proposal should decide:

  • whether owned dynamic iterator construction is a method, free function, or owner conversion;
  • how moved receivers transfer ownership into the iterator state;
  • how rvalue receivers are initialized directly into owned iterator storage;
  • how allocation failure cleans up partially constructed iterator state;
  • whether the API belongs to Iterable, Iterator, Box, or std;
  • how it interacts with Box(dyn Iterator(Item)) and closed boxed iterator forwarding.

V1 Compatibility

V1 users call iter_dyn or iter_dyn_mut explicitly with borrowed receiver authority, or use box_dyn/Box(dyn C).create_from_dyn on known iterator values.