Changes between Version 4 and Version 5 of rfc35_deletereorderalterfielddefn


Ignore:
Timestamp:
May 8, 2011, 10:17:06 AM (13 years ago)
Author:
Even Rouault
Comment:

v2: add ReorderFields() to reorder several fields at once; ReorderField() kept as a conveniency wrapper

Legend:

Unmodified
Added
Removed
Modified

  • rfc35_deletereorderalterfielddefn

    v4 v5  
    2525{{{
    2626    virtual OGRErr      DeleteField( int iField );
    27     virtual OGRErr      ReorderField( int iOldFieldPos, int iNewFieldPos );
     27    virtual OGRErr      ReorderFields( int* panNewOrder );
    2828    virtual OGRErr      AlterFieldDefn( int iField, OGRFieldDefn* poNewFieldDefn, int nFlags );
     29
     30    /* non virtual : conveniency wrapper for ReorderFields() */
     31    OGRErr              ReorderField( int iOldFieldPos, int iNewFieldPos );
    2932}}}
    3033
    … …  
    4245used by a layer directly.
    4346
    44 This function should not be called while there are feature objects in existance that
     47This method should not be called while there are feature objects in existance that
    4548were obtained or created with the previous layer definition.
    4649
    … …  
    6063
    6164/**
    62 \fn OGRErr OGRLayer::ReorderField( int iOldFieldPos, int iNewFieldPos );
    63 
    64 \brief Reorder an existing field on a layer.
     65\fn OGRErr OGRLayer::ReorderFields( int* panNewOrder );
     66
     67\brief Reorder all the fields of a layer.
    6568
    6669You must use this to reorder existing fields
    … …  
    6972used by a layer directly.
    7073
    71 This function should not be called while there are feature objects in existance that
    72 were obtained or created with the previous layer definition.
    73 
    74 Not all drivers support this method. You can query a layer to check if it supports it
    75 with the OLCReorderField capability. Some drivers may only support this method while
     74This method should not be called while there are feature objects in existance that
     75were obtained or created with the previous layer definition.
     76
     77For each field definition initially at position i, its new position
     78will be panNewOrder[i].
     79
     80For example, let suppose the fields were "0","1","2","3","4" initially.
     81ReorderFields([0,3,1,2,4]) will reorder them as "0","2","3","1","4".
     82
     83Not all drivers support this method. You can query a layer to check if it supports it
     84with the OLCReorderFields capability. Some drivers may only support this method while
    7685there are still no features in the layer. When it is supported, the existings features of the
    7786backing file/database should be updated accordingly.
    7887
     88This function is the same as the C function OGR_L_ReorderFields().
     89
     90@param panNewOrder an array of GetLayerDefn()->GetFieldCount() elements which
     91is a permutation of [0, GetLayerDefn()->GetFieldCount()-1].
     92
     93@return OGRERR_NONE on success.
     94
     95@since OGR 1.9.0
     96*/
     97
     98/**
     99\fn OGRErr OGRLayer::ReorderField( int iOldFieldPos, int iNewFieldPos );
     100
     101\brief Reorder an existing field on a layer.
     102
     103This method is a conveniency wrapper of ReorderFields() dedicated to move a single field.
     104
     105You must use this to reorder existing fields
     106on a real layer. Internally the OGRFeatureDefn for the layer will be updated
     107to reflect the reordering of the fields.  Applications should never modify the OGRFeatureDefn
     108used by a layer directly.
     109
     110This method should not be called while there are feature objects in existance that
     111were obtained or created with the previous layer definition.
     112
     113The field definition that was at initial position iOldFieldPos will be moved at
     114position iNewFieldPos, and elements between will be shuffled accordingly.
     115
     116For example, let suppose the fields were "0","1","2","3","4" initially.
     117ReorderField(1, 3) will reorder them as "0","2","3","1","4".
     118
     119Not all drivers support this method. You can query a layer to check if it supports it
     120with the OLCReorderFields capability. Some drivers may only support this method while
     121there are still no features in the layer. When it is supported, the existings features of the
     122backing file/database should be updated accordingly.
     123
    79124This function is the same as the C function OGR_L_ReorderField().
    80125
    81 @param iOldFieldPos previous position of the field to move.
    82 @param iNewFieldPos new position of the field to move.
     126@param iOldFieldPos previous position of the field to move. Must be in the range [0,GetFieldCount()-1].
     127@param iNewFieldPos new position of the field to move. Must be in the range [0,GetFieldCount()-1].
    83128
    84129@return OGRERR_NONE on success.
    … …  
    97142used by a layer directly.
    98143
    99 This function should not be called while there are feature objects in existance that
     144This method should not be called while there are feature objects in existance that
    100145were obtained or created with the previous layer definition.
    101146
    … …  
    125170existing fields on the current layer using DeleteField(), otherwise FALSE.
    126171
    127 OLCReorderField / "ReorderField": TRUE if this layer can reorder
    128 existing fields on the current layer using ReorderField(), otherwise FALSE.
     172OLCReorderFields / "ReorderFields": TRUE if this layer can reorder
     173existing fields on the current layer using ReorderField() or ReorderFields(), otherwise FALSE.
    129174
    130175OLCAlterFieldDefn / "AlterFieldDefn": TRUE if this layer can alter
    … …  
    136181{{{
    137182OGRErr CPL_DLL OGR_L_DeleteField( OGRLayerH, int iField );
     183OGRErr CPL_DLL OGR_L_ReorderFields( OGRLayerH, int* panNewOrder );
    138184OGRErr CPL_DLL OGR_L_ReorderField( OGRLayerH, int iOldFieldPos, int iNewFieldPos );
    139185OGRErr CPL_DLL OGR_L_AlterFieldDefn( OGRLayerH, int iField, OGRFieldDefnH hNewFieldDefn, int nFlags );
    … …  
    143189{{{
    144190    OGRErr      DeleteFieldDefn( int iField );
    145     OGRErr      ReorderFieldDefn( int iOldFieldPos, int iNewFieldPos );
    146 }}}
     191    OGRErr      ReorderFieldDefns( int* panNewOrder );
     192}}}
     193
     194A OGRErr OGRCheckPermutation(int* panPermutation, int nSize) function is added to ogrutils.cpp to
     195check that the array is a permutation of [0,nSize-1]. It is used by OGRFeatureDefn::ReorderFieldDefns()
     196and can be used by all drivers implementing OGRLayer::ReorderFields() to validate the panNewOrder argument.
    147197
    148198== Compatibility Issues ==
    … …  
    152202== Changed drivers ==
    153203
    154 The shapefile driver will implement DeleteField(), ReorderField() and AlterFieldDefn(). Shapelib will be
    155 extended with DBFReorderField() and DBFAlterFieldDefn().
     204The shapefile driver will implement DeleteField(), ReorderFields() and AlterFieldDefn(). Shapelib will be
     205extended with DBFReorderFields() and DBFAlterFieldDefn().
    156206
    157207Note: The implementation of AlterFieldDefn() in the Shapefile driver does not currently support altering
    … …  
    166216== SWIG bindings ==
    167217
    168 DeleteField(), ReorderField() and AlterFieldDefn() will be mapped to SWIG.
     218DeleteField(), ReorderField(), ReorderFields() and AlterFieldDefn() will be mapped to SWIG.
    169219
    170220== Test Suite ==
    … …  
    177227Implementation will be done by Even Rouault in GDAL/OGR trunk. Changes in Shapelib will need to be
    178228pushed into upstream CVS by a Shapelib committer. The proposed implementation is attached as
    179 a patch in ticket #2671 ([http://trac.osgeo.org/gdal/attachment/ticket/2671/rfc35.patch rfc35.patch]).
     229a patch in ticket #2671 ([http://trac.osgeo.org/gdal/attachment/ticket/2671/rfc35_v2.patch rfc35_v2.patch]).