Spatial C++ Library
Generic Multi-Dimensional Containers and Spatial Operations
spatial::neighbor_iterator< const Ct, Metric > Class Template Reference

A spatial iterator for a container Ct that goes through the nearest to the furthest element from a target key, with distances applied according to a user-defined geometric space of type Metric. More...

#include <spatial_neighbor.hpp>

Inherits Const_bidirectional_iterator < container_traits< Ct >::mode_type, container_traits< Ct >::rank_type >.

Public Types

typedef container_traits< Ct >::key_compare key_compare
 Key comparator type transferred from the container. More...
 
typedef Metric metric_type
 The metric type used by the iterator. More...
 
typedef Metric::distance_type distance_type
 The distance type that is read from metric_type. More...
 
typedef container_traits< Ct >::key_type key_type
 The key type that is used as a target for the nearest neighbor search. More...
 

Public Member Functions

 neighbor_iterator ()
 Constructs an empty, uninitialized object. More...
 
 neighbor_iterator (const Ct &container_, const Metric &metric_, const typename container_traits< Ct >::key_type &target_, typename container_traits< Ct >::const_iterator iter_, typename Metric::distance_type distance_)
 The standard way to build this iterator: specify a metric to apply, an iterator on a container, and that container. More...
 
 neighbor_iterator (const Ct &container_, const Metric &metric_, const typename container_traits< Ct >::key_type &target_, dimension_type node_dim_, typename container_traits< Ct >::mode_type::const_node_ptr node_, typename Metric::distance_type distance_)
 When the information of the dimension for the current node being pointed to by the iterator is known, this constructor saves some CPU cycle, by comparison to the other constructor. More...
 
 neighbor_iterator (const typename container_traits< Ct >::rank_type &rank_, const typename container_traits< Ct >::key_compare &key_comp_, const Metric &metric_, const typename container_traits< Ct >::key_type &target_, dimension_type node_dim_, typename container_traits< Ct >::mode_type::const_node_ptr node_, typename Metric::distance_type distance_)
 Build the iterator with a given rank and key compare functor, if the container is not available. More...
 
 neighbor_iterator (const neighbor_iterator< Ct, Metric > &iter)
 Convertion of mutable iterator into a constant iterator. More...
 
neighbor_iterator< const Ct, Metric > & operator++ ()
 Increments the iterator and returns the incremented value. More...
 
neighbor_iterator< const Ct, Metric > operator++ (int)
 Increments the iterator but returns the value of the iterator before the increment. More...
 
neighbor_iterator< const Ct, Metric > & operator-- ()
 Decrements the iterator and returns the decremented value. More...
 
neighbor_iterator< const Ct, Metric > operator-- (int)
 Decrements the iterator but returns the value of the iterator before the decrement. More...
 
key_compare key_comp () const
 Return the key_comparator used by the iterator. More...
 
metric_type metric () const
 Return the metric used by the iterator. More...
 
distance_type distance () const
 Read-only accessor to the last valid distance of the iterator. More...
 
distance_typedistance ()
 Read/write accessor to the last valid distance of the iterator. More...
 
const key_typetarget_key () const
 Read-only accessor to the target of the iterator. More...
 
key_typetarget_key ()
 Read/write accessor to the target of the iterator. More...
 

Private Types

typedef details::Const_bidirectional_iterator< typename container_traits< Ct >::mode_type, typename container_traits< Ct >::rank_type > Base
 

Private Attributes

details::Neighbor_data< Ct, Metric > _data
 The related data for the iterator. More...
 

Detailed Description

template<typename Ct, typename Metric>
class spatial::neighbor_iterator< const Ct, Metric >

A spatial iterator for a container Ct that goes through the nearest to the furthest element from a target key, with distances applied according to a user-defined geometric space of type Metric.

The Metric type is a complex type that must be a model of Metric:

struct Metric
{
typedef my_distance_type distance_type;
distance_type
distance_to_key(dimension_type rank,
const Key& origin, const Key& key) const;
distance_type
distance_to_plane(dimension_type rank, dimension_type dim,
const Key& origin, const Key& key) const;
};

The details of the Metric type are explained in Metric. Metrics are generally not defined by the user of the library, given their complexity. Rather, the user of the library uses ready-made models of Metric such as spatial::euclidian and spatial::manhattan. If more metrics needs to be defined, see the explanation in for the Metric concept.

This iterator only returns constant objects.

Template Parameters
CtThe container type bound to the iterator.
DistanceTypeThe type used to represent distances.
MetricAn type that follow the Metric concept.

Definition at line 340 of file spatial_neighbor.hpp.

Member Typedef Documentation

template<typename Ct , typename Metric >
typedef details::Const_bidirectional_iterator<typename container_traits<Ct>::mode_type, typename container_traits<Ct>::rank_type> spatial::neighbor_iterator< const Ct, Metric >::Base
private

Definition at line 348 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
typedef Metric::distance_type spatial::neighbor_iterator< const Ct, Metric >::distance_type

The distance type that is read from metric_type.

Definition at line 362 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
typedef container_traits<Ct>::key_compare spatial::neighbor_iterator< const Ct, Metric >::key_compare

Key comparator type transferred from the container.

Definition at line 356 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
typedef container_traits<Ct>::key_type spatial::neighbor_iterator< const Ct, Metric >::key_type

The key type that is used as a target for the nearest neighbor search.

Definition at line 365 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
typedef Metric spatial::neighbor_iterator< const Ct, Metric >::metric_type

The metric type used by the iterator.

Definition at line 359 of file spatial_neighbor.hpp.

Constructor & Destructor Documentation

template<typename Ct , typename Metric >
spatial::neighbor_iterator< const Ct, Metric >::neighbor_iterator ( )

Constructs an empty, uninitialized object.

Definition at line 368 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
spatial::neighbor_iterator< const Ct, Metric >::neighbor_iterator ( const Ct &  container_,
const Metric &  metric_,
const typename container_traits< Ct >::key_type target_,
typename container_traits< Ct >::const_iterator  iter_,
typename Metric::distance_type  distance_ 
)

The standard way to build this iterator: specify a metric to apply, an iterator on a container, and that container.

Parameters
container_The container to iterate.
metric_The metric applied during the iteration.
target_The target of the neighbor iteration.
iter_An iterator on container.
distance_The distance between the node pointed to by iter_ and target_ according to metric_.

Definition at line 382 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
spatial::neighbor_iterator< const Ct, Metric >::neighbor_iterator ( const Ct &  container_,
const Metric &  metric_,
const typename container_traits< Ct >::key_type target_,
dimension_type  node_dim_,
typename container_traits< Ct >::mode_type::const_node_ptr  node_,
typename Metric::distance_type  distance_ 
)

When the information of the dimension for the current node being pointed to by the iterator is known, this constructor saves some CPU cycle, by comparison to the other constructor.

Parameters
container_The container to iterate.
metric_The metric applied during the iteration.
target_The target of the neighbor iteration.
node_dim_The dimension of the node pointed to by iterator.
node_Use the value of node as the start point for the iteration.
distance_The distance between node_ and target_ according to metric_.

In order to iterate through nodes in the k-d tree built in the container, the algorithm must know at each node which dimension is used to partition the space. Some algorithms will provide this dimension, such as the function spatial::details::modulo().

Attention
Specifying the incorrect dimension value for the node will result in unknown behavior. It is recommended that you do not use this constructor if you are not sure about this dimension, and use the other constructors instead.

Definition at line 415 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
spatial::neighbor_iterator< const Ct, Metric >::neighbor_iterator ( const typename container_traits< Ct >::rank_type &  rank_,
const typename container_traits< Ct >::key_compare key_comp_,
const Metric &  metric_,
const typename container_traits< Ct >::key_type target_,
dimension_type  node_dim_,
typename container_traits< Ct >::mode_type::const_node_ptr  node_,
typename Metric::distance_type  distance_ 
)

Build the iterator with a given rank and key compare functor, if the container is not available.

It requires the node information to be known but is a fast constructor.

Parameters
rank_The rank of the container being iterated.
key_comp_The key compare functor associated with the iterator.
metric_The metric applied during the iteration.
target_The target of the neighbor iteration.
node_dim_The dimension of the node pointed to by iterator.
node_Use the value of node as the start point for the iteration.
distance_The distance between node_ and target_ according to metric_.
Attention
Specifying the incorrect dimension value for the node will result in unknown behavior. It is recommended that you do not use this constructor if you are not sure about this dimension, and use the other constructors instead.

Definition at line 444 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
spatial::neighbor_iterator< const Ct, Metric >::neighbor_iterator ( const neighbor_iterator< Ct, Metric > &  iter)

Convertion of mutable iterator into a constant iterator.

Definition at line 455 of file spatial_neighbor.hpp.

Member Function Documentation

template<typename Ct , typename Metric >
distance_type spatial::neighbor_iterator< const Ct, Metric >::distance ( ) const

Read-only accessor to the last valid distance of the iterator.

Definition at line 512 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
distance_type& spatial::neighbor_iterator< const Ct, Metric >::distance ( )

Read/write accessor to the last valid distance of the iterator.

Definition at line 516 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
key_compare spatial::neighbor_iterator< const Ct, Metric >::key_comp ( ) const

Return the key_comparator used by the iterator.

Definition at line 504 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
metric_type spatial::neighbor_iterator< const Ct, Metric >::metric ( ) const

Return the metric used by the iterator.

Definition at line 508 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
neighbor_iterator<const Ct, Metric>& spatial::neighbor_iterator< const Ct, Metric >::operator++ ( )

Increments the iterator and returns the incremented value.

Prefer to use this form in for loops.

Definition at line 462 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
neighbor_iterator<const Ct, Metric> spatial::neighbor_iterator< const Ct, Metric >::operator++ ( int  )

Increments the iterator but returns the value of the iterator before the increment.

Prefer to use the other form in for loops.

Definition at line 472 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
neighbor_iterator<const Ct, Metric>& spatial::neighbor_iterator< const Ct, Metric >::operator-- ( )

Decrements the iterator and returns the decremented value.

Prefer to use this form in for loops.

Definition at line 483 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
neighbor_iterator<const Ct, Metric> spatial::neighbor_iterator< const Ct, Metric >::operator-- ( int  )

Decrements the iterator but returns the value of the iterator before the decrement.

Prefer to use the other form in for loops.

Definition at line 493 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
const key_type& spatial::neighbor_iterator< const Ct, Metric >::target_key ( ) const

Read-only accessor to the target of the iterator.

Definition at line 520 of file spatial_neighbor.hpp.

template<typename Ct , typename Metric >
key_type& spatial::neighbor_iterator< const Ct, Metric >::target_key ( )

Read/write accessor to the target of the iterator.

Definition at line 524 of file spatial_neighbor.hpp.

Member Data Documentation

template<typename Ct , typename Metric >
details::Neighbor_data<Ct, Metric> spatial::neighbor_iterator< const Ct, Metric >::_data
private

The related data for the iterator.

Definition at line 528 of file spatial_neighbor.hpp.


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