Documentation

Std.Data.TreeSet.Basic

Tree sets #

This file develops the type Std.TreeSet of tree sets.

Lemmas about the operations on Std.Data.TreeSet will be available in the module Std.Data.TreeSet.Lemmas.

See the module Std.Data.TreeSet.Raw.Basic for a variant of this type which is safe to use in nested inductive types.

structure Std.TreeSet (α : Type u) (cmp : ααOrdering := by exact compare) :

Tree sets.

A tree set stores elements of a certain type in a certain order. It depends on a comparator function that defines an ordering on the keys and provides efficient order-dependent queries, such as retrieval of the minimum or maximum.

To ensure that the operations behave as expected, the comparator function cmp should satisfy certain laws that ensure a consistent ordering:

  • If a is less than (or equal) to b, then b is greater than (or equal) to a and vice versa (see the OrientedCmp typeclass).
  • If a is less than or equal to b and b is, in turn, less than or equal to c, then a is less than or equal to c (see the TransCmp typeclass).

Keys for which cmp a b = Ordering.eq are considered the same, i.e., there can be only one of them be contained in a single tree set at the same time.

To avoid expensive copies, users should make sure that the tree set is used linearly.

Internally, the tree sets are represented as size-bounded trees, a type of self-balancing binary search tree with efficient order statistic lookups.

These tree sets contain a bundled well-formedness invariant, which means that they cannot be used in nested inductive types. For these use cases, Std.TreeSet.Raw and Std.TreeSet.Raw.WF unbundle the invariant from the tree set. When in doubt, prefer TreeSet over TreeSet.Raw.

  • inner : TreeMap α Unit cmp

    Internal implementation detail of the tree map.

