Document the differing trimming behavior of absl::Span::subspan() and std::span::subspan()
`std::span::subspan()` has stricter preconditions than its `absl::`
counterpart. Supplying a `len` that would extend beyond the end of the
span is undefined behavior for `std::span` (unless `len` is the default
`npos` value), whereas `absl::span` simply truncates the result.
PiperOrigin-RevId: 836331418
Change-Id: I0e9a11cb434deca0b88d761e8233a44d5a9273ce
diff --git a/absl/types/span.h b/absl/types/span.h
index d2cf627..556c846 100644
--- a/absl/types/span.h
+++ b/absl/types/span.h
@@ -47,6 +47,9 @@
// * `absl::Span` has no static extent template parameter, nor constructors
// which exist only because of the static extent parameter.
// * `absl::Span` has an explicit mutable-reference constructor
+// * `absl::Span::subspan(pos, len)` always truncates `len` to
+// `size() - pos`, whereas `std::span::subspan()` only truncates when the
+// `len` parameter is defaulted.
//
// For more information, see the class comments below.
#ifndef ABSL_TYPES_SPAN_H_
@@ -449,6 +452,11 @@
// will be trimmed to at most size() - `pos`. A default `len` value of `npos`
// ensures the returned subspan continues until the end of the span.
//
+ // Note that trimming behavior differs from `std::span::subspan()`.
+ // `std::span::subspan()` requires `len == npos || pos + len <= size()`.
+ // In other words, `std::span::subspan()` only trims `len` when its value is
+ // defaulted.
+ //
// Examples:
//
// std::vector<int> vec = {10, 11, 12, 13};
