lsst.sphgeom  19.0.0-3-gc70e9ed+1
Classes | Public Types | Public Member Functions | List of all members
lsst::sphgeom::RangeSet Class Reference

#include <RangeSet.h>

Classes

struct  Iterator
 

Public Types

using difference_type = ptrdiff_t
 
using size_type = size_t
 
using value_type = std::tuple< uint64_t, uint64_t >
 
using const_iterator = Iterator
 

Public Member Functions

 RangeSet (RangeSet const &)=default
 
 RangeSet (RangeSet &&)=default
 
RangeSetoperator= (RangeSet const &)=default
 
RangeSetoperator= (RangeSet &&)=default
 
 RangeSet ()=default
 The default constructor creates an empty set.
 
template<typename InputIterator , typename = typename std::enable_if< std::is_base_of< std::input_iterator_tag, typename std::iterator_traits<InputIterator>::iterator_category >::value >::type>
 RangeSet (InputIterator a, InputIterator b)
 
template<typename Container , typename = typename std::enable_if< std::is_base_of< std::input_iterator_tag, typename std::iterator_traits<decltype( std::begin(std::declval<typename std::add_const<Container>::type>()) )>::iterator_category, ::value &&std::is_base_of< std::input_iterator_tag, typename std::iterator_traits< decltype(std::end(std::declval< typename std::add_const< Container >::type >()))>::iterator_category , ::value , ::type >
 RangeSet (Container const &c)
 
RangeSetsimplify (uint32_t n)
 
RangeSet simplified (uint32_t n) const
 simplified returns a simplified copy of this set.
 
RangeSetscale (uint64_t i)
 
RangeSet scaled (uint64_t i) const
 scaled returns a scaled copy of this set.
 
void clear ()
 clear removes all integers from this set.
 
void fill ()
 fill adds all the unsigned 64 bit integers to this set.
 
bool empty () const
 empty checks whether there are any integers in this set.
 
bool full () const
 
Iterator beginc () const
 
Iterator endc () const
 
size_t max_size () const
 max_size returns the maximum number of ranges a set can hold.
 
size_t size () const
 size returns the number of ranges in this set.
 
uint64_t cardinality () const
 
void swap (RangeSet &s)
 
bool isValid () const
 
 RangeSet (uint64_t u)
 
 RangeSet (uint64_t first, uint64_t last)
 
template<typename U , typename = typename std::enable_if< std::is_convertible<U, uint64_t>::value >::type>
 RangeSet (std::tuple< U, U > const &range)
 
 RangeSet (std::initializer_list< uint64_t >)
 
 RangeSet (std::initializer_list< std::pair< uint64_t, uint64_t >>)
 
bool operator== (RangeSet const &rs) const
 
bool operator!= (RangeSet const &rs) const
 
void insert (uint64_t u)
 
template<typename U , typename = typename std::enable_if< std::is_convertible<U, uint64_t>::value >::type>
void insert (std::tuple< U, U > const &range)
 
void insert (uint64_t first, uint64_t last)
 
void erase (uint64_t u)
 
template<typename U , typename = typename std::enable_if< std::is_convertible<U, uint64_t>::value >::type>
void erase (std::tuple< U, U > const &range)
 
void erase (uint64_t first, uint64_t last)
 
Set operations
RangeSetcomplement ()
 
RangeSet complemented () const
 complemented returns a complemented copy of this set.
 
RangeSet intersection (RangeSet const &s) const
 intersection returns the intersection of this set and s.
 
RangeSet join (RangeSet const &s) const
 join returns the union of this set and s.
 
RangeSet difference (RangeSet const &s) const
 difference returns the difference between this set and s.
 
RangeSet symmetricDifference (RangeSet const &s) const
 
RangeSet operator~ () const
 The ~ operator returns the complement of this set.
 
RangeSet operator& (RangeSet const &s) const
 The & operator returns the intersection of this set and s.
 
RangeSet operator| (RangeSet const &s) const
 The | operator returns the union of this set and s.
 
RangeSet operator- (RangeSet const &s) const
 The - operator returns the difference between this set and s.
 
RangeSet operator^ (RangeSet const &s) const
 The ^ operator returns the symmetric difference between this set and s.
 
RangeSetoperator&= (RangeSet const &s)
 
RangeSetoperator|= (RangeSet const &s)
 
RangeSetoperator-= (RangeSet const &s)
 
RangeSetoperator^= (RangeSet const &s)
 
bool intersects (uint64_t u) const
 
bool intersects (uint64_t first, uint64_t last) const
 
bool intersects (RangeSet const &s) const
 
bool contains (uint64_t u) const
 
bool contains (uint64_t first, uint64_t last) const
 
