Tracking issue: C++ standard library function overload compatibility

[teor2345]

Tasks for mentors

@teor2345:

• Set up a directory structure
• Add example successful and failing overloads
  • And inexpressible overloads, if there's a C++ feature with no equivalent in Rust
• Add CI to check both successful and failing overloads, with stderr output for failures
  • Add markdown lints to CI #3
• Add an overload macro compatibility table in Markdown
• Write instructions for applicants
  • Explain overall goals
  • Make a PR template for this
  • Copy AI policy summary from Outreachy project description to here
  • Add AGENTS/CLAUDE, CONTRIBUTING, update README
• Write a list of C++ standard library types with overloads
• Ethan: try following the applicant instructions below
• Open a ticket for each type so applicants can claim them

Later:

• Turn FIXME comments into bug/feature tickets, so we can reference them in multiple C++ class wrappers

Tasks for applicants

You must only open one pull request (PR).
Do not use AI to write code, PR descriptions, chats, or comments.

Follow these instructions:

Claim a ticket from the list below by commenting on it. This is the C++ type (or function) you will be working on.
Before you claim a ticket, make sure no-one else has commented before you.

After each step, submit your work as a PR, make sure CI passes, then wait for 2-4 days for a mentor to review it.
If you need help, post a message in the TODO link(outreachy/c++-overload-checks stream on Zulip).

1. Write Rust wrappers for 3-5 C++ overloads on that type:
   • Create a new file named after your type in overloading-macros/cpp-overload-test/src/stdcpp
   • Wrap constructors first
   • Explain any potential compatibility issues in a Limitations doc section
   • Explain usability issues in an Ergonomics doc section
2. Add a separate example with some failing overloads
   • Create a new file named after your type in overloading-macros/cpp-overload-test/examples
   • Wrap accessor/modifier methods
   • Explain how they fail in an Incompatibilities doc section
   • Explain how the overload failures could be resolved in a Workarounds doc section
   • Optional: If there's a C++ feature with no equivalent in Rust, explain that in an Inexpressible Overloads doc section
3. Update the overload macro compatibility table Markdown doc
   • TODO: link
   • If you haven't checked some kinds of overloads, leave those table cells blank

Ignore these overloads:

• overloaded operators: they are already possible in Rust
• overloads with an allocator argument, or that only differ by noexcept: not an interesting difference
• assignment functions, assignment operators, and swap: no equivalent in Rust (which uses memcpy for assignment/swaps)

Only give one example of overloads that:

• only differ by const/non-const, &/&& (or &/&mut)
• are iterator methods that only differ by position (before_begin/begin

You can look at stdcpp/forward_list.rs (working overloads) and stdcpp-forward-list.rs (failing overloads) for example code.

C++ Standard Library Types

Each of these types have overloads, we want to check if they can be called from Rust.

containers

• array
• vector
• deque
• list
• set
• map
• forward_list
  • constructors
  • [-] accessors
  • modifiers
  • transforms
• +8 others (mentor note: can be added if needed)
• +9 adapters/views

strings

• string
• u16string
• u32string

integer arithmetic functions

• saturating operations
• checked operations and their operator equivalents

io

• cout
• println
• cin

chrono

• system clock
• time point
• calendar functions

Trait-like:

• iterator primitive operations: advance, distance, next, prev, len?
• range primitive operations: begin, end, size, empty, data