GDAL

Public Member Functions | Static Public Member Functions | List of all members
OGRFieldDefn Class Reference

Definition of an attribute of an OGRFeatureDefn. More...

`#include <ogr_feature.h>`

## Public Member Functions
| OGRFieldDefn (const char *, OGRFieldType)
| Constructor.
| OGRFieldDefn (const OGRFieldDefn *)
| Constructor.
void | SetName (const char *)
| Reset the name of this field.
const char * | GetNameRef () const
| Fetch name of this field.
void | SetAlternativeName (const char *)
| Reset the alternative name (or "alias") for this field.
const char * | GetAlternativeNameRef () const
| Fetch the alternative name (or "alias") for this field.
OGRFieldType | GetType () const
| Fetch type of this field.
void | SetType (OGRFieldType eTypeIn)
| Set the type of this field.
OGRFieldSubType | GetSubType () const
| Fetch subtype of this field.
void | SetSubType (OGRFieldSubType eSubTypeIn)
| Set the subtype of this field.
OGRJustification | GetJustify () const
| Get the justification for this field.
void | SetJustify (OGRJustification eJustifyIn)
| Set the justification for this field.
int | GetWidth () const
| Get the formatting width for this field.
void | SetWidth (int nWidthIn)
| Set the formatting width for this field in characters.
int | GetPrecision () const
| Get the formatting precision for this field.
void | SetPrecision (int nPrecisionIn)
| Set the formatting precision for this field in characters.
int | GetTZFlag () const
| Get the time zone flag.
void | SetTZFlag (int nTZFlag)
| Set the time zone flag.
void | Set (const char *, OGRFieldType, int=0, int=0, OGRJustification=OJUndefined)
| Set defining parameters for a field in one call.
void | SetDefault (const char *)
| Set default field value.
const char * | GetDefault () const
| Get default field value.
int | IsDefaultDriverSpecific () const
| Returns whether the default value is driver specific.
int | IsIgnored () const
| Return whether this field should be omitted when fetching features.
void | SetIgnored (int bIgnoreIn)
| Set whether this field should be omitted when fetching features.
int | IsNullable () const
| Return whether this field can receive null values.
void | SetNullable (int bNullableIn)
| Set whether this field can receive null values.
int | IsUnique () const
| Return whether this field has a unique constraint.
void | SetUnique (int bUniqueIn)
| Set whether this field has a unique constraint.
const std::string & | GetDomainName () const
| Return the name of the field domain for this field.
void | SetDomainName (const std::string &osDomainName)
| Set the name of the field domain for this field.
const std::string & | GetComment () const
| Return the (optional) comment for this field.
void | SetComment (const std::string &osComment)
| Set the comment for this field.
int | IsSame (const OGRFieldDefn *) const
| Test if the field definition is identical to the other one.
void | Seal ()
| Seal a OGRFieldDefn.
void | Unseal ()
| Unseal a OGRFieldDefn.
TemporaryUnsealer | GetTemporaryUnsealer ()
| Return an object that temporary unseals the OGRFieldDefn.

## Static Public Member Functions
static const char * | GetFieldTypeName (OGRFieldType)
| Fetch human readable name for a field type.
static const char * | GetFieldSubTypeName (OGRFieldSubType)
| Fetch human readable name for a field subtype.
static OGRFieldDefnH | ToHandle (OGRFieldDefn *poFieldDefn)
| Convert a OGRFieldDefn* to a OGRFieldDefnH.
static OGRFieldDefn * | FromHandle (OGRFieldDefnH hFieldDefn)
| Convert a OGRFieldDefnH to a OGRFieldDefn*.

## Detailed Description

Definition of an attribute of an OGRFeatureDefn.

A field is described by :

- a name. See SetName() / GetNameRef()
- an alternative name (optional): alternative descriptive name for the field (sometimes referred to as an "alias"). See SetAlternativeName() / GetAlternativeNameRef()
- a type: OFTString, OFTInteger, OFTReal, ... See SetType() / GetType()
- a subtype (optional): OFSTBoolean, ... See SetSubType() / GetSubType()
- a width (optional): maximal number of characters. See SetWidth() / GetWidth()
- a precision (optional): number of digits after decimal point. See SetPrecision() / GetPrecision()
- a NOT NULL constraint (optional). See SetNullable() / IsNullable()
- a UNIQUE constraint (optional). See SetUnique() / IsUnique()
- a default value (optional). See SetDefault() / GetDefault()
- a boolean to indicate whether it should be ignored when retrieving features. See SetIgnored() / IsIgnored()
- a field domain name (optional). See SetDomainName() / Get DomainName()

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn().

## Constructor & Destructor Documentation

## ◆ OGRFieldDefn() [1/2]

OGRFieldDefn::OGRFieldDefn | ( | const char * | pszNameIn,
|  | OGRFieldType | eTypeIn
| ) |  |

Constructor.

By default, fields have no width, precision, are nullable and not ignored.

Parameters

  pszNameIn | the name of the new field.
  eTypeIn | the type of the new field.

## ◆ OGRFieldDefn() [2/2]

OGRFieldDefn::OGRFieldDefn | ( | const OGRFieldDefn * | poPrototype | ) |
| explicit

Constructor.

Create by cloning an existing field definition.

Parameters

  poPrototype | the field definition to clone.

## Member Function Documentation

## ◆ FromHandle()

static OGRFieldDefn * OGRFieldDefn::FromHandle | ( | OGRFieldDefnH | hFieldDefn | ) |
| inline static

Convert a OGRFieldDefnH to a OGRFieldDefn*.

Since
  GDAL 2.3

## ◆ GetAlternativeNameRef()

const char * OGRFieldDefn::GetAlternativeNameRef | ( |  | ) | const
| inline

Fetch the alternative name (or "alias") for this field.

The alternative name is an optional attribute for a field which can provide a more user-friendly, descriptive name of a field which is not subject to the usual naming constraints defined by the data provider.

This is a metadata style attribute only: the alternative name cannot be used in place of the actual field name during SQL queries or other field name dependent API calls.

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

Returns
  pointer to an internal alternative name string that should not be freed or modified.

Since
  GDAL 3.2

## ◆ GetComment()

const std::string & OGRFieldDefn::GetComment | ( |  | ) | const
| inline

Return the (optional) comment for this field.

By default, none (empty string) is returned.

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

Returns
  the field comment, or an empty string if there is none.

Since
  GDAL 3.7

## ◆ GetDefault()

const char * OGRFieldDefn::GetDefault | ( |  | ) | const

Get default field value.

This function is the same as the C function OGR_Fld_GetDefault().

Returns
  default field value or NULL.

Since
  GDAL 2.0

## ◆ GetDomainName()

const std::string & OGRFieldDefn::GetDomainName | ( |  | ) | const
| inline

Return the name of the field domain for this field.

By default, none (empty string) is returned.

Field domains (OGRFieldDomain class) are attached at the GDALDataset level and should be retrieved with GDALDataset::GetFieldDomain().

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

Returns
  the field domain name, or an empty string if there is none.

Since
  GDAL 3.3

## ◆ GetFieldSubTypeName()

const char * OGRFieldDefn::GetFieldSubTypeName | ( | OGRFieldSubType | eSubType | ) |
| static

Fetch human readable name for a field subtype.

This static method is the same as the C function OGR_GetFieldSubTypeName().

Parameters

  eSubType | the field subtype to get name for.

Returns
  pointer to an internal static name string. It should not be modified or freed.

Since
  GDAL 2.0

## ◆ GetFieldTypeName()

const char * OGRFieldDefn::GetFieldTypeName | ( | OGRFieldType | eType | ) |
| static

Fetch human readable name for a field type.

This static method is the same as the C function OGR_GetFieldTypeName().

Parameters

  eType | the field type to get name for.

Returns
  pointer to an internal static name string. It should not be modified or freed.

## ◆ GetJustify()

OGRJustification OGRFieldDefn::GetJustify | ( |  | ) | const
| inline

Get the justification for this field.

Note: no driver is know to use the concept of field justification.

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

Returns
  the justification.

## ◆ GetNameRef()

const char * OGRFieldDefn::GetNameRef | ( |  | ) | const
| inline

Fetch name of this field.

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

Returns
  pointer to an internal name string that should not be freed or modified.

## ◆ GetPrecision()

int OGRFieldDefn::GetPrecision | ( |  | ) | const
| inline

Get the formatting precision for this field.

This should normally be zero for fields of types other than OFTReal.

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

Returns
  the precision.

## ◆ GetSubType()

OGRFieldSubType OGRFieldDefn::GetSubType | ( |  | ) | const
| inline

Fetch subtype of this field.

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

Returns
  field subtype.

Since
  GDAL 2.0

## ◆ GetTemporaryUnsealer()

OGRFieldDefn::TemporaryUnsealer OGRFieldDefn::GetTemporaryUnsealer | ( |  | ) |

Return an object that temporary unseals the OGRFieldDefn.

The returned object calls Unseal() initially, and when it is destroyed it calls Seal().

This method should only be called by driver implementations.

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

Since
  GDAL 3.9

## ◆ GetType()

OGRFieldType OGRFieldDefn::GetType | ( |  | ) | const
| inline

Fetch type of this field.

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

Returns
  field type.

## ◆ GetTZFlag()

int OGRFieldDefn::GetTZFlag | ( |  | ) | const
| inline

Get the time zone flag.

Only applies to OFTTime, OFTDate and OFTDateTime fields.

Cf OGR_TZFLAG_UNKNOWN, OGR_TZFLAG_LOCALTIME, OGR_TZFLAG_MIXED_TZ and OGR_TZFLAG_UTC

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

Returns
  the time zone flag.

Since
  GDAL 3.8

## ◆ GetWidth()

int OGRFieldDefn::GetWidth | ( |  | ) | const
| inline

Get the formatting width for this field.

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

Returns
  the width, zero means no specified width.

## ◆ IsDefaultDriverSpecific()

int OGRFieldDefn::IsDefaultDriverSpecific | ( |  | ) | const

Returns whether the default value is driver specific.

Driver specific default values are those that are not NULL, a numeric value, a literal value enclosed between single quote characters, CURRENT_TIMESTAMP, CURRENT_TIME, CURRENT_DATE or datetime literal value.

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

Returns
  TRUE if the default value is driver specific.

Since
  GDAL 2.0

## ◆ IsIgnored()

int OGRFieldDefn::IsIgnored | ( |  | ) | const
| inline

Return whether this field should be omitted when fetching features.

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

Returns
  ignore state

## ◆ IsNullable()

int OGRFieldDefn::IsNullable | ( |  | ) | const
| inline

Return whether this field can receive null values.

By default, fields are nullable.

Even if this method returns FALSE (i.e not-nullable field), it doesn't mean that OGRFeature::IsFieldSet() will necessary return TRUE, as fields can be temporary unset and null/not-null validation is usually done when OGRLayer::CreateFeature()/SetFeature() is called.

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

Returns
  TRUE if the field is authorized to be null.

Since
  GDAL 2.0

## ◆ IsSame()

int OGRFieldDefn::IsSame | ( | const OGRFieldDefn * | poOtherFieldDefn | ) | const

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

Parameters

  poOtherFieldDefn | the other field definition to compare to.

Returns
  TRUE if the field definition is identical to the other one.

## ◆ IsUnique()

int OGRFieldDefn::IsUnique | ( |  | ) | const
| inline

Return whether this field has a unique constraint.

By default, fields have no unique constraint.

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

Returns
  TRUE if the field has a unique constraint.

Since
  GDAL 3.2

## ◆ Seal()

void OGRFieldDefn::Seal | ( |  | ) |

Seal a OGRFieldDefn.

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

This method should only be called by driver implementations.

Since
  GDAL 3.9

## ◆ Set()

void OGRFieldDefn::Set | ( | const char * | pszNameIn,
|  | OGRFieldType | eTypeIn,
|  | int | nWidthIn = `0`,
|  | int | nPrecisionIn = `0`,
|  | OGRJustification | eJustifyIn = `OJUndefined`
| ) |  |

Set defining parameters for a field in one call.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  pszNameIn | the new name to assign.
  eTypeIn | the new type (one of the OFT values like OFTInteger).
  nWidthIn | the preferred formatting width. Defaults to zero indicating undefined.
  nPrecisionIn | number of decimals places for formatting, defaults to zero indicating undefined.
  eJustifyIn | the formatting justification (OJLeft or OJRight), defaults to OJUndefined.

## ◆ SetAlternativeName()

void OGRFieldDefn::SetAlternativeName | ( | const char * | pszAlternativeNameIn | ) |

Reset the alternative name (or "alias") for this field.

The alternative name is an optional attribute for a field which can provide a more user-friendly, descriptive name of a field which is not subject to the usual naming constraints defined by the data provider.

This is a metadata style attribute only: the alternative name cannot be used in place of the actual field name during SQL queries or other field name dependent API calls.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  pszAlternativeNameIn | the new alternative name to apply.

Since
  GDAL 3.2

## ◆ SetComment()

void OGRFieldDefn::SetComment | ( | const std::string & | osComment | ) |

Set the comment for this field.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn().

Parameters

  osComment | Field comment.

Since
  GDAL 3.7

## ◆ SetDefault()

void OGRFieldDefn::SetDefault | ( | const char * | pszDefaultIn | ) |

Set default field value.

The default field value is taken into account by drivers (generally those with a SQL interface) that support it at field creation time. OGR will generally not automatically set the default field value to null fields by itself when calling OGRFeature::CreateFeature() / OGRFeature::SetFeature(), but will let the low-level layers to do the job. So retrieving the feature from the layer is recommended.

The accepted values are NULL, a numeric value, a literal value enclosed between single quote characters (and inner single quote characters escaped by repetition of the single quote character), CURRENT_TIMESTAMP, CURRENT_TIME, CURRENT_DATE or a driver specific expression (that might be ignored by other drivers). For a datetime literal value, format should be 'YYYY/MM/DD HH:MM:SS[.sss]' (considered as UTC time).