bool contains (RangeSet const &s) const
 
bool isWithin (uint64_t u) const
 
bool isWithin (uint64_t first, uint64_t last) const
 
bool isWithin (RangeSet const &s) const
 
bool isDisjointFrom (uint64_t u) const
 
bool isDisjointFrom (uint64_t first, uint64_t last) const
 
bool isDisjointFrom (RangeSet const &s) const
 
Iterator begin () const
 
Iterator cbegin () const
 
Iterator end () const
 
Iterator cend () const
 

Detailed Description

A RangeSet is a set of unsigned 64 bit integers.

Internally, elements in the set are tracked using a sorted vector of disjoint, non-empty, half-open ranges, which is memory efficient for sets containing many consecutive integers.

Given a hierarchical pixelization of the sphere and a simple spherical region, a RangeSet is a good way to store the indexes of pixels intersecting the region. For an in-depth discussion of this use case, see:

Efficient data structures for masks on 2D grids M. Reinecke and E. Hivon Astronomy & Astrophysics, Volume 580, id.A132, 9 pp.

http://www.aanda.org/articles/aa/abs/2015/08/aa26549-15/aa26549-15.html

The beginning and end points of the disjoint, non-empty, half-open integer ranges in the set are stored in a std::vector<uint64_t>, with monotonically increasing values, except for the last one. Each pair of consecutive elements [begin, end) in the vector is a non-empty half-open range, where the value of end is defined as the integer obtained by adding one to the largest element in the range.

Mathematically, a half-open range with largest element equal to 2^64 - 1 would have an end point of 2^64. But arithmetic for unsigned 64 bit integers is modular, and adding 1 to 2^64 - 1 "wraps around" to 0. So in practice, ranges containing the largest uint64_t value have an end point of 0. Note that overflow is undefined for signed integers, which motivates the use of unsigned 64 bit integers for this class.

The first and last values of the internal vector are are always 0, even if no range in the set has a beginning or end point of 0. To illustrate why, consider the contents of the vector for a set containing a single integer, 3:

[0, 3, 4, 0]

The range obtained by extracting pairs of elements from the vector starting at index 1 is [3, 4), which corresponds to the contents of the set. The ranges obtained by starting at index 0 are [0, 3) and [4, 0). They correspond to the unsigned 64 bit integers not in the set.

The use of bookended half open ranges means that simply toggling the index of the first range between 0 and 1 corresponds to complementing the set. This allows many simplifications in the implementation - for example, set union and difference can be implemented in terms of set intersection and complement, since A ∪ B = ¬(¬A ∩ ¬B) and A ∖ B = A ∩ ¬B.

Many of the RangeSet methods accept ranges of integers [first, last) as input, either directly or in the form of a tuple. The values in a range are generated by starting with a value equal to first, and incrementing it until last is reached. If first == last, the range is full (it contains all possible uint64_t values), and if first > last, it wraps around - that is, it contains all uint64_t values except for [last, first).

The ranges in a set can be iterated over. Set modification may invalidate all iterators.

Constructor & Destructor Documentation

◆ RangeSet() [1/3]

lsst::sphgeom::RangeSet::RangeSet ( uint64_t  u)
inlineexplicit

This constructor creates a set containing the given integer(s) or integer range(s).

◆ RangeSet() [2/3]

template<typename InputIterator , typename = typename std::enable_if< std::is_base_of< std::input_iterator_tag, typename std::iterator_traits<InputIterator>::iterator_category >::value >::type>
lsst::sphgeom::RangeSet::RangeSet ( InputIterator  a,
InputIterator  b 
)
inline

This generic constructor creates a set containing the integers or ranges obtained by dereferencing the iterators in [a, b).

It is hidden via SFINAE if InputIterator is not a standard input iterator.

◆ RangeSet() [3/3]

template<typename Container , typename = typename std::enable_if< std::is_base_of< std::input_iterator_tag, typename std::iterator_traits<decltype( std::begin(std::declval<typename std::add_const<Container>::type>()) )>::iterator_category, ::value &&std::is_base_of< std::input_iterator_tag, typename std::iterator_traits< decltype(std::end(std::declval< typename std::add_const< Container >::type >()))>::iterator_category , ::value , ::type >
lsst::sphgeom::RangeSet::RangeSet ( Container const &  c)
inlineexplicit

This generic constructor creates a set containing the integers or integer ranges in the given container.

It is hidden via SFINAE if Container does not provide constant input iterators over its elements.

Member Function Documentation

◆ begin()

Iterator lsst::sphgeom::RangeSet::begin ( ) const
inline

This function returns a constant iterator to the first range in this set.

◆ beginc()

Iterator lsst::sphgeom::RangeSet::beginc ( ) const
inline

