Changes between Initial Version and Version 1 of rfc50_ogr_field_subtype

Timestamp:

Nov 19, 2014, 2:08:10 PM (10 years ago)

Author:

Even Rouault

Comment:

Initial version of RFC 50

rfc50_ogr_field_subtype

@@ +1 @@
+= RFC 50: OGR field subtypes =
+
+Author: Even Rouault[[BR]]
+Contact: even dot rouault at spatialys dot com[[BR]]
+Status: In development
+
+== Summary ==
+
+This RFC aims at adding the capability of specifying sub-types to OGR fields,
+like boolean, 16 bit integers or 32 bit floating point values.
+The sub-type of a field definition is an additional
+attribute that specifies a hint or a restriction to the main type. The subtype
+can be used by applications and drivers that know how to handle it, and
+can generally be safely ignored by applications and drivers that do not.
+
+== Core changes ==
+
+=== Field subtypes ===
+
+The OGRFieldSubType enumeration is added :
+
+{{{
+/**
+ * List of field subtypes. A subtype represents a hint, a restriction of the
+ * main type, that is not strictly necessary to consult.
+ * This list is likely to be extended in the
+ * future ... avoid coding applications based on the assumption that all
+ * field types can be known.
+ * Most subtypes only make sense for a restricted set of main types.
+ * @since GDAL 2.0
+ */
+typedef enum
+{
+    /** No subtype. This is the default value */        OFSTNone = 0,
+    /** Boolean integer. Only valid for OFTInteger and OFTIntegerList.*/
+                                                        OFSTBoolean = 1,
+    /** Signed 16-bit integer. Only valid for OFTInteger and OFTIntegerList. */
+                                                        OFSTInt16 = 2,
+    /** Single precision (32 bit) floatint point. Only valid for OFTReal and OFTRealList. */
+                                                        OFSTFloat32 = 3,
+                                                        OFSTMaxSubType = 3
+} OGRFieldSubType;
+}}}
+
+
+=== New attributes and methods ===
+
+  * In OGRFieldDefn class :
+{{{
+    OGRFieldSubType     eSubType;
+
+    OGRFieldSubType     GetSubType() { return eSubType; }
+    void                SetSubType( OGRFieldSubType eSubTypeIn );
+    static const char  *GetFieldSubTypeName( OGRFieldSubType );
+}}}
+
+OGRFeature::SetField() will check that the passed value is in the accepted
+range for boolean and int16 subtypes. If not, it will emit a warning and
+correct/clamp the value to fit the subtype.
+
+=== C API changes ===
+
+Only additions :
+{{{
+OGRFieldSubType CPL_DLL OGR_Fld_GetSubType( OGRFieldDefnH );
+void   CPL_DLL OGR_Fld_SetSubType( OGRFieldDefnH, OGRFieldSubType );
+const char CPL_DLL *OGR_GetFieldSubTypeName( OGRFieldSubType );
+int CPL_DLL OGR_AreTypeSubTypeCompatible( OGRFieldType eType,
+                                          OGRFieldSubType eSubType );
+}}}
+
+== Changes in OGR SQL ==
+
+  * Subtypes are preserved when a field name (or *) is specified in the list
+    of fields of a SELECT
+  * CAST(xxx AS BOOLEAN) and CAST(xxx AS SMALLINT) are now supported.
+  * The field list of a SELECT can now accept boolean expressions, such as
+    "SELECT x IS NULL, x >= 5 FROM foo"
+  * The WHERE clause of a SELECT can now accept boolean fields, such as
+    "SELECT * FROM foo WHERE a_boolean_field"
+
+== Changes in drivers ==
+
+  * GeoJSON: can read/write OFSTBoolean
+  * GML: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32
+  * CSV: can read/write OFSTBoolean (explicitely with CSVT or with autodetection), OFSTInt16 and OFSTFloat32 (explicitely with CSVT)
+  * PG: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32
+  * PGDump: can write OFSTBoolean, OFSTInt16 and OFSTFloat32
+  * GeoPackage: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32
+  * SQLite: can read/write OFSTBoolean and OFSTInt16
+  * SQLite dialect: can read/write OFSTBoolean, OFSTInt16 and OFSTFloat32
+  * FileGDB: can read/write OFSTInt16 and OFSTFloat32
+  * OpenFileGDB: can read OFSTInt16 and OFSTFloat32
+  * VRT: 'subtype' property added to be able to handle any subtype.
+
+== Changes in utilities ==
+
+  * ogrinfo: the output of ogrinfo is slightly modified in presence of a subtype.
+    A field with a non-default subtype will be described as "field_type(field_subtype)".
+    For example
+{{{
+Had to open data source read-only.
+INFO: Open of `out.gml'
+      using driver `GML' successful.
+
+Layer name: test
+Geometry: None
+Feature Count: 2
+Layer SRS WKT:
+(unknown)
+short: Integer(Int16) (0.0)
+b: Integer(Boolean) (0.0)
+OGRFeature(test):0
+  short (Integer(Int16)) = -32768
+  b (Integer(Boolean)) = 1
+}}}
+
+== Changes in SWIG bindings ==
+
+Addition of :
+  * ogr.OFSTNone, ogr.OFSTBoolean, ogr.OFSTInt16 and ogr.OFSTFloat32
+  * ogr.GetFieldSubTypeName()
+  * FieldDefn.GetSubType()
+  * FieldDefn.SetSubType()
+
+== Compatibility ==
+
+This should have no impact on read-only operations done by applications.
+Update operations could be impacted if an out-of-range value for the subtype
+is written (but such a behaviour probably already caused issues, either ignored or
+notified by the backend)
+
+== Documentation ==
+
+All new methods are documented. Driver documentationis updated when necessary.
+
+== Testing ==
+
+The various aspects of this RFC are tested:
+  * core changes 
+  * OGR SQL changes
+  * driver changes
+
+== Implementation ==
+
+Implementation will be done by Even Rouault ([http://spatialys.com Spatialys]),
+and sponsored by [https://cartodb.com CartoDB].
+
+The proposed implementation lies in the "ogr_field_subtype" branch of the 
+https://github.com/rouault/gdal2/tree/ogr_field_subtype repository.
+
+The list of changes : https://github.com/rouault/gdal2/compare/ogr_field_subtype
+
+== Voting history ==
+
+TBD