Init

cppdraft/range/dangling.md

@@ -0,0 +1,56 @@
+[range.dangling]
+
+# 25 Ranges library [[ranges]](./#ranges)
+
+## 25.5 Range utilities [[range.utility]](range.utility#range.dangling)
+
+### 25.5.5 Dangling iterator handling [range.dangling]
+
+[1](#1)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/ranges.tex#L2252)
+
+The type dangling is used together with the template aliasesborrowed_iterator_t and borrowed_subrange_t[.](#1.sentence-1)
+
+When an algorithm
+that typically returns an iterator into, or a subrange of, a range argument
+is called with an rvalue range argument
+that does not model [borrowed_range](range.range#concept:borrowed_range "25.4.2 Ranges [range.range]") ([[range.range]](range.range "25.4.2 Ranges")),
+the return value possibly refers to a range whose lifetime has ended[.](#1.sentence-2)
+
+In such cases,
+the type dangling is returned instead of an iterator or subrange[.](#1.sentence-3)
+
+[🔗](#lib:dangling)
+
+namespace std::ranges {struct dangling {constexpr dangling() noexcept = default; constexpr dangling(auto&&...) noexcept {}};}
+
+[2](#2)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/ranges.tex#L2272)
+
+[*Example [1](#example-1)*: vector<int> f();auto result1 = ranges::find(f(), 42); // #1static_assert([same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<decltype(result1), ranges::dangling>);auto vec = f();auto result2 = ranges::find(vec, 42); // #2static_assert([same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<decltype(result2), vector<int>::iterator>);auto result3 = ranges::find(ranges::subrange{vec}, 42); // #3static_assert([same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<decltype(result3), vector<int>::iterator>);
+
+The call to ranges​::​find at #1 returns ranges​::​dangling since f() is an rvalue vector;
+it is possible for the vector to be destroyed
+before a returned iterator is dereferenced[.](#2.sentence-1)
+
+However, the calls at #2 and #3 both return iterators
+since the lvalue vec and specializations of subrange model [borrowed_range](range.range#concept:borrowed_range "25.4.2 Ranges [range.range]")[.](#2.sentence-2)
+
+— *end example*]
+
+[3](#3)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/ranges.tex#L2293)
+
+For a type R that models [range](range.range#concept:range "25.4.2 Ranges [range.range]"):
+
+- [(3.1)](#3.1)
+
+if R models [borrowed_range](range.range#concept:borrowed_range "25.4.2 Ranges [range.range]"), thenborrowed_iterator_t<R> denotes iterator_t<R>, andborrowed_subrange_t<R> denotes subrange<iterator_t<R>>;
+
+- [(3.2)](#3.2)
+
+otherwise,
+both borrowed_iterator_t<R> and borrowed_subrange_t<R> denote dangling[.](#3.sentence-1)