Drivers that support writing DEFAULT clauses will advertise the GDAL_DCAP_DEFAULT_FIELDS driver metadata item.

This function is the same as the C function OGR_Fld_SetDefault().

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  pszDefaultIn | new default field value or NULL pointer.

Since
  GDAL 2.0

## ◆ SetDomainName()

void OGRFieldDefn::SetDomainName | ( | const std::string & | osDomainName | ) |

Set the name of the field domain for this field.

Field domains (OGRFieldDomain) are attached at the GDALDataset level.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn().

Parameters

  osDomainName | Field domain name.

Since
  GDAL 3.3

## ◆ SetIgnored()

void OGRFieldDefn::SetIgnored | ( | int | ignore | ) |
| inline

Set whether this field should be omitted when fetching features.

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

This method should not be called on a object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, the OGRLayer::SetIgnoredFields() method should be called.

Parameters

  ignore | ignore state

## ◆ SetJustify()

void OGRFieldDefn::SetJustify | ( | OGRJustification | eJustify | ) |
| inline

Set the justification for this field.

Note: no driver is know to use the concept of field justification.

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

Parameters

  eJustify | the new justification.

## ◆ SetName()

void OGRFieldDefn::SetName | ( | const char * | pszNameIn | ) |

Reset the name of this field.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  pszNameIn | the new name to apply.

## ◆ SetNullable()

void OGRFieldDefn::SetNullable | ( | int | bNullableIn | ) |

Set whether this field can receive null values.

By default, fields are nullable, so this method is generally called with FALSE to set a not-null constraint.

Drivers that support writing not-null constraint will advertise the GDAL_DCAP_NOTNULL_FIELDS driver metadata item.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn().

Parameters

  bNullableIn | FALSE if the field must have a not-null constraint.

Since
  GDAL 2.0

## ◆ SetPrecision()

void OGRFieldDefn::SetPrecision | ( | int | nPrecisionIn | ) |

Set the formatting precision for this field in characters.

This should normally be zero for fields of types other than OFTReal.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  nPrecisionIn | the new precision.

## ◆ SetSubType()

void OGRFieldDefn::SetSubType | ( | OGRFieldSubType | eSubTypeIn | ) |

Set the subtype of this field.

This should never be done to an OGRFieldDefn that is already part of an OGRFeatureDefn.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  eSubTypeIn | the new field subtype.

Since
  GDAL 2.0

## ◆ SetType()

void OGRFieldDefn::SetType | ( | OGRFieldType | eTypeIn | ) |

Set the type of this field.

This should never be done to an OGRFieldDefn that is already part of an OGRFeatureDefn.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  eTypeIn | the new field type.

## ◆ SetTZFlag()

void OGRFieldDefn::SetTZFlag | ( | int | nTZFlag | ) |

Set the time zone flag.

Only applies to OFTTime, OFTDate and OFTDateTime fields.

Cf OGR_TZFLAG_UNKNOWN, OGR_TZFLAG_LOCALTIME, OGR_TZFLAG_MIXED_TZ and OGR_TZFLAG_UTC

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  nTZFlag | the new time zone flag.

Since
  GDAL 3.8

## ◆ SetUnique()

void OGRFieldDefn::SetUnique | ( | int | bUniqueIn | ) |

Set whether this field has a unique constraint.

By default, fields have no unique constraint, so this method is generally called with TRUE to set a unique constraint.

Drivers that support writing unique constraint will advertise the GDAL_DCAP_UNIQUE_FIELDS driver metadata item.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn().

Parameters

  bUniqueIn | TRUE if the field must have a unique constraint.

Since
  GDAL 3.2

## ◆ SetWidth()

void OGRFieldDefn::SetWidth | ( | int | nWidthIn | ) |

Set the formatting width for this field in characters.

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

Note that once a OGRFieldDefn has been added to a layer definition with OGRLayer::AddFieldDefn(), its setter methods should not be called on the object returned with OGRLayer::GetLayerDefn()->GetFieldDefn(). Instead, OGRLayer::AlterFieldDefn() should be called on a new instance of OGRFieldDefn, for drivers that support AlterFieldDefn.

Parameters

  nWidthIn | the new width.

## ◆ ToHandle()

static OGRFieldDefnH OGRFieldDefn::ToHandle | ( | OGRFieldDefn * | poFieldDefn | ) |
| inline static

Convert a OGRFieldDefn* to a OGRFieldDefnH.

Since
  GDAL 2.3

## ◆ Unseal()

void OGRFieldDefn::Unseal | ( |  | ) |

Unseal a OGRFieldDefn.

Undo OGRFieldDefn::Seal()

Using GetTemporaryUnsealer() is recommended for most use cases.

This method should only be called by driver implementations.

Since
  GDAL 3.9

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

- ogr_feature.h
- ogrfielddefn.cpp