1.. _rfc-50: 2 3======================================================================================= 4RFC 50: OGR field subtypes 5======================================================================================= 6 7Author: Even Rouault 8 9Contact: even dot rouault at spatialys dot com 10 11Status: Adopted, implemented in GDAL 2.0 12 13Summary 14------- 15 16This RFC aims at adding the capability of specifying sub-types to OGR 17fields, like boolean, 16 bit integers or 32 bit floating point values. 18The sub-type of a field definition is an additional attribute that 19specifies a hint or a restriction to the main type. The subtype can be 20used by applications and drivers that know how to handle it, and can 21generally be safely ignored by applications and drivers that do not. 22 23Core changes 24------------ 25 26Field subtypes 27~~~~~~~~~~~~~~ 28 29The OGRFieldSubType enumeration is added : 30 31:: 32 33 /** 34 * List of field subtypes. A subtype represents a hint, a restriction of the 35 * main type, that is not strictly necessary to consult. 36 * This list is likely to be extended in the 37 * future ... avoid coding applications based on the assumption that all 38 * field types can be known. 39 * Most subtypes only make sense for a restricted set of main types. 40 * @since GDAL 2.0 41 */ 42 typedef enum 43 { 44 /** No subtype. This is the default value */ OFSTNone = 0, 45 /** Boolean integer. Only valid for OFTInteger and OFTIntegerList.*/ 46 OFSTBoolean = 1, 47 /** Signed 16-bit integer. Only valid for OFTInteger and OFTIntegerList. */ 48 OFSTInt16 = 2, 49 /** Single precision (32 bit) floatint point. Only valid for OFTReal and OFTRealList. */ 50 OFSTFloat32 = 3, 51 OFSTMaxSubType = 3 52 } OGRFieldSubType; 53 54New attributes and methods 55~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 57- In OGRFieldDefn class : 58 59:: 60 61 OGRFieldSubType eSubType; 62 63 OGRFieldSubType GetSubType() { return eSubType; } 64 void SetSubType( OGRFieldSubType eSubTypeIn ); 65 static const char *GetFieldSubTypeName( OGRFieldSubType ); 66 67OGRFeature::SetField() will check that the passed value is in the 68accepted range for boolean and int16 subtypes. If not, it will emit a 69warning and correct/clamp the value to fit the subtype. 70 71C API changes 72~~~~~~~~~~~~~ 73 74Only additions : 75 76:: 77 78 OGRFieldSubType CPL_DLL OGR_Fld_GetSubType( OGRFieldDefnH ); 79 void CPL_DLL OGR_Fld_SetSubType( OGRFieldDefnH, OGRFieldSubType ); 80 const char CPL_DLL *OGR_GetFieldSubTypeName( OGRFieldSubType ); 81 int CPL_DLL OGR_AreTypeSubTypeCompatible( OGRFieldType eType, 82 OGRFieldSubType eSubType ); 83 84Changes in OGR SQL 85------------------ 86 87- Subtypes are preserved when a field name (or \*) is specified in the 88 list of fields of a SELECT 89- CAST(xxx AS BOOLEAN) and CAST(xxx AS SMALLINT) are now supported. 90- The field list of a SELECT can now accept boolean expressions, such 91 as "SELECT x IS NULL, x >= 5 FROM foo" 92- The WHERE clause of a SELECT can now accept boolean fields, such as 93 "SELECT \* FROM foo WHERE a_boolean_field" 94 95Changes in drivers 96------------------ 97 98- GeoJSON: can read/write OFSTBoolean 99- GML: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32 100- CSV: can read/write OFSTBoolean (explicitly with CSVT or with 101 autodetection), OFSTInt16 and OFSTFloat32 (explicitly with CSVT) 102- PG: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32 103- PGDump: can write OFSTBoolean, OFSTInt16 and OFSTFloat32 104- GeoPackage: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32 105- SQLite: can read/write OFSTBoolean and OFSTInt16 106- SQLite dialect: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32 107- FileGDB: can read/write OFSTInt16 and OFSTFloat32 108- OpenFileGDB: can read OFSTInt16 and OFSTFloat32 109- VRT: 'subtype' property added to be able to handle any subtype. 110 111Changes in utilities 112-------------------- 113 114- ogrinfo: the output of ogrinfo is slightly modified in presence of a 115 subtype. A field with a non-default subtype will be described as 116 "field_type(field_subtype)". For example 117 118:: 119 120 Had to open data source read-only. 121 INFO: Open of `out.gml' 122 using driver `GML' successful. 123 124 Layer name: test 125 Geometry: None 126 Feature Count: 2 127 Layer SRS WKT: 128 (unknown) 129 short: Integer(Int16) (0.0) 130 b: Integer(Boolean) (0.0) 131 OGRFeature(test):0 132 short (Integer(Int16)) = -32768 133 b (Integer(Boolean)) = 1 134 135Changes in SWIG bindings 136------------------------ 137 138Addition of : 139 140- ogr.OFSTNone, ogr.OFSTBoolean, ogr.OFSTInt16 and ogr.OFSTFloat32 141- ogr.GetFieldSubTypeName() 142- FieldDefn.GetSubType() 143- FieldDefn.SetSubType() 144 145Compatibility 146------------- 147 148This should have no impact on read-only operations done by applications. 149Update operations could be impacted if an out-of-range value for the 150subtype is written (but such a behavior probably already caused issues, 151either ignored or notified by the backend) 152 153Documentation 154------------- 155 156All new methods are documented. Driver documentation is updated when 157necessary. 158 159Testing 160------- 161 162The various aspects of this RFC are tested: 163 164- core changes 165- OGR SQL changes 166- driver changes 167 168Implementation 169-------------- 170 171Implementation will be done by Even Rouault 172(`Spatialys <http://spatialys.com>`__), and sponsored by 173`CartoDB <https://cartodb.com>`__. 174 175The proposed implementation lies in the "ogr_field_subtype" branch of 176the 177`https://github.com/rouault/gdal2/tree/ogr_field_subtype <https://github.com/rouault/gdal2/tree/ogr_field_subtype>`__ 178repository. 179 180The list of changes : 181`https://github.com/rouault/gdal2/compare/ogr_field_subtype <https://github.com/rouault/gdal2/compare/ogr_field_subtype>`__ 182 183Voting history 184-------------- 185 186+1 JukkaR, TamasS, FrankW and EvenR 187