WL#8055: Consistent naming scheme for GIS functions - Deprecation

This WL is about cleaning up the GIS function namespace by
deprecating, removing and adding function names (aliases) in order to
make the naming scheme consistent and bring MySQL in line with other
major DBMSs.

The standard among DBMSs is to use an "ST_" prefix to function names,
as specified by SQL/MM. PostGIS, Oracle and most other systems follow
this naming scheme, while Microsoft SQL Server uses "ST" without the
underscore.

In MySQL, almost all GIS functions have multiple names. Most functions
have two names: one with an "ST_" prefix, and one without, e.g.,
"ST_SRID" and "SRID". Newer functions are implemented only with an
"ST_" prefix, while some older functions only have a name without the
prefix.

Some functions have two implementations: one that gives an exact
answer, and one "MBR" implementation that uses a minimum bounding
rectangle instead of the exact shape of objects, e.g., "ST_Contains"
and "MBRContains". For most of these functions, there is also a third
name without a prefix, e.g., "Contains". The name without a prefix
mostly points to the MBR functions, but not always.

In one case, the non-prefixed function name collides with an existing
function, so the non-prefixed version of "ST_Length" is "GLength"
("Length" calculates the length of a string).

This WL will standardize on "ST_" prefixed functions by making the
following changes:

 - Add "ST_" prefixed function names for functions that don't have
   them (except "MBR" prefixed functions).

 - Deprecate function names without an "ST_" or "MBR" prefix.

The only exception to this standardization is the geometry object
construction functions Point, LineString, Polygon, MultiPoint,
MultiLineString, MultiPolygon and GeometryCollection. These functions
have the same name as the corresponding column type and will not be
deprecated or receive an "ST_" prefix.

In total, 66 function names are deprecated, and 13 are added.

Functional requirements:

F-1: The following functions MUST cause a completion condition to be
     raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling
     the user to use the "MBR" prefixed name instead:

     Contains
     Disjoint
     Equals
     Intersects
     Overlaps
     Within

F-2: The following functions MUST cause a completion condition to be
     raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling
     the user to use the "ST_" prefixed name instead.

     Area
     AsBinary
     AsText
     AsWKB
     AsWKT
     Buffer
     Centroid
     ConvexHull
     Crosses
     Dimension
     Distance
     EndPoint
     Envelope
     ExteriorRing
     GeometryN
     GeometryType
     InteriorRingN
     IsClosed
     IsEmpty
     IsSimple
     NumGeometries
     NumInteriorRings
     NumPoints
     PointN
     SRID
     StartPoint
     Touches
     X
     Y

F-3: The "GLength" function MUST cause a completion condition to be
     raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling
     the user to use the "ST_Length" function instead.

F-4: The following functions MUST cause a completion condition to be
     raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling
     the user to use the "ST_" prefixed name instead.

     GeomCollFromText
     GeomCollFromWKB
     GeometryCollectionFromText
     GeometryCollectionFromWKB
     GeometryFromText
     GeometryFromWKB
     GeomFromText
     GeomFromWKB
     LineFromText
     LineFromWKB
     LineStringFromText
     LineStringFromWKB
     MLineFromText
     MLineFromWKB
     MPointFromText
     MPointFromWKB
     MPolyFromText
     MPolyFromWKB
     MultiLineStringFromText
     MultiLineStringFromWKB
     MultiPointFromText
     MultiPointFromWKB
     MultiPolygonFromText
     MultiPolygonFromWKB
     PointFromText
     PointFromWKB
     PolyFromText
     PolyFromWKB
     PolygonFromText
     PolygonFromWKB

F-5: The following new function names MUST be added and refer to the
     same function as without the "ST_" prefix:

     ST_GeomCollFromTxt
     ST_MLineFromText
     ST_MLineFromWKB
     ST_MPointFromText
     ST_MPointFromWKB
     ST_MPolyFromText
     ST_MPolyFromWKB
     ST_MultiLineStringFromText
     ST_MultiLineStringFromWKB
     ST_MultiPointFromText
     ST_MultiPointFromWKB
     ST_MultiPolygonFromText
     ST_MultiPolygonFromWKB

F-6: The functions in F-5 MUST NOT raise a completion condition with
     the ER_WARN_DEPRECATED_SYNTAX warning message.

Changes to the interface specification:

I-1: No new files.

I-2: New syntax: 13 new functions:

         ST_GeomCollFromTxt([, ])
         ST_MLineFromText([, ])
         ST_MLineFromWKB([, ])
         ST_MPointFromText([, ])
         ST_MPointFromWKB([, ])
         ST_MPolyFromText([, ])
         ST_MPolyFromWKB([, ])
         ST_MultiLineStringFromText([, ])
         ST_MultiLineStringFromWKB([, ])
         ST_MultiPointFromText([, ])
         ST_MultiPointFromWKB([, ])
         ST_MultiPolygonFromText([, ])
         ST_MultiPolygonFromWKB([, ])

I-3: No new commands.

I-4: No new tools.

I-5: No impact on existing functionality.

Deprecation of function names
=============================
Before this WL, it is not possible to know which function alias that was used
when the query was sent from the user. So in order to identify which function
alias that was used, we need an extra field in Item class:

In Item.h:
  - Add public field to Item class: char *function_alias_used= NULL;

This field will be populated in PTI_function_call_generic_ident_sys::itemize(),
when the native functions are resolved. This is the stage where we know which
alias was used when the query was sent from the user.

For each function to be deprecated, we can use this field do determine whether we
should raise a deprecation warning or not. For instance, for Area()
the code will look something like this:

  if (native_strcasecmp("area", this->function_alias_used) == 0)
    push_deprecated_warn(current_thd, "AREA", "ST_AREA");

This code snippet will be added in each functions val_*-function, so that one
warning is raised for each row evaluated. Some initial testing shows that string
comparison should not cause any performance issues at all.

Adding new function names
=========================
For each of the new function names to be added in F-5, we add a new entry in
Item_create::func_array[], which refers to the correct Create_func-class. For
instance, ST_MultiLineStringFromText will refer to the class 
Create_func_geometry_from_text.

Test suite
==========
All test that uses any of the deprecated spatial functions must be changed and
re-recorded to use the correct function alias. 

A new test file named deprecated_functions.test will be added to MTR to ensure
that all deprecated spatial functions do raise a ER_WARN_DEPRECATED_SYNTAX warning.