[libcu++] Implement cuda::std::format_to_n

[davebayer]

No description provided.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4a54ea89-7000-4458-8872-2ca0e916c28f

📥 Commits

Reviewing files that changed from the base of the PR and between b840c5d and 48b1a2c.

📒 Files selected for processing (6)

• libcudacxx/include/cuda/std/__format/buffer.h
• libcudacxx/include/cuda/std/__format/format_to_n.h
• libcudacxx/include/cuda/std/__format_
• libcudacxx/include/cuda/std/__fwd/format.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/checkers/format_to_n.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to_n.pass.cpp

💤 Files with no reviewable changes (1)

• libcudacxx/include/cuda/std/__format/buffer.h

✅ Files skipped from review due to trivial changes (1)

• libcudacxx/include/cuda/std/__fwd/format.h

🚧 Files skipped from review as they are similar to previous changes (2)

• libcudacxx/include/cuda/std/__format/format_to_n.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/checkers/format_to_n.h

---

Note: CodeRabbit is enabled on this repository as a convenience for maintainers
and contributors. Use your best judgment when considering its review comments and
suggestions — a suggested change may be inadequate, unnecessary, or safe to ignore.
Contributors are not expected to address every comment. Human reviews are what
ultimately matter for merging.

Overview

This PR implements cuda::std::format_to_n, a C++ standard library formatting function that writes formatted output to an iterator with a bounded limit on the number of code units written. The implementation includes the core API, result type with CTAD support, an internal counting buffer, and comprehensive tests.

Changes

New Public API

• format_to_n_result<_OutIt>: A struct template containing:

  • _OutIt out: The output iterator after formatting
  • iter_difference_t<_OutIt> size: Total number of code units that would have been written (regardless of the limit)

• format_to_n overloads (two variants):

  • format_to_n(_OutIt, iter_difference_t<_OutIt>, format_string<_Args...>, _Args&&...) for narrow character output
  • format_to_n(_OutIt, iter_difference_t<_OutIt>, wformat_string<_Args...>, _Args&&...) for wide character output (gated by _CCCL_HAS_WCHAR_T())

Implementation Details

• __fmt_format_to_n_buffer<_OutIt, _CharT>: Internal buffer template that inherits from __fmt_buffer_select_t and:

  • Clamps negative count values to zero using cuda::std::cmp_less
  • Tracks the total number of code units written
  • Provides an output iterator interface for formatting

• __format_to_n_impl: Internal helper function that:

  • Constructs the appropriate format_context or wformat_context based on template parameter
  • Delegates to __fmt_vformat_to for actual formatting
  • Returns the final format_to_n_result with actual and total written counts

Infrastructure Changes

• Added forward declaration of format_to_n_result in __fwd/format.h
• Updated the __format_ umbrella header to include __format/format_to_n.h
• Removed unused #include <cuda/std/__utility/cmp.h> from buffer.h

Test Coverage

• Type verification: static_assert checks confirm correct return types and non-noexcept specification
• Functional tests validate:
  • Writing zero code units (empty output)
  • Positive write counts with back-insertion iterators
  • Direct iterator writes with pre-sized buffers
  • Negative count handling (verifies no output is written and iterator remains unchanged)
  • Result size field correctly reports total code units that would have been written

Walkthrough

Adds cuda::std::format_to_n with format_to_n_result<_OutIt>, a clamping/counting internal buffer (__fmt_format_to_n_buffer), an internal dispatch helper (__format_to_n_impl), and narrow/wide public overloads. Wires the forward declaration in fwd/format.h, adds the new header to the umbrella __format_ include, removes an unused cmp.h include from buffer.h, and adds a test checker plus a test translation unit.

format_to_n implementation and tests

Layer / File(s)	Summary
Forward declaration, umbrella wiring, and buffer.h cleanup libcudacxx/include/cuda/std/__fwd/format.h, libcudacxx/include/cuda/std/__format/buffer.h, libcudacxx/include/cuda/std/__format_	Adds format_to_n_result forward declaration in fwd/format.h, includes format_to_n.h from the umbrella header, and removes the unused cmp.h include from buffer.h.
format_to_n_result, limiting buffer, and format_to_n overloads libcudacxx/include/cuda/std/__format/format_to_n.h	New header defining format_to_n_result<_OutIt> with CTAD, __fmt_format_to_n_buffer that clamps negative counts to zero and tracks total code units written, __format_to_n_impl that constructs format contexts and calls __fmt_vformat_to, and narrow/wide format_to_n overloads returning format_to_n_result.
format_to_n test checker and test translation unit libcudacxx/test/.../checkers/format_to_n.h, libcudacxx/test/.../format_to_n.pass.cpp	Checker validates n==0 back-insert, positive n back-insert, positive n with inplace_vector (iterator advance and remaining-element sentinel checks), and negative n with signed-type static_assert and sentinel array verification; check_exception is a no-op. format_to_n.pass.cpp adds static_assert checks on return type and noexcept for char* and wchar_t*.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 288d730a-885d-4c9f-9b87-fc647b0a03e7

📥 Commits

Reviewing files that changed from the base of the PR and between f52338f and 3f4e243.

📒 Files selected for processing (6)

• libcudacxx/include/cuda/std/__format/buffer.h
• libcudacxx/include/cuda/std/__format/format_to_n.h
• libcudacxx/include/cuda/std/__format_
• libcudacxx/include/cuda/std/__fwd/format.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/checkers/format_to_n.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to_n.pass.cpp

💤 Files with no reviewable changes (1)

• libcudacxx/include/cuda/std/__format/buffer.h

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: fea81086-1519-4098-a892-afeba001b0bf

📥 Commits

Reviewing files that changed from the base of the PR and between 3f4e243 and b840c5d.

📒 Files selected for processing (19)

• libcudacxx/include/cuda/std/__format/buffer.h
• libcudacxx/include/cuda/std/__format/format_string.h
• libcudacxx/include/cuda/std/__format/format_to.h
• libcudacxx/include/cuda/std/__format/format_to_n.h
• libcudacxx/include/cuda/std/__format/vformat_to.h
• libcudacxx/include/cuda/std/__format_
• libcudacxx/include/cuda/std/__fwd/format.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/checkers/format_to.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/checkers/format_to_n.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.bool.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.buffer.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.char.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.handle.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.pointer.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.signed_integer.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.string.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.unsigned_integer.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to_n.pass.cpp

💤 Files with no reviewable changes (1)

• libcudacxx/include/cuda/std/__format/buffer.h

✅ Files skipped from review due to trivial changes (8)

• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.char.pass.cpp
• libcudacxx/include/cuda/std/_format
• libcudacxx/include/cuda/std/__fwd/format.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.handle.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.signed_integer.pass.cpp
• libcudacxx/include/cuda/std/__format/format_string.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.unsigned_integer.pass.cpp
• libcudacxx/test/libcudacxx/std/text/format/format.functions/format_to.buffer.pass.cpp

🚧 Files skipped from review as they are similar to previous changes (2)

• libcudacxx/include/cuda/std/__format/format_to_n.h
• libcudacxx/test/libcudacxx/std/text/format/format.functions/checkers/format_to_n.h

[miscco]

Same comments as the PR before,

I am not a fan of the test setup, but its probably necessary given the compile times

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 4h 18m: Pass: 100%/118 | Total: 5d 12h | Max: 4h 18m | Hits: 45%/1465731

See results here.