geodesk::Features Class Reference

A collection of geographic features. More...

#include <Features.h>

Inheritance diagram for geodesk::Features:

Public Member Functions
	Features (const char *golFile)
	Creates a collection that contains all features in the given Geographic Object Library.
	Features (const Features &other)
	Creates a collection with all the features in the other collection.
State and Membership
	operator bool () const
	Returns true if this collection contains at least one Feature.
bool	operator! () const
	Returns true if this collection is empty.
bool	contains (const Feature &feature) const
	Checks if the specified Feature exists in this collection.
Filtering by type and tags
Features	operator() (const char *query) const
	Only features that match the given query.
Nodes	nodes () const
	Only nodes.
Nodes	nodes (const char *query) const
	Only nodes that match the given query.
Ways	ways () const
	Only ways.
Ways	ways (const char *query) const
	Only ways that match the given query.
Relations	relations () const
	Only relations.
Relations	relations (const char *query) const
	Only relations that match the given query.
Retrieving Features
std::optional< Feature >	first () const
	Returns the first Feature in this collection, or std::nullopt if the collection is empty.
Feature	one () const
	Returns the one and only Feature in this collection.
void	addTo (std::vector< Feature > &features) const
	Appends the Feature objects in this collection to the given std::vector.
void	addTo (std::vector< FeaturePtr > &features) const
	Appends the Feature objects in this collection to the given std::vector as FeaturePtr pointers.
Scalar Queries
uint64_t	count () const
	Returns the total number of features in this collection.
double	length () const
	Computes the total length (in meters) of the features in this collection.
double	area () const
	Computes the total area (in square meters) of the features in this collection.
Spatial Filters
Features	operator() (const Box &box) const
	Only features whose bounding box intersects the given bounding box.
Features	operator() (Coordinate xy) const
	Only features whose bounding box contains the given Coordinate.
Features	operator() (const Feature &feature) const
	Only features whose geometry intersects with the given Feature (short form of intersecting())
Features	intersecting (const Feature &feature) const
	Only features whose geometry intersects with the given Feature.
Features	within (const Feature &feature) const
	Only features that lie entirely inside the geometry of the given Feature.
Features	containing (const Feature &feature) const
	Only features whose geometry contains the given Feature.
Features	containing (Coordinate xy) const
	Only features whose geometry contains the given Coordinate.
Features	containingLonLat (double lon, double lat) const
	Only features whose geometry contains the given location.
Features	crossing (const Feature &feature) const
	Only features whose geometry crosses the given Feature.
Features	maxMetersFrom (double distance, Coordinate xy) const
	Only features whose closest point lies within distance meters of xy.
Features	maxMetersFrom (double distance, double lon, double lat) const
	Only features whose closest point lies within distance meters of the given location.
Topological Filters
Features	nodesOf (const Feature &feature) const
	Only nodes that belong to the given Way.
Features	membersOf (const Feature &feature) const
	Only features that belong to the given Relation.
Features	parentsOf (const Feature &feature) const
	Only features that are parent relations of the given Feature (or parent ways of the given Node).
Features	connectedTo (const Feature &feature) const
	Only features that share a common node with the given Feature.
Filtering with Predicate
template<typename Predicate >
Features	filter (Predicate predicate) const
	Only features that match the given predicate.
Access to the Low-Level API
FeatureStore *	store () const noexcept
	Returns a pointer to the FeatureStore which contains the features in this collection.

Detailed Description

A collection of geographic features.

A Features object isn't a traditional container; it doesn't actually hold any Feature objects. Instead, it defines the criteria for retrieving features from a Geographic Object Library. A query is only executed whenever the Features object is iterated, assigned to a container, or when one of its scalar functions (such as count() or length()) is called. Query results are not cached. For example, calling count() before iterating over a Features object will result in the query being executed twice.

Features objects are lightweight, thread-safe, and designed to be passed by value. They can be safely shared across threads. Matchers, filters, and related resources (such as temporary indexes) use reference counting to ensure efficient and safe resource management.

To start working with a GOL, simply create a Features object with the path of its file (the .gol extension may be omitted):

Features world("path/to/planet.gol");

This creates a FeatureStore that manages access to planet.gol. The world object now represents a collection of all features stored in the GOL (It is legal to create multiple Features objects that refer to the same GOL – they will share the same FeatureStore).

