Add rx(), ry(), ... methods to QgsPointV2, add missing docs to class

Allows for directly modifying point's coordinates in place

python/core/geometry/qgspointv2.sip

@@ -1,72 +1,156 @@
+/** \ingroup core
+ * \class QgsPointV2
+ * \brief Point geometry type, with support for z-dimension and m-values.
+ * \note added in QGIS 2.10
+ */
+
 class QgsPointV2: public QgsAbstractGeometryV2
 {
 %TypeHeaderCode
 #include <qgspointv2.h>
 %End
 
-    public:
-      QgsPointV2( double x = 0.0, double y = 0.0 );
-      QgsPointV2( const QgsPoint& p );
-      QgsPointV2( QgsWKBTypes::Type type, double x = 0.0, double y = 0.0, double z = 0.0, double m = 0.0 );
-
-      bool operator==( const QgsPointV2& pt ) const;
-      bool operator!=( const QgsPointV2& pt ) const;
-
-      virtual QgsPointV2* clone() const;
-      void clear();
-
-      double x() const;
-      double y() const;
-      double z() const;
-      double m() const;
-
-      void setX( double x );
-      void setY( double y );
-      void setZ( double z );
-      void setM( double m );
-
-      virtual QString geometryType() const;
-
-      //implementation of inherited methods
-      virtual int dimension() const;
-
-
-      virtual bool fromWkb( const unsigned char* wkb );
-      virtual bool fromWkt( const QString& wkt );
-
-      int wkbSize() const;
-      unsigned char* asWkb( int& binarySize ) const;
-      QString asWkt( int precision = 17 ) const;
-      QDomElement asGML2( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const;
-      QDomElement asGML3( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const;
-      QString asJSON( int precision = 17 ) const;
-
-      virtual QgsRectangle calculateBoundingBox() const;
-
-      void draw( QPainter& p ) const;
-      void transform( const QgsCoordinateTransform& ct );
-      void transform( const QTransform& t );
-
-      virtual void coordinateSequence( QList< QList< QList< QgsPointV2 > > >& coord /Out/ ) const;
-
-      //low-level editing
-      virtual bool insertVertex( const QgsVertexId& position, const QgsPointV2& vertex );
-      virtual bool moveVertex( const QgsVertexId& position, const QgsPointV2& newPos );
-      virtual bool deleteVertex( const QgsVertexId& position );
-
-      double closestSegment( const QgsPointV2& pt, QgsPointV2& segmentPt,  QgsVertexId& vertexAfter, bool* leftOf, double epsilon ) const;
-      bool nextVertex( QgsVertexId& id, QgsPointV2& vertex ) const;
-
-      /** Angle undefined. Always returns 0.0
-          @param vertex the vertex id
-          @return 0.0*/
-      double vertexAngle( const QgsVertexId& vertex ) const;
-
-      virtual int vertexCount(int part = 0, int ring = 0) const;
-      virtual int ringCount(int part = 0) const;
-      virtual int partCount() const;
-      virtual QgsPointV2 vertexAt( const QgsVertexId& id ) const;
-
-      virtual bool addZValue( double zValue = 0 );
-      virtual bool addMValue( double mValue = 0 );
+  public:
+
+    /** Construct a 2 dimensional point with an initial x and y coordinate.
+     * @param x x-coordinate of point
+     * @param y y-coordinate of point
+     */
+    QgsPointV2( double x = 0.0, double y = 0.0 );
+
+    /** Construct a QgsPointV2 from a QgsPoint object
+     */
+    QgsPointV2( const QgsPoint& p );
+
+    /** Construct a point with a specified type (eg PointZ, PointM) and initial x, y, z, and m values.
+     * @param type point type
+     * @param x x-coordinate of point
+     * @param y y-coordinate of point
+     * @param z z-coordinate of point, for PointZ or PointZM types
+     * @param m m-value of point, for PointM or PointZM types
+     */
+    QgsPointV2( QgsWKBTypes::Type type, double x = 0.0, double y = 0.0, double z = 0.0, double m = 0.0 );
+
+    bool operator==( const QgsPointV2& pt ) const;
+    bool operator!=( const QgsPointV2& pt ) const;
+
+    /** Returns the point's x-coordinate.
+     * @see setX()
+     * @see rx()
+     */
+    double x() const;
+
+    /** Returns the point's y-coordinate.
+     * @see setY()
+     * @see ry()
+     */
+    double y() const;
+
+    /** Returns the point's z-coordinate.
+     * @see setZ()
+     * @see rz()
+     */
+    double z() const;
+
+    /** Returns the point's m value.
+     * @see setM()
+     * @see rm()
+     */
+    double m() const;
+
+    /** Returns a reference to the x-coordinate of this point.
+     * Using a reference makes it possible to directly manipulate x in place.
+     * @see x()
+     * @see setX()
+     * @note not available in Python bindings
+     */
+    //double &rx();
+
+    /** Returns a reference to the y-coordinate of this point.
+     * Using a reference makes it possible to directly manipulate y in place.
+     * @see y()
+     * @see setY()
+     * @note not available in Python bindings
+     */
+    //double &ry();
+
+    /** Returns a reference to the z-coordinate of this point.
+     * Using a reference makes it possible to directly manipulate z in place.
+     * @see z()
+     * @see setZ()
+     * @note not available in Python bindings
+     */
+    //double &rz();
+
+    /** Returns a reference to the m value of this point.
+     * Using a reference makes it possible to directly manipulate m in place.
+     * @see m()
+     * @see setM()
+     * @note not available in Python bindings
+     */
+    //double &rm()
+
+    /** Sets the point's x-coordinate.
+     * @see x()
+     * @see rx()
+     */
+    void setX( double x );
+
+    /** Sets the point's y-coordinate.
+     * @see y()
+     * @see ry()
+     */
+    void setY( double y );
+
+    /** Sets the point's z-coordinate.
+     * @see z()
+     * @see rz()
+     */
+    void setZ( double z );
+
+    /** Sets the point's m-value.
+     * @see m()
+     * @see rm()
+     */
+    void setM( double m );
+
+    //implementation of inherited methods
+    virtual QString geometryType() const;
+    virtual int dimension() const;
+    virtual QgsPointV2* clone() const;
+    void clear();
+    virtual bool fromWkb( const unsigned char* wkb );
+    virtual bool fromWkt( const QString& wkt );
+    int wkbSize() const;
+    unsigned char* asWkb( int& binarySize ) const;
+    QString asWkt( int precision = 17 ) const;
+    QDomElement asGML2( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const;
+    QDomElement asGML3( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const;
+    QString asJSON( int precision = 17 ) const;
+    virtual QgsRectangle calculateBoundingBox() const;
+    void draw( QPainter& p ) const;
+    void transform( const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform );
+    void transform( const QTransform& t );
+    virtual void coordinateSequence( QList< QList< QList< QgsPointV2 > > >& coord /Out/ ) const;
+
+    //low-level editing
+    virtual bool insertVertex( const QgsVertexId& position, const QgsPointV2& vertex );
+    virtual bool moveVertex( const QgsVertexId& position, const QgsPointV2& newPos );
+    virtual bool deleteVertex( const QgsVertexId& position );
+
+    double closestSegment( const QgsPointV2& pt, QgsPointV2& segmentPt,  QgsVertexId& vertexAfter, bool* leftOf, double epsilon ) const;
+    bool nextVertex( QgsVertexId& id, QgsPointV2& vertex ) const;
+
+    /** Angle undefined. Always returns 0.0
+        @param vertex the vertex id
+        @return 0.0*/
+    double vertexAngle( const QgsVertexId& vertex ) const;
+
+    virtual int vertexCount(int part = 0, int ring = 0) const;
+    virtual int ringCount(int part = 0) const;
+    virtual int partCount() const;
+    virtual QgsPointV2 vertexAt( const QgsVertexId& id ) const;
+
+    virtual bool addZValue( double zValue = 0 );
+    virtual bool addMValue( double mValue = 0 );
 };

src/core/geometry/qgspointv2.h

@@ -22,60 +22,132 @@
 
 /** \ingroup core
  * \class QgsPointV2
- * \brief Point geometry type.
+ * \brief Point geometry type, with support for z-dimension and m-values.
  * \note added in QGIS 2.10
- * \note this API is not considered stable and may change for 2.12
  */
 class CORE_EXPORT QgsPointV2: public QgsAbstractGeometryV2
 {
   public:
+
+    /** Construct a 2 dimensional point with an initial x and y coordinate.
+     * @param x x-coordinate of point
+     * @param y y-coordinate of point
+     */
     QgsPointV2( double x = 0.0, double y = 0.0 );
+
+    /** Construct a QgsPointV2 from a QgsPoint object
+     */
     QgsPointV2( const QgsPoint& p );
+
+    /** Construct a point with a specified type (eg PointZ, PointM) and initial x, y, z, and m values.
+     * @param type point type
+     * @param x x-coordinate of point
+     * @param y y-coordinate of point
+     * @param z z-coordinate of point, for PointZ or PointZM types
+     * @param m m-value of point, for PointM or PointZM types
+     */
     QgsPointV2( QgsWKBTypes::Type type, double x = 0.0, double y = 0.0, double z = 0.0, double m = 0.0 );
 
     bool operator==( const QgsPointV2& pt ) const;
     bool operator!=( const QgsPointV2& pt ) const;
 
-    virtual QgsPointV2* clone() const override;
-    void clear() override;
-
+    /** Returns the point's x-coordinate.
+     * @see setX()
+     * @see rx()
+     */
     double x() const { return mX; }
+
+    /** Returns the point's y-coordinate.
+     * @see setY()
+     * @see ry()
+     */
     double y() const { return mY; }
+
+    /** Returns the point's z-coordinate.
+     * @see setZ()
+     * @see rz()
+     */
     double z() const { return mZ; }
+
+    /** Returns the point's m value.
+     * @see setM()
+     * @see rm()
+     */
     double m() const { return mM; }
 
+    /** Returns a reference to the x-coordinate of this point.
+     * Using a reference makes it possible to directly manipulate x in place.
+     * @see x()
+     * @see setX()
+     * @note not available in Python bindings
+     */
+    double &rx() { return mX; }
+
+    /** Returns a reference to the y-coordinate of this point.
+     * Using a reference makes it possible to directly manipulate y in place.
+     * @see y()
+     * @see setY()
+     * @note not available in Python bindings
+     */
+    double &ry() { return mY; }
+
+    /** Returns a reference to the z-coordinate of this point.
+     * Using a reference makes it possible to directly manipulate z in place.
+     * @see z()
+     * @see setZ()
+     * @note not available in Python bindings
+     */
+    double &rz() { return mZ; }
+
+    /** Returns a reference to the m value of this point.
+     * Using a reference makes it possible to directly manipulate m in place.
+     * @see m()
+     * @see setM()
+     * @note not available in Python bindings
+     */
+    double &rm() { return mM; }
+
+    /** Sets the point's x-coordinate.
+     * @see x()
+     * @see rx()
+     */
     void setX( double x ) { mX = x; }
+
+    /** Sets the point's y-coordinate.
+     * @see y()
+     * @see ry()
+     */
     void setY( double y ) { mY = y; }
+
+    /** Sets the point's z-coordinate.
+     * @see z()
+     * @see rz()
+     */
     void setZ( double z ) { mZ = z; }
-    void setM( double m ) { mM = m; }
 
-    virtual QString geometryType() const override { return "Point"; }
+    /** Sets the point's m-value.
+     * @see m()
+     * @see rm()
+     */
+    void setM( double m ) { mM = m; }
 
     //implementation of inherited methods
+    virtual QString geometryType() const override { return "Point"; }
     virtual int dimension() const override { return 0; }
-
-
+    virtual QgsPointV2* clone() const override;
+    void clear() override;
     virtual bool fromWkb( const unsigned char* wkb ) override;
     virtual bool fromWkt( const QString& wkt ) override;
-
     int wkbSize() const override;
     unsigned char* asWkb( int& binarySize ) const override;
     QString asWkt( int precision = 17 ) const override;
     QDomElement asGML2( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const override;
     QDomElement asGML3( QDomDocument& doc, int precision = 17, const QString& ns = "gml" ) const override;
     QString asJSON( int precision = 17 ) const override;
-
     virtual QgsRectangle calculateBoundingBox() const override { return QgsRectangle( mX, mY, mX, mY );}
-
     void draw( QPainter& p ) const override;
-
-    /** Transforms the geometry using a coordinate transform
-     * @param ct coordinate transform
-       @param d transformation direction
-     */
     void transform( const QgsCoordinateTransform& ct, QgsCoordinateTransform::TransformDirection d = QgsCoordinateTransform::ForwardTransform ) override;
     void transform( const QTransform& t ) override;
-
     virtual void coordinateSequence( QList< QList< QList< QgsPointV2 > > >& coord ) const override;
 
     //low-level editing