- 3a9532fb2d6ae45c3cba44c9bb0dbdfc1558b7d3 Fix the description of Span::subspan(). by Abseil Team <absl-team@google.com>

  - bae1a1c21924bd31fa7315eff05ea6158d9e7947 Port the symbolizer to Windows. by Derek Mauro <dmauro@google.com>
  - 2253c04c1a4f39d9581772f1dc4491878aa3831f Support absl::Hex() and absl::Dec() as arguments to absl:... by Jorg Brown <jorg@google.com>
  - 552c3ac259e9c254fda9244755487f3423d2fe4b Internal change by Jorg Brown <jorg@google.com>

GitOrigin-RevId: 3a9532fb2d6ae45c3cba44c9bb0dbdfc1558b7d3
Change-Id: I448133c9bb6d837037c12b45a9a16a7945049453

1 files changed, 14 insertions, 4 deletions

diff --git a/absl/types/span.h b/absl/types/span.h
index d365f17d5219..0ca30d1d0f08 100644
--- a/absl/types/span.h
+++ b/absl/types/span.h
@@ -458,10 +458,20 @@ class Span {
 
   // Span::subspan()
   //
-  // Returns a `Span` starting at element `pos` and of length `len`, with
-  // proper bounds checking to ensure `len` does not exceed the ptr+size of the
-  // original array. (Spans whose `len` would point past the end of the array
-  // will throw a `std::out_of_range`.)
+  // Returns a `Span` starting at element `pos` and of length `len`. Both `pos`
+  // and `len` are of type `size_type` and thus non-negative. Parameter `pos`
+  // must be <= size(). Any `len` value that points past the end of the span
+  // 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.
+  //
+  // Examples:
+  //
+  //   std::vector<int> vec = {10, 11, 12, 13};
+  //   absl::MakeSpan(vec).subspan(1, 2);  // {11, 12}
+  //   absl::MakeSpan(vec).subspan(2, 8);  // {12, 13}
+  //   absl::MakeSpan(vec).subspan(1);     // {11, 12, 13}
+  //   absl::MakeSpan(vec).subspan(4);     // {}
+  //   absl::MakeSpan(vec).subspan(5);     // throws std::out_of_range
   constexpr Span subspan(size_type pos = 0, size_type len = npos) const {
     return (pos <= len_)
                ? Span(ptr_ + pos, span_internal::Min(len_ - pos, len))