Class S2Iterator<T extends S2Iterator.Entry>


  • @GwtCompatible
    public final class S2Iterator<T extends S2Iterator.Entry>
    extends java.lang.Object
    A random access iterator that provides low-level access to entries sorted by cell ID. The behavior of this iterator is more like a database cursor, where accessing properties at the current position does not alter the position of the cursor. The cursor has a compareTo(com.google.common.geometry.S2CellId) method to compare the value at the current position of the iterator with a given S2CellId.
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  S2Iterator.Entry
      An interface to provide the cell ID for an element in a sorted list.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.List<T> entries  
      protected int pos  
      private com.google.common.base.Function<S2CellId,​java.lang.Integer> seekFunction  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected S2Iterator​(java.util.List<T> entries)
      Create a new iterator based on the given list of entries.
      protected S2Iterator​(java.util.List<T> entries, com.google.common.base.Function<S2CellId,​java.lang.Integer> seekFunction)
      Same as S2Iterator(List), but accepts seekFunction, which is used as the implementation of seek(S2CellId).
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean atBegin()
      Returns true if the iterator is positioned at the first index cell.
      S2Point center()
      Returns the center of the cell (used as a reference point for shape interiors.)
      int compareTo​(S2CellId cellId)
      Returns the comparison from the current iterator cell to the given cell ID.
      S2Iterator<T> copy()
      Returns a copy of this iterator, positioned as this iterator is.
      (package private) static <T extends S2Iterator.Entry>
      S2Iterator<T>
      copy​(S2Iterator<T> it)
      Creates a new iterator with the same entries and position as it.
      (package private) static <T extends S2Iterator.Entry>
      S2Iterator<T>
      create​(java.util.List<T> entries)
      Creates an iterator given a list of entries.
      (package private) static <T extends S2Iterator.Entry>
      S2Iterator<T>
      create​(java.util.List<T> entries, com.google.common.base.Function<S2CellId,​java.lang.Integer> seekFunction)
      Same as create(List), but accepts seekFunction, which is used as the implementation of seek(S2CellId).
      boolean done()
      Returns true if the iterator is positioned past the last index cell.
      T entry()
      Returns the current entry.
      <T extends S2Iterator.Entry>
      boolean
      equalIterators​(S2Iterator<T> it)
      Returns true if these iterators have the same entries and position.
      boolean equals​(java.lang.Object o)
      Returns true if o is an S2Iterator with equal entries and position.
      void finish()
      Positions the iterator so that done() is true.
      int hashCode()  
      S2CellId id()
      Returns the cell id for the current cell.
      S2ShapeIndex.CellRelation locate​(S2CellId target)
      Positions the iterator at the index cell containing the given cell, if possible, and returns the S2ShapeIndex.CellRelation that describes the relationship between the index and the given target cell: Returns S2ShapeIndex.CellRelation.INDEXED if the iterator was positioned at an index cell that is equal to or contains the given cell.
      boolean locate​(S2Point targetPoint)
      Positions the iterator at the index cell containing "target" and returns true, or if no such cell exists in the index, the iterator is positioned arbitrarily and this method returns false.
      void next()
      Advances the iterator to the next cell in the index.
      void position​(S2Iterator<T> it)
      Set this iterator to the position given by the other iterator.
      void prev()
      Positions the iterator at the previous cell in the index.
      void restart()
      Positions the iterator so that atBegin() is true.
      void seek​(S2CellId target)
      Positions the iterator at the first cell with id() >= target, or at the end of the index if no such cell exists.
      void seekForward​(S2CellId target)
      Advances the iterator to the next cell with id() >= target.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • seekFunction

        private final com.google.common.base.Function<S2CellId,​java.lang.Integer> seekFunction
      • pos

        protected int pos
    • Constructor Detail

      • S2Iterator

        protected S2Iterator​(java.util.List<T> entries)
        Create a new iterator based on the given list of entries. Results are undefined if the entries are not in ascending sorted order.
        Parameters:
        entries - the list of entries which back this iterator.
      • S2Iterator

        protected S2Iterator​(java.util.List<T> entries,
                             com.google.common.base.Function<S2CellId,​java.lang.Integer> seekFunction)
        Same as S2Iterator(List), but accepts seekFunction, which is used as the implementation of seek(S2CellId).
        Parameters:
        entries - the list of entries which back this iterator.
        seekFunction - a function which takes a target S2CellId and returns an index to which this iterator will be repositioned.
    • Method Detail

      • create

        static <T extends S2Iterator.EntryS2Iterator<T> create​(java.util.List<T> entries)
        Creates an iterator given a list of entries. Package private and not public, since only S2 classes guarantee the necessary preconditions on entries -- that the cell IDs of each entry are sorted in ascending order.
      • create

        static <T extends S2Iterator.EntryS2Iterator<T> create​(java.util.List<T> entries,
                                                                 com.google.common.base.Function<S2CellId,​java.lang.Integer> seekFunction)
        Same as create(List), but accepts seekFunction, which is used as the implementation of seek(S2CellId).
        Parameters:
        entries - the list of entries which back this iterator.
        seekFunction - a function which takes a target S2CellId and returns an index to which this iterator will be repositioned.
      • copy

        public S2Iterator<T> copy()
        Returns a copy of this iterator, positioned as this iterator is.
      • restart

        public void restart()
        Positions the iterator so that atBegin() is true.
      • compareTo

        public int compareTo​(S2CellId cellId)
        Returns the comparison from the current iterator cell to the given cell ID.
      • equals

        public boolean equals​(java.lang.Object o)
        Returns true if o is an S2Iterator with equal entries and position.
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equalIterators

        public <T extends S2Iterator.Entry> boolean equalIterators​(S2Iterator<T> it)
        Returns true if these iterators have the same entries and position.
      • id

        public S2CellId id()
        Returns the cell id for the current cell.
      • entry

        public T entry()
        Returns the current entry.
      • center

        public S2Point center()
        Returns the center of the cell (used as a reference point for shape interiors.)
      • next

        public void next()
        Advances the iterator to the next cell in the index. Does not advance the iterator if pos is equal to the number of cells in the index.
      • prev

        public void prev()
        Positions the iterator at the previous cell in the index. Does not move the iterator if pos is equal to 0.
      • done

        public boolean done()
        Returns true if the iterator is positioned past the last index cell.
      • atBegin

        public boolean atBegin()
        Returns true if the iterator is positioned at the first index cell.
      • seek

        public void seek​(S2CellId target)
        Positions the iterator at the first cell with id() >= target, or at the end of the index if no such cell exists.
      • seekForward

        public void seekForward​(S2CellId target)
        Advances the iterator to the next cell with id() >= target. If the iterator is done() or already satisfies id() >= target, there is no effect.
      • finish

        public void finish()
        Positions the iterator so that done() is true.
      • locate

        public boolean locate​(S2Point targetPoint)
        Positions the iterator at the index cell containing "target" and returns true, or if no such cell exists in the index, the iterator is positioned arbitrarily and this method returns false.

        The resulting index position is guaranteed to contain all edges that might intersect the line segment between targetPoint and center().

      • locate

        public S2ShapeIndex.CellRelation locate​(S2CellId target)
        Positions the iterator at the index cell containing the given cell, if possible, and returns the S2ShapeIndex.CellRelation that describes the relationship between the index and the given target cell:
        • Returns S2ShapeIndex.CellRelation.INDEXED if the iterator was positioned at an index cell that is equal to or contains the given cell. I.e. the given target exists in the index as a leaf cell.
        • Returns S2ShapeIndex.CellRelation.SUBDIVIDED if the iterator was positioned at the first of one or more cells contained by the given target cell. I.e. the target does not exist in the index, but the first of its descendants was selected.
        • Returns S2ShapeIndex.CellRelation.DISJOINT if the iterator had to be positioned arbitrarily because the given target cell does not intersect any of the index's cells.
      • position

        public void position​(S2Iterator<T> it)
        Set this iterator to the position given by the other iterator.