beginc returns a constant iterator to the first range in the complement of this set.

◆ cardinality()

uint64_t lsst::sphgeom::RangeSet::cardinality ( ) const

cardinality returns the number of integers in this set.

Note that 0 is returned both for full and empty sets (a full set contains 2^64 integers, which is 0 modulo 2^64).

◆ complement()

RangeSet& lsst::sphgeom::RangeSet::complement ( )
inline

complement replaces this set S with U ∖ S, where U is the universe of range sets, [0, 2^64). It runs in constant time.

◆ contains()

bool lsst::sphgeom::RangeSet::contains ( uint64_t  u) const
inline

contains returns true iff every one of the given integers is in this set.

◆ end()

Iterator lsst::sphgeom::RangeSet::end ( ) const
inline

This function returns a constant iterator to the range after the last one in this set.

◆ endc()

Iterator lsst::sphgeom::RangeSet::endc ( ) const
inline

endc returns a constant iterator to to the range after the last one in the complement of this set.

◆ erase()

void lsst::sphgeom::RangeSet::erase ( uint64_t  u)
inline

erase removes the given integers from this set.

The strong exception safety guarantee is provided.

◆ full()

bool lsst::sphgeom::RangeSet::full ( ) const
inline

full checks whether all integers in the universe of range sets, [0, 2^64), are in this set.

◆ insert()

void lsst::sphgeom::RangeSet::insert ( uint64_t  u)
inline

insert adds the given integer(s) to this set.

It is strongly exception safe, and runs in amortized constant time if the given integers extend or follow the last (largest) range in this set. Otherwise, the worst case run time is O(N), where N is the number of ranges in the set.

◆ intersects()

bool lsst::sphgeom::RangeSet::intersects ( uint64_t  u) const
inline

intersects returns true iff the intersection of this set and the given integers is non-empty.

◆ isDisjointFrom()

bool lsst::sphgeom::RangeSet::isDisjointFrom ( uint64_t  u) const
inline

isDisjointFrom returns true iff the intersection of this set and the given integers is empty.

◆ isValid()

bool lsst::sphgeom::RangeSet::isValid ( ) const

isValid checks that this RangeSet is in a valid state.

It is intended for use by unit tests, but calling it in other contexts is harmless. A return value of false means the RangeSet implementation isn't preserving its invariants, i.e. has a bug.

◆ isWithin()

bool lsst::sphgeom::RangeSet::isWithin ( uint64_t  u) const
inline

isWithin returns true iff every integer in this set is also one of the given integers.

◆ operator&=()

RangeSet& lsst::sphgeom::RangeSet::operator&= ( RangeSet const &  s)
inline

The &= operator assigns the intersection of this set and s to this set. It is strongly exception safe.

◆ operator-=()

RangeSet& lsst::sphgeom::RangeSet::operator-= ( RangeSet const &  s)
inline

The -= operator assigns the difference between this set and s to this set. It is strongly exception safe.

◆ operator==()

bool lsst::sphgeom::RangeSet::operator== ( RangeSet const &  rs) const
inline

Two RangeSet instances are equal iff they contain the same integers.

◆ operator^=()

RangeSet& lsst::sphgeom::RangeSet::operator^= ( RangeSet const &  s)
inline

The ^= operator assigns the symmetric difference between this set and s to this set. It is strongly exception safe.

◆ operator|=()

RangeSet& lsst::sphgeom::RangeSet::operator|= ( RangeSet const &  s)
inline

The |= operator assigns the union of this set and s to this set. It is strongly exception safe.

◆ scale()

RangeSet & lsst::sphgeom::RangeSet::scale ( uint64_t  i)

scale multiplies the endpoints of each range in this set by the given integer.

Given ranges that correspond to pixel indexes in a hierarchical pixelization of the sphere like HTM or Q3C, scaling by 4 corresponds to increasing the subdivision level of the pixelization by 1.

◆ simplify()

RangeSet & lsst::sphgeom::RangeSet::simplify ( uint32_t  n)

simplify simplifies this range set by "coarsening" its ranges.

The result is defined as the union of the ranges obtained by rounding existing range beginnings down to the nearest multiple of 2^n, and rounding the ends up. Therefore, simplifying a range set always results in a superset of the original set.

This function replaces many small ranges with fewer coarser ranges. If the ranges correspond to pixels in a hierarchical pixelization of the sphere that overlap a region R, then this operation can be thought of as computing a lower resolution representation of the coverage of R.

◆ symmetricDifference()

RangeSet lsst::sphgeom::RangeSet::symmetricDifference ( RangeSet const &  s) const

symmetricDifference returns the symmetric difference of this set and s.


The documentation for this class was generated from the following files: