Farthest(...)

@results = $index->Farthest( \%point );
$results = $index->Farthest( \%point );
@results = $index->Farthest( \%point, \%options );
$results = $index->Farthest( \%point, \%options );
@results = $index->Farthest( \%point, $number_of_points_desired );
$results = $index->Farthest( \%point, $number_of_points_desired );
@results = $index->Farthest( \%point, $number_of_points_desired, \%options );
$results = $index->Farthest( \%point, $number_of_points_desired, \%options );
Find the point or points farthest from a given point

In other words, find the points closest to a given point's antipode.

---

%point
The point to search relative to

This is either a reference to a hash containing at a minimum a lat and a lon value (both in degrees) or a reference to an array giving the point.
See the Points section for details.

$number_of_points_desired
The number of points that should be returned.

Set to 0 to not restrict the number of points returned or set it >0 to set the maximum number of points to return.

If omitted then this will default to 1.

%options
The parameters for the search (all are optional):

• radius
  Only return results within this distance (in meters) from search point.

  If no radius is specified or the radius is set to Geo::Index::ALL then all points in the index may potentially be returned.

• sort_results
  Sort results by distance from point

  By default points returned are sorted by distance. Set this to 0 to not sort the returned points.

  Although sorting is not mandatory, performing it is strongly recommended since otherwise the set of points returned are not guaranteed to be the farthest.

• pre_condition
  Reference to additional user-supplied code to determine whether each point should be included in the results.

  This code is run before the distance from the search point to the result point has been calculated.

  See Condition functions for syntax.

• post_condition
  Reference to additional user-supplied code to determine whether each point should be included in the results.

  This code is run after the distance from the search point to the result point has been calculated.

  By default, a post_condition function that filters out the search point is used. To remove this default function either specify a new one, set a value for user_data, or set post_condition to "NONE".

  See Condition functions for syntax.

• user_data
  Arbitrary user-supplied data that is passed to the condition functions.

  This can be used to allow the function access to additional data structures.

  If the default post_condition is active and no user_data value has been provided by the caller then this is set to the actual (non-antipodal) search point.

  See Condition functions for syntax.

Return value

In list context the return value is a list of references to the points found or an empty array if none were found.

In scalar context the return value is a reference to the aforementioned list or undef if no results were found.

For each point in the results the distance in meters from it to the search point will be stored in the search_result_distance entry in the result point's hash. In addition, the distance from a result point to the search point's antipode will be stored in the antipode_distance entry. These can be retrieved using e.g.:

$meters_from_search_point  = $$point{search_result_distance};
$meters_to_antipodal_point = $$point{antipode_distance};