From 4a851046a0102cd986a5714a1af8deef28a544c4 Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Tue, 16 Jun 2020 12:36:35 -0700 Subject: Export of internal Abseil changes -- 1f80d4f1cb8847545627a2d0b18f697c4a763292 by Samuel Benzaquen : Add a hint message to the assertions for easier debugging. Also, move it out of the template to avoid printing the whole template instantiation as part of the assertion. It is not relevant and can significantly bloat the error message and hide the important bits. PiperOrigin-RevId: 316736140 -- 223e97a90150de5b7206be2e45c62a9b70ac02df by Tom Manshreck : Update Span description to remove "view" terminology, in light of recent clarification of the differences between a view and a span type. PiperOrigin-RevId: 316734382 -- 361b87d55b1809a5da3f72a996686f27b3d630c2 by Evan Brown : Allow for explicit conversion of values in btree range constructor/insert. PiperOrigin-RevId: 316725951 GitOrigin-RevId: 1f80d4f1cb8847545627a2d0b18f697c4a763292 Change-Id: I74e2b095bc24710b27ed63ed94a50ef8f0fc897f --- absl/types/span.h | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'absl/types') diff --git a/absl/types/span.h b/absl/types/span.h index 4e450fc9..95fe7926 100644 --- a/absl/types/span.h +++ b/absl/types/span.h @@ -17,10 +17,13 @@ // span.h // ----------------------------------------------------------------------------- // -// This header file defines a `Span` type for holding a view of an existing -// array of data. The `Span` object, much like the `absl::string_view` object, -// does not own such data itself. A span provides a lightweight way to pass -// around view of such data. +// This header file defines a `Span` type for holding a reference to existing +// array data. The `Span` object, much like the `absl::string_view` object, +// does not own such data itself, and the data being referenced by the span must +// outlive the span itself. Unlike `view` type references, a span can hold a +// reference to mutable data (and can mutate it for underlying types of +// non-const T.) A span provides a lightweight way to pass a reference to such +// data. // // Additionally, this header file defines `MakeSpan()` and `MakeConstSpan()` // factory functions, for clearly creating spans of type `Span` or read-only @@ -72,9 +75,9 @@ ABSL_NAMESPACE_BEGIN // Span //------------------------------------------------------------------------------ // -// A `Span` is an "array view" type for holding a view of a contiguous data -// array; the `Span` object does not and cannot own such data itself. A span -// provides an easy way to provide overloads for anything operating on +// A `Span` is an "array reference" type for holding a reference of contiguous +// array data; the `Span` object does not and cannot own such data itself. A +// span provides an easy way to provide overloads for anything operating on // contiguous sequences without needing to manage pointers and array lengths // manually. @@ -92,7 +95,8 @@ ABSL_NAMESPACE_BEGIN // constructors. // // A `Span` is somewhat analogous to an `absl::string_view`, but for an array -// of elements of type `T`. A user of `Span` must ensure that the data being +// of elements of type `T`, and unlike an `absl::string_view`, a span can hold a +// reference to mutable data. A user of `Span` must ensure that the data being // pointed to outlives the `Span` itself. // // You can construct a `Span` in several ways: @@ -122,7 +126,7 @@ ABSL_NAMESPACE_BEGIN // Note that `Span` objects, in addition to requiring that the memory they // point to remains alive, must also ensure that such memory does not get // reallocated. Therefore, to avoid undefined behavior, containers with -// associated span views should not invoke operations that may reallocate memory +// associated spans should not invoke operations that may reallocate memory // (such as resizing) or invalidate iterators into the container. // // One common use for a `Span` is when passing arguments to a routine that can -- cgit v1.2.3