Add iterators (#14)

This adds something like Rust's `Iterator` trait but in a way that is
suitable for C++ use. We have:

- `best::iter` and friends.
- `best::int_range`, which `best::bounds` is now a specialization of.
It's an iterator.
- `best::span::find()` and `best::text::find()` now have standardized
interfaces.
- `best::span::split()`, `best::text::split()`.
- `best::text::runes()` and `best::text::rune_indices()`.
- `best::pretext`, i.e., a `best::text` that has not been validated.

Removed `best::rune::iter`, since it was a stopgap solution until we got
here.

README.md

@@ -51,6 +51,7 @@ pieces of functionality.
 - `best/container` - Container types. We interpret any generic "wrapper" type as
  a container.
 - `best/func` - Helpers for manipulating functions as first-class objects.
+- `best/iter` - Iterators and other functional programming types.
 - `best/log` - Logging utilities.
 - `best/math` - Numeric and integer utilities.
 - `best/memory` - Low-level memory management.

best/base/fwd.h

@@ -34,9 +34,6 @@
 //! best. Users SHOULD NOT forward-declared best types.
 
 namespace best {
-// best/container/bounds.h
-struct bounds;
-
 // best/container/choice.h
 template <typename...>
 class choice;
@@ -79,6 +76,21 @@ tap(Cb&&) -> tap<tags_internal_do_not_use::ctad_guard, best::as_auto<Cb>>;
 template <typename Cb>
 tap(best::bind_t, Cb&&) -> tap<tags_internal_do_not_use::ctad_guard, Cb&&>;
 
+// best/func/tap.h
+template <typename>
+class iter;
+template <typename Impl>
+iter(Impl) -> iter<Impl>;
+template <typename>
+class iter_range;
+template <typename Impl>
+iter_range(Impl) -> iter_range<Impl>;
+struct iter_range_end final {};
+
+// best/iter/bounds.h
+template <typename>
+struct int_range;
+
 // best/log/location.h
 template <typename>
 class track_location;
@@ -116,6 +128,8 @@ class formatter;
 // best/text/str.h
 template <typename>
 class text;
+template <typename>
+class pretext;
 
 // best/text/utf.h
 struct utf8;

best/container/BUILD

@@ -1,25 +1,5 @@
 package(default_visibility = ["//visibility:public"])
 
-cc_library(
- name = "bounds",
- hdrs = ["bounds.h"],
- srcs = ["bounds.cc"],
- deps = [
- ":simple_option",
- "//best/log/internal:crash",
- ],
-)
-
-cc_test(
- name = "bounds_test",
- srcs = ["bounds_test.cc"],
- linkopts = ["-rdynamic"],
- deps = [
- ":bounds",
- "//best/test",
- ],
-)
-
 cc_library(
  name = "choice",
  hdrs = [
@@ -167,6 +147,7 @@ cc_library(
  deps = [
  ":option",
  ":result",
+ "//best/iter",
  "//best/memory:bytes",
  ],
 )

best/container/internal/simple_option.h

@@ -33,6 +33,8 @@ namespace best::container_internal {
 template <typename T>
 class option final {
  public:
+ using type = T;
+
  constexpr option() = default;
  constexpr option(T value) : value_(BEST_MOVE(value)), has_(true) {}
 
@@ -59,13 +61,13 @@ class option final {
  return has_ && value_ == that;
  }
 
- // TODO: BestFmt
- template <typename Os>
- friend Os& operator<<(Os& os, option opt) {
- if (!opt.has_value()) {
- return os << "none";
+ friend void BestFmt(auto& fmt, const option& opt)
+  requires requires { fmt.format(opt.value_); }
+ {
+ if (opt.has_) {
+ fmt.format("option({:!})", opt.value_);
  } else {
- return os << "option(" << *opt << ")";
+ fmt.format("none");
  }
  }
 

best/container/option.h

@@ -58,7 +58,14 @@ inline constexpr struct none_t {
 /// Whether `T` is some `best::option<U>`.
 template <typename T>
 concept is_option =
- best::same<best::as_auto<T>, best::option<typename best::as_auto<T>::type>>;
+ best::same<best::as_auto<T>,
+ best::option<typename best::as_auto<T>::type>> ||
+ requires {
+ requires best::is_object<typename best::as_auto<T>::type>;
+ requires best::same<
+ best::as_auto<T>,
+ best::container_internal::option<typename best::as_auto<T>::type>>;
+ };
 
 /// # `best::option_type<T>`
 ///

best/container/row.h

@@ -83,7 +83,7 @@ args(Args&&...) -> args<Args&&...>;
 
 /// # `best::row<...>`
 ///
-/// A list of heterogenous things. Note that the semantics of `best::row`
+/// A list of heterogenous thing0s. Note that the semantics of `best::row`
 /// for non-object types does not match `std::tuple`. Instead, a `best::row`
 /// models a sequence of `best::object`s. In particular, a `best::row<T>` and
 /// a `best::choice<T>` have the same internal semantics.