To obtain subsets, apply filters using () or by calling a named method – or intersect multiple Features object with &:

Features hotels = world("na[tourism=hotel]");  // All hotels
Features inParis = world.within(paris);        // All features in Paris
 
// Only hotels in Paris:
Features hotelsInParis = hotels.within(paris);
// or...
Features hotelsInParis = hotels & inParis;

Applying a filter creates a copy of the Features object, with the additional constraint. The original Features object is unaffected.

To retrieve the actual features:

// By iterating:
for(Feature hotel : hotelsInParis)
{
    std::cout << hotel["name"] << std::endl;
}
 
// As a vector:
std::vector<Feature> hotelList = hotelsInParis;
 
// The one and only:
Feature paris = world("a[boundary=administrative]"
     "[admin_level=8][name=Paris]").one();
 
// The first (if any):
std::optional<Feature> anyHotel = hotels.first();

Features has three subclasses: Nodes, Ways and Relations, which contain only Node, Way and Relation objects. Assigning a Features object to a subclass object implicitly filters the collection by type (Assigning a subtype to an incompatible type results in an empty collection):

Features world("world");
 
Relations busRoutes =                  // Only relations that
    world("[type=route][route=bus]");  // are tagged as bus routes
 
Nodes nodes = busRoutes;               // empty collection

When the last Features object referring to a FeatureStore is destroyed, the associated Geographic Object Library is automatically closed, and all resources managed by the FeatureStore are released. (This differs from GeoDesk for Java, which requires GOLs to be closed explicitly).

Important: After a GOL has been closed, any Feature objects obtained from it become invalid. Calling their methods results in undefined behavior. This restriction also applies to related types, such as Tags, Tag, TagValue and StringValue.

Constructor & Destructor Documentation

Features() [1/2]

geodesk::Features::Features

(

const char *

golFile

)

Creates a collection that contains all features in the given Geographic Object Library.

Parameters

golFile

path of the GOL (.gol extension may be omitted)

Features() [2/2]

geodesk::Features::Features

(

const Features &

other

)

Creates a collection with all the features in the other collection.

Member Function Documentation

addTo() [1/2]

void geodesk::Features::addTo

(

std::vector< Feature > &

features

)

const

Appends the Feature objects in this collection to the given std::vector.

addTo() [2/2]

void geodesk::Features::addTo

(

std::vector< FeaturePtr > &

features

)

const

Appends the Feature objects in this collection to the given std::vector as FeaturePtr pointers.

area()

double geodesk::Features::area

(

)

const

Computes the total area (in square meters) of the features in this collection.

Exceptions

QueryException

if one or more tiles that contain the geometry of a Relation are missing

connectedTo()

Features geodesk::Features::connectedTo

(

const Feature &

feature

)

const

Only features that share a common node with the given Feature.

containing() [1/2]

Features geodesk::Features::containing

(

const Feature &

feature

)

const

Only features whose geometry contains the given Feature.

Exceptions

QueryException

if one or more tiles that contain the geometry of a Relation are missing

containing() [2/2]

Features geodesk::Features::containing

(

Coordinate

xy

)

const

Only features whose geometry contains the given Coordinate.

containingLonLat()

Features geodesk::Features::containingLonLat	(	double	lon,
		double	lat ) const

Only features whose geometry contains the given location.

Parameters

lon	degrees longitude
lat	degrees latitude

contains()

bool geodesk::Features::contains

(

const Feature &

feature

)

const

Checks if the specified Feature exists in this collection.

count()

uint64_t geodesk::Features::count

(

)

const

Returns the total number of features in this collection.

crossing()

Features geodesk::Features::crossing

(

const Feature &

feature

)

const

Only features whose geometry crosses the given Feature.

Exceptions

QueryException

if one or more tiles that contain the geometry of a Relation are missing

filter()

template<typename Predicate >

Features geodesk::Features::filter

(

Predicate

predicate

)

const

Only features that match the given predicate.

Parameters

predicate

A callable object (e.g., lambda, function pointer, or functor) that defines the filtering logic. The callable must accept a Feature and return a bool.

Important: The provided predicate must be thread-safe, as it may be invoked concurrently.

// Find all parks whose area is at least 1 km²
// (one million square meters)
 
