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