Instances For
    @[inline]
    def Std.TreeSet.empty {α : Type u} {cmp : ααOrdering} :
    TreeSet α cmp

    Creates a new empty tree set. It is also possible and recommended to use the empty collection notations and {} to create an empty tree set. simp replaces empty with .

    Equations
    Instances For
      instance Std.TreeSet.instEmptyCollection {α : Type u} {cmp : ααOrdering} :
      Equations
      instance Std.TreeSet.instInhabited {α : Type u} {cmp : ααOrdering} :
      Equations
      @[simp]
      theorem Std.TreeSet.empty_eq_emptyc {α : Type u} {cmp : ααOrdering} :
      @[inline]
      def Std.TreeSet.insert {α : Type u} {cmp : ααOrdering} (l : TreeSet α cmp) (a : α) :
      TreeSet α cmp

      Inserts the given element into the set. If the tree set already contains an element that is equal (with regard to cmp) to the given element, then the tree set is returned unchanged.

      Note: this non-replacement behavior is true for TreeSet and TreeSet.Raw. The insert function on TreeMap, DTreeMap, TreeMap.Raw and DTreeMap.Raw behaves differently: it will overwrite an existing mapping.

      Equations
      Instances For
        instance Std.TreeSet.instSingleton {α : Type u} {cmp : ααOrdering} :
        Singleton α (TreeSet α cmp)
        Equations
        instance Std.TreeSet.instInsert {α : Type u} {cmp : ααOrdering} :
        Insert α (TreeSet α cmp)
        Equations
        instance Std.TreeSet.instLawfulSingleton {α : Type u} {cmp : ααOrdering} :
        @[inline]
        def Std.TreeSet.containsThenInsert {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (a : α) :
        Bool × TreeSet α cmp

        Checks whether an element is present in a set and inserts the element if it was not found. If the tree set already contains an element that is equal (with regard to cmp to the given element, then the tree set is returned unchanged.

        Equivalent to (but potentially faster than) calling contains followed by insert.

        Equations
        Instances For
          @[inline]
          def Std.TreeSet.contains {α : Type u} {cmp : ααOrdering} (l : TreeSet α cmp) (a : α) :

          Returns true if a, or an element equal to a according to the comparator cmp, is contained in the set. There is also a Prop-valued version of this: a ∈ t is equivalent to t.contains a = true.

          Observe that this is different behavior than for lists: for lists, uses = and contains uses == for equality checks, while for tree sets, both use the given comparator cmp.

          Equations
          Instances For
            instance Std.TreeSet.instMembership {α : Type u} {cmp : ααOrdering} :
            Membership α (TreeSet α cmp)
            Equations
            instance Std.TreeSet.instDecidableMem {α : Type u} {cmp : ααOrdering} {m : TreeSet α cmp} {a : α} :
            Equations
            @[inline]
            def Std.TreeSet.size {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) :

            Returns the number of mappings present in the map.

            Equations
            Instances For
              @[inline]
              def Std.TreeSet.isEmpty {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) :

              Returns true if the tree set contains no mappings.

              Equations
              Instances For
                @[inline]
                def Std.TreeSet.erase {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (a : α) :
                TreeSet α cmp

                Removes the given key if it exists.

                Equations
                Instances For
                  @[inline]
                  def Std.TreeSet.get? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (a : α) :

                  Checks if given key is contained and returns the key if it is, otherwise none. The result in the some case is guaranteed to be pointer equal to the key in the map.

                  Equations
                  Instances For
                    @[inline]
                    def Std.TreeSet.get {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (a : α) (h : a t) :
                    α

                    Retrieves the key from the set that matches a. Ensures that such a key exists by requiring a proof of a ∈ m. The result is guaranteed to be pointer equal to the key in the set.

                    Equations
                    Instances For
                      @[inline]
                      def Std.TreeSet.get! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) (a : α) :
                      α

                      Checks if given key is contained and returns the key if it is, otherwise panics. If no panic occurs the result is guaranteed to be pointer equal to the key in the set.

                      Equations
                      Instances For
                        @[inline]
                        def Std.TreeSet.getD {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (a fallback : α) :
                        α

                        Checks if given key is contained and returns the key if it is, otherwise fallback. If they key is contained the result is guaranteed to be pointer equal to the key in the set.

                        Equations
                        Instances For
                          @[inline]
                          def Std.TreeSet.min? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) :

                          Tries to retrieve the smallest element of the tree set, returning none if the set is empty.

                          Equations
                          Instances For
                            @[inline]
                            def Std.TreeSet.min {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (h : t.isEmpty = false) :
                            α

                            Given a proof that the tree set is not empty, retrieves the smallest element.

                            Equations
                            Instances For
                              @[inline]
                              def Std.TreeSet.min! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) :
                              α

                              Tries to retrieve the smallest element of the tree set, panicking if the set is empty.

                              Equations
                              Instances For
                                @[inline]
                                def Std.TreeSet.minD {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (fallback : α) :
                                α

                                Tries to retrieve the smallest element of the tree set, returning fallback if the tree set is empty.

                                Equations
                                Instances For
                                  @[inline]
                                  def Std.TreeSet.max? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) :

                                  Tries to retrieve the largest element of the tree set, returning none if the set is empty.

                                  Equations
                                  Instances For
                                    @[inline]
                                    def Std.TreeSet.max {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (h : t.isEmpty = false) :
                                    α

                                    Given a proof that the tree set is not empty, retrieves the largest element.

                                    Equations
                                    Instances For
                                      @[inline]
                                      def Std.TreeSet.max! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) :
                                      α

                                      Tries to retrieve the largest element of the tree set, panicking if the set is empty.

                                      Equations
                                      Instances For
                                        @[inline]
                                        def Std.TreeSet.maxD {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (fallback : α) :
                                        α

                                        Tries to retrieve the largest element of the tree set, returning fallback if the tree set is empty.

                                        Equations
                                        Instances For
                                          @[inline]
                                          def Std.TreeSet.atIdx? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (n : Nat) :

                                          Returns the n-th smallest element, or none if n is at least t.size.

                                          Equations
                                          Instances For
                                            @[inline]
                                            def Std.TreeSet.atIdx {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (n : Nat) (h : n < t.size) :
                                            α

                                            Returns the n-th smallest element.

                                            Equations
                                            Instances For
                                              @[inline]
                                              def Std.TreeSet.atIdx! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) (n : Nat) :
                                              α

                                              Returns the n-th smallest element, or panics if n is at least t.size.

                                              Equations
                                              Instances For
                                                @[inline]
                                                def Std.TreeSet.atIdxD {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (n : Nat) (fallback : α) :
                                                α

                                                Returns the n-th smallest element, or fallback if n is at least t.size.

                                                Equations
                                                Instances For
                                                  @[inline]
                                                  def Std.TreeSet.getGE? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k : α) :

                                                  Tries to retrieve the smallest element that is greater than or equal to the given element, returning none if no such element exists.

                                                  Equations
                                                  Instances For
                                                    @[inline]
                                                    def Std.TreeSet.getGT? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k : α) :

                                                    Tries to retrieve the smallest element that is greater than the given element, returning none if no such element exists.

                                                    Equations
                                                    Instances For
                                                      @[inline]
                                                      def Std.TreeSet.getLE? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k : α) :

                                                      Tries to retrieve the largest element that is less than or equal to the given element, returning none if no such element exists.

                                                      Equations
                                                      Instances For
                                                        @[inline]
                                                        def Std.TreeSet.getLT? {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k : α) :

                                                        Tries to retrieve the smallest element that is less than the given element, returning none if no such element exists.

                                                        Equations
                                                        Instances For

                                                          getGE, getGT, getLE, getLT can be found in Std.Data.TreeSet.AdditionalOperations.

                                                          @[inline]
                                                          def Std.TreeSet.getGE! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) (k : α) :
                                                          α

                                                          Tries to retrieve the smallest element that is greater than or equal to the given element, panicking if no such element exists.

                                                          Equations
                                                          Instances For
                                                            @[inline]
                                                            def Std.TreeSet.getGT! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) (k : α) :
                                                            α

                                                            Tries to retrieve the smallest element that is greater than the given element, panicking if no such element exists.

                                                            Equations
                                                            Instances For
                                                              @[inline]
                                                              def Std.TreeSet.getLE! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) (k : α) :
                                                              α

                                                              Tries to retrieve the largest element that is less than or equal to the given element, panicking if no such element exists.

                                                              Equations
                                                              Instances For
                                                                @[inline]
                                                                def Std.TreeSet.getLT! {α : Type u} {cmp : ααOrdering} [Inhabited α] (t : TreeSet α cmp) (k : α) :
                                                                α

                                                                Tries to retrieve the smallest element that is less than the given element, panicking if no such element exists.

                                                                Equations
                                                                Instances For
                                                                  @[inline]
                                                                  def Std.TreeSet.getGED {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k fallback : α) :
                                                                  α

                                                                  Tries to retrieve the smallest element that is greater than or equal to the given element, returning fallback if no such element exists.

                                                                  Equations
                                                                  Instances For
                                                                    @[inline]
                                                                    def Std.TreeSet.getGTD {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k fallback : α) :
                                                                    α

                                                                    Tries to retrieve the smallest element that is greater than the given element, returning fallback if no such element exists.

                                                                    Equations
                                                                    Instances For
                                                                      @[inline]
                                                                      def Std.TreeSet.getLED {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k fallback : α) :
                                                                      α

                                                                      Tries to retrieve the largest element that is less than or equal to the given element, returning fallback if no such element exists.

                                                                      Equations
                                                                      Instances For
                                                                        @[inline]
                                                                        def Std.TreeSet.getLTD {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (k fallback : α) :
                                                                        α

                                                                        Tries to retrieve the smallest element that is less than the given element, returning fallback if no such element exists.

                                                                        Equations
                                                                        Instances For
                                                                          @[inline]
                                                                          def Std.TreeSet.filter {α : Type u} {cmp : ααOrdering} (f : αBool) (m : TreeSet α cmp) :
                                                                          TreeSet α cmp

                                                                          Removes all elements from the tree set for which the given function returns false.

                                                                          Equations
                                                                          Instances For
                                                                            @[inline]
                                                                            def Std.TreeSet.foldlM {α : Type u} {cmp : ααOrdering} {m : Type u_1 → Type u_2} {δ : Type u_1} [Monad m] (f : δαm δ) (init : δ) (t : TreeSet α cmp) :
                                                                            m δ

                                                                            Monadically computes a value by folding the given function over the elements in the tree set in ascending order.

                                                                            Equations
                                                                            Instances For
                                                                              @[inline, deprecated Std.TreeSet.foldlM (since := "2025-02-12")]
                                                                              def Std.TreeSet.foldM {α : Type u} {cmp : ααOrdering} {δ : Type w} {m : Type w → Type w₂} [Monad m] (f : δαm δ) (init : δ) (t : TreeSet α cmp) :
                                                                              m δ

                                                                              Monadically computes a value by folding the given function over the elements in the tree set in ascending order.

                                                                              Equations
                                                                              Instances For
                                                                                @[inline]
                                                                                def Std.TreeSet.foldl {α : Type u} {cmp : ααOrdering} {δ : Type w} (f : δαδ) (init : δ) (t : TreeSet α cmp) :
                                                                                δ

                                                                                Folds the given function over the elements of the tree set in ascending order.

                                                                                Equations
                                                                                Instances For
                                                                                  @[inline, deprecated Std.TreeSet.foldl (since := "2025-02-12")]
                                                                                  def Std.TreeSet.fold {α : Type u} {cmp : ααOrdering} {δ : Type w} (f : δαδ) (init : δ) (t : TreeSet α cmp) :
                                                                                  δ

                                                                                  Folds the given function over the elements of the tree set in ascending order.

                                                                                  Equations
                                                                                  Instances For
                                                                                    @[inline]
                                                                                    def Std.TreeSet.foldrM {α : Type u} {cmp : ααOrdering} {m : Type u_1 → Type u_2} {δ : Type u_1} [Monad m] (f : αδm δ) (init : δ) (t : TreeSet α cmp) :
                                                                                    m δ

                                                                                    Monadically computes a value by folding the given function over the elements in the tree set in descending order.

                                                                                    Equations
                                                                                    Instances For
                                                                                      @[inline]
                                                                                      def Std.TreeSet.foldr {α : Type u} {cmp : ααOrdering} {δ : Type w} (f : αδδ) (init : δ) (t : TreeSet α cmp) :
                                                                                      δ

                                                                                      Folds the given function over the elements of the tree set in descending order.

                                                                                      Equations
                                                                                      Instances For
                                                                                        @[inline, deprecated Std.TreeSet.foldr (since := "2025-02-12")]
                                                                                        def Std.TreeSet.revFold {α : Type u} {cmp : ααOrdering} {δ : Type w} (f : δαδ) (init : δ) (t : TreeSet α cmp) :
                                                                                        δ

                                                                                        Folds the given function over the elements of the tree set in descending order.

                                                                                        Equations
                                                                                        Instances For
                                                                                          @[inline]
                                                                                          def Std.TreeSet.partition {α : Type u} {cmp : ααOrdering} (f : αBool) (t : TreeSet α cmp) :
                                                                                          TreeSet α cmp × TreeSet α cmp

                                                                                          Partitions a tree set into two tree sets based on a predicate.

                                                                                          Equations
                                                                                          Instances For
                                                                                            @[inline]
                                                                                            def Std.TreeSet.forM {α : Type u} {cmp : ααOrdering} {m : Type w → Type w₂} [Monad m] (f : αm PUnit) (t : TreeSet α cmp) :

                                                                                            Carries out a monadic action on each element in the tree set in ascending order.

                                                                                            Equations
                                                                                            Instances For
                                                                                              @[inline]
                                                                                              def Std.TreeSet.forIn {α : Type u} {cmp : ααOrdering} {δ : Type w} {m : Type w → Type w₂} [Monad m] (f : αδm (ForInStep δ)) (init : δ) (t : TreeSet α cmp) :
                                                                                              m δ

                                                                                              Support for the for loop construct in do blocks. The iteration happens in ascending order.

                                                                                              Equations
                                                                                              Instances For
                                                                                                instance Std.TreeSet.instForM {α : Type u} {cmp : ααOrdering} {m : Type w → Type w₂} :
                                                                                                ForM m (TreeSet α cmp) α
                                                                                                Equations
                                                                                                instance Std.TreeSet.instForIn {α : Type u} {cmp : ααOrdering} {m : Type w → Type w₂} :
                                                                                                ForIn m (TreeSet α cmp) α
                                                                                                Equations
                                                                                                • One or more equations did not get rendered due to their size.
                                                                                                @[inline]
                                                                                                def Std.TreeSet.any {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (p : αBool) :

                                                                                                Check if all elements satisfy the predicate, short-circuiting if a predicate fails.

                                                                                                Equations
                                                                                                Instances For
                                                                                                  @[inline]
                                                                                                  def Std.TreeSet.all {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) (p : αBool) :

                                                                                                  Check if any element satisfies the predicate, short-circuiting if a predicate succeeds.

                                                                                                  Equations
                                                                                                  Instances For
                                                                                                    @[inline]
                                                                                                    def Std.TreeSet.toList {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) :
                                                                                                    List α

                                                                                                    Transforms the tree set into a list of elements in ascending order.

                                                                                                    Equations
                                                                                                    Instances For
                                                                                                      def Std.TreeSet.ofList {α : Type u} (l : List α) (cmp : ααOrdering := by exact compare) :
                                                                                                      TreeSet α cmp

                                                                                                      Transforms a list into a tree set.

                                                                                                      Equations
                                                                                                      Instances For
                                                                                                        @[inline, deprecated Std.TreeSet.ofList (since := "2025-02-12")]
                                                                                                        def Std.TreeSet.fromList {α : Type u} (l : List α) (cmp : ααOrdering) :
                                                                                                        TreeSet α cmp

                                                                                                        Transforms a list into a tree set.

                                                                                                        Equations
                                                                                                        Instances For
                                                                                                          @[inline]
                                                                                                          def Std.TreeSet.toArray {α : Type u} {cmp : ααOrdering} (t : TreeSet α cmp) :

                                                                                                          Transforms the tree set into an array of elements in ascending order.

                                                                                                          Equations
                                                                                                          Instances For
                                                                                                            def Std.TreeSet.ofArray {α : Type u} (a : Array α) (cmp : ααOrdering := by exact compare) :
                                                                                                            TreeSet α cmp

                                                                                                            Transforms an array into a tree set.

                                                                                                            Equations
                                                                                                            Instances For
                                                                                                              @[inline, deprecated Std.TreeSet.ofArray (since := "2025-02-12")]
                                                                                                              def Std.TreeSet.fromArray {α : Type u} (a : Array α) (cmp : ααOrdering) :
                                                                                                              TreeSet α cmp

                                                                                                              Transforms an array into a tree set.

                                                                                                              Equations
                                                                                                              Instances For
                                                                                                                @[inline]
                                                                                                                def Std.TreeSet.merge {α : Type u} {cmp : ααOrdering} (t₁ t₂ : TreeSet α cmp) :
                                                                                                                TreeSet α cmp

                                                                                                                Returns a set that contains all mappings of t₁ and `t₂.

                                                                                                                This function ensures that t₁ is used linearly. Hence, as long as t₁ is unshared, the performance characteristics follow the following imperative description: Iterate over all mappings in t₂, inserting them into t₁.

                                                                                                                Hence, the runtime of this method scales logarithmically in the size of t₁ and linearly in the size of t₂ as long as t₁ is unshared.

                                                                                                                Equations
                                                                                                                Instances For
                                                                                                                  @[inline]
                                                                                                                  def Std.TreeSet.insertMany {α : Type u} {cmp : ααOrdering} {ρ : Type u_1} [ForIn Id ρ α] (t : TreeSet α cmp) (l : ρ) :
                                                                                                                  TreeSet α cmp

                                                                                                                  Inserts multiple elements into the tree set by iterating over the given collection and calling insert. If the same element (with respect to cmp) appears multiple times, the first occurrence takes precedence.

                                                                                                                  Note: this precedence behavior is true for TreeSet and TreeSet.Raw. The insertMany function on TreeMap, DTreeMap, TreeMap.Raw and DTreeMap.Raw behaves differently: it will prefer the last appearance.

                                                                                                                  Equations
                                                                                                                  Instances For
                                                                                                                    @[inline]
                                                                                                                    def Std.TreeSet.eraseMany {α : Type u} {cmp : ααOrdering} {ρ : Type u_1} [ForIn Id ρ α] (t : TreeSet α cmp) (l : ρ) :
                                                                                                                    TreeSet α cmp

                                                                                                                    Erases multiple items from the tree set by iterating over the given collection and calling erase.

                                                                                                                    Equations
                                                                                                                    Instances For
                                                                                                                      instance Std.TreeSet.instRepr {α : Type u} {cmp : ααOrdering} [Repr α] :
                                                                                                                      Repr (TreeSet α cmp)
                                                                                                                      Equations