GDAL
Public Member Functions | Static Public Member Functions | List of all members
OGRFeatureDefn Class Reference

Definition of a feature class or feature layer. More...

#include <ogr_feature.h>

Public Member Functions

 OGRFeatureDefn (const char *pszName=nullptr)
 Constructor. More...
 
void SetName (const char *pszName)
 Change name of this OGRFeatureDefn. More...
 
virtual const char * GetName () const
 Get name of this OGRFeatureDefn. More...
 
virtual int GetFieldCount () const
 Fetch number of fields on this feature. More...
 
virtual OGRFieldDefnGetFieldDefn (int i)
 Fetch field definition. More...
 
virtual const OGRFieldDefnGetFieldDefn (int i) const
 Fetch field definition. More...
 
virtual int GetFieldIndex (const char *) const
 Find field by name. More...
 
int GetFieldIndexCaseSensitive (const char *) const
 Find field by name, in a case sensitive way. More...
 
Fields GetFields ()
 Return an object that can be used to iterate over non-geometry fields. More...
 
virtual void AddFieldDefn (const OGRFieldDefn *)
 Add a new field definition. More...
 
virtual OGRErr DeleteFieldDefn (int iField)
 Delete an existing field definition. More...
 
virtual OGRErr ReorderFieldDefns (const int *panMap)
 Reorder the field definitions in the array of the feature definition. More...
 
virtual int GetGeomFieldCount () const
 Fetch number of geometry fields on this feature. More...
 
virtual OGRGeomFieldDefnGetGeomFieldDefn (int i)
 Fetch geometry field definition. More...
 
virtual const OGRGeomFieldDefnGetGeomFieldDefn (int i) const
 Fetch geometry field definition. More...
 
virtual int GetGeomFieldIndex (const char *) const
 Find geometry field by name. More...
 
GeomFields GetGeomFields ()
 Return an object that can be used to iterate over geometry fields. More...
 
virtual void AddGeomFieldDefn (const OGRGeomFieldDefn *)
 Add a new geometry field definition. More...
 
virtual void AddGeomFieldDefn (std::unique_ptr< OGRGeomFieldDefn > &&)
 Add a new geometry field definition. More...
 
virtual OGRErr DeleteGeomFieldDefn (int iGeomField)
 Delete an existing geometry field definition. More...
 
virtual OGRwkbGeometryType GetGeomType () const
 Fetch the geometry base type. More...
 
virtual void SetGeomType (OGRwkbGeometryType)
 Assign the base geometry type for this layer. More...
 
virtual OGRFeatureDefnClone () const
 Create a copy of this feature definition. More...
 
int Reference ()
 Increments the reference count by one. More...
 
int Dereference ()
 Decrements the reference count by one. More...
 
int GetReferenceCount () const
 Fetch current reference count. More...
 
void Release ()
 Drop a reference to this object, and destroy if no longer referenced.
 
virtual int IsGeometryIgnored () const
 Determine whether the geometry can be omitted when fetching features. More...
 
virtual void SetGeometryIgnored (int bIgnore)
 Set whether the geometry can be omitted when fetching features. More...
 
virtual bool IsStyleIgnored () const
 Determine whether the style can be omitted when fetching features. More...
 
virtual void SetStyleIgnored (bool bIgnore)
 Set whether the style can be omitted when fetching features. More...
 
virtual int IsSame (const OGRFeatureDefn *poOtherFeatureDefn) const
 Test if the feature definition is identical to the other one. More...
 
std::vector< int > ComputeMapForSetFrom (const OGRFeatureDefn *poSrcFDefn, bool bForgiving=true) const
 Compute the map from source to target field that can be passed to SetFrom(). More...
 
void Seal (bool bSealFields)
 Seal a OGRFeatureDefn. More...
 
void Unseal (bool bUnsealFields)
 Unseal a OGRFeatureDefn. More...
 
TemporaryUnsealer GetTemporaryUnsealer (bool bSealFields=true)
 Return an object that temporary unseals the OGRFeatureDefn. More...
 

Static Public Member Functions

static OGRFeatureDefnCreateFeatureDefn (const char *pszName=nullptr)
 Create a new feature definition object. More...
 
static void DestroyFeatureDefn (OGRFeatureDefn *)
 Destroy a feature definition. More...
 
static OGRFeatureDefnH ToHandle (OGRFeatureDefn *poFeatureDefn)
 Convert a OGRFeatureDefn* to a OGRFeatureDefnH. More...
 
static OGRFeatureDefnFromHandle (OGRFeatureDefnH hFeatureDefn)
 Convert a OGRFeatureDefnH to a OGRFeatureDefn*. More...
 

Detailed Description

Definition of a feature class or feature layer.

This object contains schema information for a set of OGRFeatures. In table based systems, an OGRFeatureDefn is essentially a layer. In more object oriented approaches (such as SF CORBA) this can represent a class of features but doesn't necessarily relate to all of a layer, or just one layer.

This object also can contain some other information such as a name and potentially other metadata.

It is essentially a collection of field descriptions (OGRFieldDefn class). Starting with GDAL 1.11, in addition to attribute fields, it can also contain multiple geometry fields (OGRGeomFieldDefn class).

It is reasonable for different translators to derive classes from OGRFeatureDefn with additional translator specific information.

Note that adding, modifying, removing, reordering a OGRFieldDefn (or a OGRGeomFieldDefn) from/to a OGRFeatureDefn that belongs to a OGRLayer should not be done through the OGRFeatureDefn::AddFieldDefn(), OGRFeatureDefn::DeleteFieldDefn() or OGRFeatureDefn::ReorderFieldDefns() methods, but rather through OGRLayer::CreateField(), OGRLayer::AlterFieldDefn() or OGRLayer::ReorderFields(), for drivers that support those operations.

Constructor & Destructor Documentation

◆ OGRFeatureDefn()

OGRFeatureDefn::OGRFeatureDefn ( const char *  pszName = nullptr)
explicit

Constructor.

The OGRFeatureDefn maintains a reference count, but this starts at zero. It is mainly intended to represent a count of OGRFeature's based on this definition.

This method is the same as the C function OGR_FD_Create().

Parameters
pszNamethe name to be assigned to this layer/class. It does not need to be unique.

Member Function Documentation

◆ AddFieldDefn()

void OGRFeatureDefn::AddFieldDefn ( const OGRFieldDefn poNewDefn)
virtual

Add a new field definition.

To add a new field definition to a layer definition, do not use this function directly, but use OGRLayer::CreateField() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn. The OGRFieldDefn passed in is copied, and remains the responsibility of the caller.

This method is the same as the C function OGR_FD_AddFieldDefn().

Parameters
poNewDefnthe definition of the new field.

◆ AddGeomFieldDefn() [1/2]

void OGRFeatureDefn::AddGeomFieldDefn ( const OGRGeomFieldDefn poNewDefn)
virtual

Add a new geometry field definition.

To add a new geometry field definition to a layer definition, do not use this function directly, but use OGRLayer::CreateGeomField() instead.

This method does an internal copy of the passed geometry field definition, unless bCopy is set to FALSE (in which case it takes ownership of the field definition.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn. The OGRGeomFieldDefn passed in is copied, and remains the responsibility of the caller.

This method is the same as the C function OGR_FD_AddGeomFieldDefn().

Parameters
poNewDefnthe definition of the new geometry field.
Since
GDAL 1.11

◆ AddGeomFieldDefn() [2/2]

void OGRFeatureDefn::AddGeomFieldDefn ( std::unique_ptr< OGRGeomFieldDefn > &&  poNewDefn)
virtual

Add a new geometry field definition.

To add a new geometry field definition to a layer definition, do not use this function directly, but use OGRLayer::CreateGeomField() instead.

This method takes ownership of the passed geometry field definition.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

Parameters
poNewDefnthe definition of the new geometry field.
Since
GDAL 3.4

◆ Clone()

OGRFeatureDefn * OGRFeatureDefn::Clone ( ) const
virtual

Create a copy of this feature definition.

Creates a deep copy of the feature definition.

Returns
the copy.

◆ ComputeMapForSetFrom()

std::vector< int > OGRFeatureDefn::ComputeMapForSetFrom ( const OGRFeatureDefn poSrcFDefn,
bool  bForgiving = true 
) const

Compute the map from source to target field that can be passed to SetFrom().

Parameters
poSrcFDefnthe feature definition of source features later passed to SetFrom()
bForgivingtrue if the operation should continue despite lacking output fields matching some of the source fields.
Returns
an array of size poSrcFDefn->GetFieldCount() if everything succeeds, or empty in case a source field definition was not found in the target layer and bForgiving == true.
Since
GDAL 2.3

◆ CreateFeatureDefn()

OGRFeatureDefn * OGRFeatureDefn::CreateFeatureDefn ( const char *  pszName = nullptr)
static

Create a new feature definition object.

Parameters
pszNamename
Returns
new feature definition object.

◆ DeleteFieldDefn()

OGRErr OGRFeatureDefn::DeleteFieldDefn ( int  iField)
virtual

Delete an existing field definition.

To delete an existing field definition from a layer definition, do not use this function directly, but use OGRLayer::DeleteField() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

This method is the same as the C function OGR_FD_DeleteFieldDefn().

Parameters
iFieldthe index of the field definition.
Returns
OGRERR_NONE in case of success.
Since
OGR 1.9.0

◆ DeleteGeomFieldDefn()

OGRErr OGRFeatureDefn::DeleteGeomFieldDefn ( int  iGeomField)
virtual

Delete an existing geometry field definition.

To delete an existing field definition from a layer definition, do not use this function directly, but use OGRLayer::DeleteGeomField() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

This method is the same as the C function OGR_FD_DeleteGeomFieldDefn().

Parameters
iGeomFieldthe index of the geometry field definition.
Returns
OGRERR_NONE in case of success.
Since
GDAL 1.11

◆ Dereference()

int OGRFeatureDefn::Dereference ( )
inline

Decrements the reference count by one.

This method is the same as the C function OGR_FD_Dereference().

Returns
the updated reference count.

◆ DestroyFeatureDefn()

void OGRFeatureDefn::DestroyFeatureDefn ( OGRFeatureDefn poDefn)
static

Destroy a feature definition.

Parameters
poDefnfeature definition.

◆ FromHandle()

static OGRFeatureDefn * OGRFeatureDefn::FromHandle ( OGRFeatureDefnH  hFeatureDefn)
inlinestatic

Convert a OGRFeatureDefnH to a OGRFeatureDefn*.

Since
GDAL 2.3

◆ GetFieldCount()

int OGRFeatureDefn::GetFieldCount ( ) const
virtual

Fetch number of fields on this feature.

This method is the same as the C function OGR_FD_GetFieldCount().

Returns
count of fields.

◆ GetFieldDefn() [1/2]

OGRFieldDefn * OGRFeatureDefn::GetFieldDefn ( int  iField)
virtual

Fetch field definition.

This method is the same as the C function OGR_FD_GetFieldDefn().

Parameters
iFieldthe field to fetch, between 0 and GetFieldCount() - 1.
Returns
a pointer to an internal field definition object or NULL if invalid index. This object should not be modified or freed by the application.

◆ GetFieldDefn() [2/2]

const OGRFieldDefn * OGRFeatureDefn::GetFieldDefn ( int  iField) const
virtual

Fetch field definition.

This method is the same as the C function OGR_FD_GetFieldDefn().

Parameters
iFieldthe field to fetch, between 0 and GetFieldCount() - 1.
Returns
a pointer to an internal field definition object or NULL if invalid index. This object should not be modified or freed by the application.
Since
GDAL 2.3

◆ GetFieldIndex()

int OGRFeatureDefn::GetFieldIndex ( const char *  pszFieldName) const
virtual

Find field by name.

The field index of the first field matching the passed field name (case insensitively) is returned.

This method is the same as the C function OGR_FD_GetFieldIndex().

Parameters
pszFieldNamethe field name to search for.
Returns
the field index, or -1 if no match found.

◆ GetFieldIndexCaseSensitive()

int OGRFeatureDefn::GetFieldIndexCaseSensitive ( const char *  pszFieldName) const

Find field by name, in a case sensitive way.

The field index of the first field matching the passed field name is returned.

Parameters
pszFieldNamethe field name to search for.
Returns
the field index, or -1 if no match found.

◆ GetFields()

Fields OGRFeatureDefn::GetFields ( )
inline

Return an object that can be used to iterate over non-geometry fields.

for( const auto* poFieldDefn: poFeatureDefn->GetFields() )
{
    // do something
}
Since
GDAL 3.7

◆ GetGeomFieldCount()

int OGRFeatureDefn::GetGeomFieldCount ( ) const
virtual

Fetch number of geometry fields on this feature.

This method is the same as the C function OGR_FD_GetGeomFieldCount().

Returns
count of geometry fields.
Since
GDAL 1.11

◆ GetGeomFieldDefn() [1/2]

OGRGeomFieldDefn * OGRFeatureDefn::GetGeomFieldDefn ( int  iGeomField)
virtual

Fetch geometry field definition.

This method is the same as the C function OGR_FD_GetGeomFieldDefn().

Parameters
iGeomFieldthe geometry field to fetch, between 0 and GetGeomFieldCount() - 1.
Returns
a pointer to an internal field definition object or NULL if invalid index. This object should not be modified or freed by the application.
Since
GDAL 1.11

◆ GetGeomFieldDefn() [2/2]

const OGRGeomFieldDefn * OGRFeatureDefn::GetGeomFieldDefn ( int  iGeomField) const
virtual

Fetch geometry field definition.

This method is the same as the C function OGR_FD_GetGeomFieldDefn().

Parameters
iGeomFieldthe geometry field to fetch, between 0 and GetGeomFieldCount() - 1.
Returns
a pointer to an internal field definition object or NULL if invalid index. This object should not be modified or freed by the application.
Since
GDAL 2.3

◆ GetGeomFieldIndex()

int OGRFeatureDefn::GetGeomFieldIndex ( const char *  pszGeomFieldName) const
virtual

Find geometry field by name.

The geometry field index of the first geometry field matching the passed field name (case insensitively) is returned.

This method is the same as the C function OGR_FD_GetGeomFieldIndex().

Parameters
pszGeomFieldNamethe geometry field name to search for.
Returns
the geometry field index, or -1 if no match found.

◆ GetGeomFields()

GeomFields OGRFeatureDefn::GetGeomFields ( )
inline

Return an object that can be used to iterate over geometry fields.

for( const auto* poGeomFieldDefn: poFeatureDefn->GetGeomFields() )
{
    // do something
}
Since
GDAL 3.7

◆ GetGeomType()

OGRwkbGeometryType OGRFeatureDefn::GetGeomType ( ) const
virtual

Fetch the geometry base type.

Note that some drivers are unable to determine a specific geometry type for a layer, in which case wkbUnknown is returned. A value of wkbNone indicates no geometry is available for the layer at all. Many drivers do not properly mark the geometry type as 25D even if some or all geometries are in fact 25D. A few (broken) drivers return wkbPolygon for layers that also include wkbMultiPolygon.

Starting with GDAL 1.11, this method returns GetGeomFieldDefn(0)->GetType().

This method is the same as the C function OGR_FD_GetGeomType().

Returns
the base type for all geometry related to this definition.

◆ GetName()

const char * OGRFeatureDefn::GetName ( ) const
virtual

Get name of this OGRFeatureDefn.

This method is the same as the C function OGR_FD_GetName().

Returns
the name. This name is internal and should not be modified, or freed.

◆ GetReferenceCount()

int OGRFeatureDefn::GetReferenceCount ( ) const
inline

Fetch current reference count.

This method is the same as the C function OGR_FD_GetReferenceCount().

Returns
the current reference count.

◆ GetTemporaryUnsealer()

OGRFeatureDefn::TemporaryUnsealer OGRFeatureDefn::GetTemporaryUnsealer ( bool  bSealFields = true)

Return an object that temporary unseals the OGRFeatureDefn.

The returned object calls Unseal() initially, and when it is destroyed it calls Seal(). This method should be called on a OGRFeatureDefn that has been sealed previously. GetTemporaryUnsealer() calls may be nested, in which case only the first one has an effect (similarly to a recursive mutex locked in a nested way from the same thread).

This method should only be called by driver implementations.

It is also possible to use the helper method whileUnsealing(). Example: whileUnsealing(poFeatureDefn)->some_method()

Parameters
bSealFieldsWhether fields and geometry fields should be unsealed and resealed. This is generally desirabled, but in case of deferred resolution of them, this parameter should be set to false.
Since
GDAL 3.9

◆ IsGeometryIgnored()

int OGRFeatureDefn::IsGeometryIgnored ( ) const
virtual

Determine whether the geometry can be omitted when fetching features.

This method is the same as the C function OGR_FD_IsGeometryIgnored().

Starting with GDAL 1.11, this method returns GetGeomFieldDefn(0)->IsIgnored().

Returns
ignore state

◆ IsSame()

int OGRFeatureDefn::IsSame ( const OGRFeatureDefn poOtherFeatureDefn) const
virtual

Test if the feature definition is identical to the other one.

Parameters
poOtherFeatureDefnthe other feature definition to compare to.
Returns
TRUE if the feature definition is identical to the other one.

◆ IsStyleIgnored()

int OGRFeatureDefn::IsStyleIgnored ( ) const
inlinevirtual

Determine whether the style can be omitted when fetching features.

This method is the same as the C function OGR_FD_IsStyleIgnored().

Returns
ignore state

◆ Reference()

int OGRFeatureDefn::Reference ( )
inline

Increments the reference count by one.

The reference count is used keep track of the number of OGRFeature objects referencing this definition.

This method is the same as the C function OGR_FD_Reference().

Returns
the updated reference count.

◆ ReorderFieldDefns()

OGRErr OGRFeatureDefn::ReorderFieldDefns ( const int *  panMap)
virtual

Reorder the field definitions in the array of the feature definition.

To reorder the field definitions in a layer definition, do not use this function directly, but use OGR_L_ReorderFields() instead.

This method should only be called while there are no OGRFeature objects in existence based on this OGRFeatureDefn.

This method is the same as the C function OGR_FD_ReorderFieldDefns().

Parameters
panMapan array of GetFieldCount() elements which is a permutation of [0, GetFieldCount()-1]. panMap is such that, for each field definition at position i after reordering, its position before reordering was panMap[i].
Returns
OGRERR_NONE in case of success.
Since
OGR 1.9.0

◆ Seal()

void OGRFeatureDefn::Seal ( bool  bSealFields)

Seal a OGRFeatureDefn.

A sealed OGRFeatureDefn can not be modified while it is sealed.

This method also call OGRFieldDefn::Seal() and OGRGeomFieldDefn::Seal() on its fields and geometry fields.

This method should only be called by driver implementations.

Parameters
bSealFieldsWhether fields and geometry fields should be sealed. This is generally desirabled, but in case of deferred resolution of them, this parameter should be set to false.
Since
GDAL 3.9

◆ SetGeometryIgnored()

void OGRFeatureDefn::SetGeometryIgnored ( int  bIgnore)
virtual

Set whether the geometry can be omitted when fetching features.

This method is the same as the C function OGR_FD_SetGeometryIgnored().

Starting with GDAL 1.11, this method calls GetGeomFieldDefn(0)->SetIgnored().

Parameters
bIgnoreignore state

◆ SetGeomType()

void OGRFeatureDefn::SetGeomType ( OGRwkbGeometryType  eNewType)
virtual

Assign the base geometry type for this layer.

All geometry objects using this type must be of the defined type or a derived type. The default upon creation is wkbUnknown which allows for any geometry type. The geometry type should generally not be changed after any OGRFeatures have been created against this definition.

This method is the same as the C function OGR_FD_SetGeomType().

Starting with GDAL 1.11, this method calls GetGeomFieldDefn(0)->SetType().

Parameters
eNewTypethe new type to assign.

◆ SetName()

void OGRFeatureDefn::SetName ( const char *  pszName)

Change name of this OGRFeatureDefn.

To rename a layer, do not use this function directly, but use OGRLayer::Rename() instead.

Parameters
pszNamefeature definition name
Since
GDAL 2.3

◆ SetStyleIgnored()

void OGRFeatureDefn::SetStyleIgnored ( bool  bIgnore)
inlinevirtual

Set whether the style can be omitted when fetching features.

This method is the same as the C function OGR_FD_SetStyleIgnored().

Parameters
bIgnoreignore state

◆ ToHandle()

static OGRFeatureDefnH OGRFeatureDefn::ToHandle ( OGRFeatureDefn poFeatureDefn)
inlinestatic

Convert a OGRFeatureDefn* to a OGRFeatureDefnH.

Since
GDAL 2.3

◆ Unseal()

void OGRFeatureDefn::Unseal ( bool  bUnsealFields)

Unseal a OGRFeatureDefn.

Undo OGRFeatureDefn::Seal()

This method also call OGRFieldDefn::Unseal() and OGRGeomFieldDefn::Unseal() on its fields and geometry fields.

Using GetTemporaryUnsealer() is recommended for most use cases.

This method should only be called by driver implementations.

Parameters
bUnsealFieldsWhether fields and geometry fields should be unsealed. This is generally desirabled, but in case of deferred resolution of them, this parameter should be set to false.
Since
GDAL 3.9

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