Features parks = world("a[leisure=park]");
Features largeParks = parks.filter([](Feature park)
    { return park.area() > 1'000'000; });

first()

std::optional< Feature > geodesk::Features::first

(

)

const

Returns the first Feature in this collection, or std::nullopt if the collection is empty.

Only Nodes of a Way and member Features of a Relation are ordered; for all other collections, first() returns an arbitrary Feature.

Returns

the first Feature, or std::nullopt

intersecting()

Features geodesk::Features::intersecting

(

const Feature &

feature

)

const

Only features whose geometry intersects with the given Feature.

Exceptions

QueryException

if one or more tiles that contain the geometry of a Relation are missing

length()

double geodesk::Features::length

(

)

const

Computes the total length (in meters) of the features in this collection.

Exceptions

QueryException

if one or more tiles that contain the geometry of a Relation are missing

maxMetersFrom() [1/2]

Features geodesk::Features::maxMetersFrom	(	double	distance,
		Coordinate	xy ) const

Only features whose closest point lies within distance meters of xy.

Parameters

distance	the maximum distance (in meters)
xy	the center of the search radius

maxMetersFrom() [2/2]

Features geodesk::Features::maxMetersFrom	(	double	distance,
		double	lon,
		double	lat ) const

Only features whose closest point lies within distance meters of the given location.

Parameters

distance	the maximum distance (in meters)
lon	longitude of the search radius center
lat	latitude of the search radius center

membersOf()

Features geodesk::Features::membersOf

(

const Feature &

feature

)

const

Only features that belong to the given Relation.

nodes() [1/2]

Nodes geodesk::Features::nodes

(

)

const

Only nodes.

nodes() [2/2]

Nodes geodesk::Features::nodes

(

const char *

query

)

const

Only nodes that match the given query.

Parameters

query

a query in GOQL format

Exceptions

QueryException

if the query is malformed.

nodesOf()

Features geodesk::Features::nodesOf

(

const Feature &

feature

)

const

Only nodes that belong to the given Way.

one()

Feature geodesk::Features::one

(

)

const

Returns the one and only Feature in this collection.

Returns

the sole Feature

Exceptions

QueryException

if this collection is empty or contains more than one Feature

operator bool()

geodesk::Features::operator bool

(

)

const

Returns true if this collection contains at least one Feature.

operator!()

bool geodesk::Features::operator!

(

)

const

Returns true if this collection is empty.

operator()() [1/4]

Features geodesk::Features::operator()

(

const Box &

box

)

const

Only features whose bounding box intersects the given bounding box.

Parameters

box

operator()() [2/4]

Features geodesk::Features::operator()

(

const char *

query

)

const

Only features that match the given query.

Parameters

query

a query in GOQL format

Exceptions

QueryException

if the query is malformed.

operator()() [3/4]

Features geodesk::Features::operator()

(

const Feature &

feature

)

const

Only features whose geometry intersects with the given Feature (short form of intersecting())

operator()() [4/4]

Features geodesk::Features::operator()

(

Coordinate

xy

)

const

Only features whose bounding box contains the given Coordinate.

Parameters

xy

parentsOf()

Features geodesk::Features::parentsOf

(

const Feature &

feature

)

const

Only features that are parent relations of the given Feature (or parent ways of the given Node).

relations() [1/2]

Relations geodesk::Features::relations

(

)

const

Only relations.

relations() [2/2]

Relations geodesk::Features::relations

(

const char *

query

)

const

Only relations that match the given query.

Parameters

query

a query in GOQL format

Exceptions

QueryException

if the query is malformed.

store()

FeatureStore * geodesk::Features::store ( ) const

noexcept

Returns a pointer to the FeatureStore which contains the features in this collection.

ways() [1/2]

Ways geodesk::Features::ways

(

)

const

Only ways.

ways() [2/2]

Ways geodesk::Features::ways

(

const char *

query

)

const

Only ways that match the given query.

Parameters

query

a query in GOQL format

Exceptions

QueryException

if the query is malformed.

within()

Features geodesk::Features::within

(

const Feature &

feature

)

const

Only features that lie entirely inside the geometry of the given Feature.

Exceptions

QueryException

if one or more tiles that contain the geometry of a Relation are missing

---

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

• C:/dev/libgeodesk/include/geodesk/api/Features.h