sipify QgsRange as template

python/auto_sip.blacklist

@@ -1,6 +1,5 @@
 core/conversions.sip
 core/qgsexception.sip
-core/qgsrange.sip
 core/composer/qgsaddremoveitemcommand.sip
 core/composer/qgsgroupungroupitemscommand.sip
 core/composer/qgsaddremovemultiframecommand.sip

python/core/qgsrange.sip

@@ -1,82 +1,238 @@
-class QgsDoubleRange
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsrange.h                                                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+template <T> class QgsRange
 {
-%TypeHeaderCode
-#include <qgsrange.h>
-%End
+%Docstring
+ A template based class for storing ranges (lower to upper values).
 
+ QgsRange classes represent a range of values of some element type. For instance,
+ ranges of int might be used to represent integer ranges.
+
+ Ranges can indicate whether the upper and lower values are inclusive or exclusive.
+ The inclusivity or exclusivity of bounds is considered when determining things like
+ whether ranges overlap or during calculation of range intersections.
+
+.. versionadded:: 3.0
+.. seealso:: QgsDoubleRange
+.. seealso:: QgsIntRange
+.. note::
+
+   not available in Python bindings (but class provided for template-based inheritance)
+%End
   public:
 
-    QgsDoubleRange( double lower, double upper, bool includeLower = true, bool includeUpper = true );
-    double lower() const;
-    double upper() const;
-    bool includeLower() const;
-    bool includeUpper() const;
-    bool isEmpty() const;
-    bool isSingleton() const;
-    bool contains( const QgsDoubleRange &other ) const;
-    bool contains( double element ) const;
-    bool overlaps( const QgsDoubleRange &other ) const;
-};
+    QgsRange( T lower, T upper, bool includeLower = true, bool includeUpper = true );
+%Docstring
+ Constructor for QgsRange. The ``lower`` and ``upper`` bounds are specified,
+ and optionally whether or not these bounds are included in the range.
+%End
 
-class QgsIntRange
-{
-%TypeHeaderCode
-#include <qgsrange.h>
+    T lower() const;
+%Docstring
+ Returns the lower bound of the range.
+.. seealso:: upper()
+.. seealso:: includeLower()
+ :rtype: T
 %End
 
-  public:
+    T upper() const;
+%Docstring
+ Returns the upper bound of the range.
+.. seealso:: lower()
+.. seealso:: includeUpper()
+ :rtype: T
+%End
 
-    QgsIntRange( int lower, int upper, bool includeLower = true, bool includeUpper = true );
-    int lower() const;
-    int upper() const;
     bool includeLower() const;
+%Docstring
+ Returns true if the lower bound is inclusive, or false if the lower
+ bound is exclusive.
+.. seealso:: lower()
+.. seealso:: includeUpper()
+ :rtype: bool
+%End
+
     bool includeUpper() const;
+%Docstring
+ Returns true if the upper bound is inclusive, or false if the upper
+ bound is exclusive.
+.. seealso:: upper()
+.. seealso:: includeLower()
+ :rtype: bool
+%End
+
     bool isEmpty() const;
+%Docstring
+ Returns true if the range is empty, ie the lower bound equals (or exceeds) the upper bound
+ and either the bounds are exclusive.
+.. seealso:: isSingleton()
+ :rtype: bool
+%End
+
     bool isSingleton() const;
-    bool contains( const QgsIntRange &other ) const;
-    bool contains( int element ) const;
-    bool overlaps( const QgsIntRange &other ) const;
-};
+%Docstring
+ Returns true if the range consists only of a single value or instant.
+.. seealso:: isEmpty()
+ :rtype: bool
+%End
 
-class QgsDateRange
-{
-%TypeHeaderCode
-#include <qgsrange.h>
+    bool contains( const QgsRange<T> &other ) const;
+%Docstring
+ Returns true if this range contains another range.
+.. seealso:: overlaps()
+ :rtype: bool
+%End
+
+    bool contains( T element ) const;
+%Docstring
+ Returns true if this range contains a specified ``element``.
+ :rtype: bool
+%End
+
+    bool overlaps( const QgsRange<T> &other ) const;
+%Docstring
+ Returns true if this range overlaps another range.
+.. seealso:: contains()
+ :rtype: bool
 %End
 
-  public:
 
-    QgsDateRange( const QDate &lower = QDate(), const QDate &upper = QDate(), bool includeLower = true, bool includeUpper = true );
-    QDate begin() const;
-    QDate end() const;
-    bool includeBeginning() const;
-    bool includeEnd() const;
-    bool isEmpty() const;
-    bool isInstant() const;
-    bool isInfinite() const;
-    bool contains( const QgsDateRange &other ) const;
-    bool contains( const QDate &element ) const;
-    bool overlaps( const QgsDateRange &other ) const;
 };
 
-class QgsDateTimeRange
+
+typedef QgsRange< double > QgsDoubleRange;
+
+
+
+
+typedef QgsRange< int > QgsIntRange;
+
+
+template <T> class QgsTemporalRange
 {
-%TypeHeaderCode
-#include <qgsrange.h>
-%End
+%Docstring
+ A template based class for storing temporal ranges (beginning to end values).
+
+ QgsTemporalRange classes represent a range of values of some temporal type. For instance,
+ ranges of QDateTime might be used to represent datetime ranges.
+
+ Ranges can indicate whether the upper and lower values are inclusive or exclusive.
+ The inclusivity or exclusivity of bounds is considered when determining things like
+ whether ranges overlap or during calculation of range intersections.
 
+.. versionadded:: 3.0
+.. seealso:: QgsDateRange
+.. note::
+
+   not available in Python bindings (but class provided for template-based inheritance)
+%End
   public:
 
-    QgsDateTimeRange( const QDateTime &lower = QDateTime(), const QDateTime &upper = QDateTime(), bool includeLower = true, bool includeUpper = true );
-    QDateTime begin() const;
-    QDateTime end() const;
+    QgsTemporalRange( const T &begin, const T &end, bool includeBeginning = true, bool includeEnd = true );
+%Docstring
+ Constructor for QgsTemporalRange. The ``begin`` and ``end`` are specified,
+ and optionally whether or not these bounds are included in the range.
+.. note::
+
+   in Python ``begin`` and ``end`` must be provided.
+%End
+    // default constructor as default value for templates is not handled in SIP
+
+    T begin() const;
+%Docstring
+ Returns the beginning of the range.
+.. seealso:: end()
+.. seealso:: includeBeginning()
+ :rtype: T
+%End
+
+    T end() const;
+%Docstring
+ Returns the upper bound of the range.
+.. seealso:: begin()
+.. seealso:: includeEnd()
+ :rtype: T
+%End
+
     bool includeBeginning() const;
+%Docstring
+ Returns true if the beginning is inclusive, or false if the beginning
+ is exclusive.
+.. seealso:: begin()
+.. seealso:: includeEnd()
+ :rtype: bool
+%End
+
     bool includeEnd() const;
-    bool isEmpty() const;
+%Docstring
+ Returns true if the end is inclusive, or false if the end is exclusive.
+.. seealso:: end()
+.. seealso:: includeBeginning()
+ :rtype: bool
+%End
+
     bool isInstant() const;
+%Docstring
+ Returns true if the range consists only of a single instant.
+.. seealso:: isEmpty()
+.. seealso:: isInfinite()
+ :rtype: bool
+%End
+
     bool isInfinite() const;
-    bool contains( const QgsDateTimeRange &other ) const;
-    bool contains( const QDateTime &element ) const;
-    bool overlaps( const QgsDateTimeRange &other ) const;
+%Docstring
+ Returns true if the range consists of all possible values.
+.. seealso:: isEmpty()
+.. seealso:: isInstant()
+ :rtype: bool
+%End
+
+    bool isEmpty() const;
+%Docstring
+ Returns true if the range is empty, ie the beginning equals (or exceeds) the end
+ and either of the bounds are exclusive.
+ A range with both invalid beginning and end is considered infinite and not empty.
+ :rtype: bool
+%End
+
+    bool contains( const QgsTemporalRange<T> &other ) const;
+%Docstring
+ Returns true if this range contains another range.
+ :rtype: bool
+%End
+
+    bool contains( const T &element ) const;
+%Docstring
+ Returns true if this range contains a specified ``element``.
+ :rtype: bool
+%End
+
+    bool overlaps( const QgsTemporalRange<T> &other ) const;
+%Docstring
+ Returns true if this range overlaps another range.
+ :rtype: bool
+%End
+
 };
 
+
+typedef QgsTemporalRange< QDate > QgsDateRange;
+
+typedef QgsTemporalRange< QDateTime > QgsDateTimeRange;
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/qgsrange.h                                                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

scripts/sipify.pl

@@ -694,7 +694,7 @@ sub detect_comment_block{
 
     # keyword fixes
     do {no warnings 'uninitialized';
-        $LINE =~ s/^(\s*template<)(?:class|typename) (\w+>)(.*)$/$1$2$3/;
+        $LINE =~ s/^(\s*template\s*<)(?:class|typename) (\w+>)(.*)$/$1$2$3/;
         $LINE =~ s/\s*\boverride\b//;
         $LINE =~ s/\s*\bextern \b//;
         $LINE =~ s/^(\s*)?(const )?(virtual |static )?inline /$1$2$3/;
@@ -712,7 +712,7 @@ sub detect_comment_block{
     # https://regex101.com/r/gUBZUk/10
     if ( $SIP_RUN != 1 &&
          $ACCESS[$#ACCESS] != PUBLIC &&
-         $LINE =~ m/^\s*(?:template<\w+>\s+)?(?:(const|mutable|static|friend|unsigned)\s+)*\w+(::\w+)?(<([\w<> *&,()]|::)+>)?(,?\s+\*?\w+( = (-?\d+(\.\d+)?|(\w+::)*\w+(\([^()]+\))?)|\[\d+\])?)+;/){
+         $LINE =~ m/^\s*(?:template\s*<\w+>\s+)?(?:(const|mutable|static|friend|unsigned)\s+)*\w+(::\w+)?(<([\w<> *&,()]|::)+>)?(,?\s+\*?\w+( = (-?\d+(\.\d+)?|(\w+::)*\w+(\([^()]+\))?)|\[\d+\])?)+;/){
         dbg_info("skip non-method member declaration in non-public sections");
         next;
     }
@@ -868,7 +868,7 @@ sub detect_comment_block{
         $IS_OVERRIDE = 0;
         next;
     }
-    if ( $LINE =~ m/^\s*template<.*>/ ){
+    if ( $LINE =~ m/^\s*template\s*<.*>/ ){
         # do not comment now for templates, wait for class definition
         next;
     }

src/core/qgsrange.h

@@ -37,9 +37,9 @@
  * \since QGIS 3.0
  * \see QgsDoubleRange
  * \see QgsIntRange
- * \note not available in Python bindings
+ * \note not available in Python bindings (but class provided for template-based inheritance)
  */
-template <class T> class QgsRange SIP_SKIP
+template <class T> class QgsRange
 {
   public:
 
@@ -211,22 +211,28 @@ typedef QgsRange< int > QgsIntRange;
  *
  * \since QGIS 3.0
  * \see QgsDateRange
- * \note not available in Python bindings
+ * \note not available in Python bindings (but class provided for template-based inheritance)
  */
-template <class T> class QgsTemporalRange SIP_SKIP
+template <class T> class QgsTemporalRange
 {
   public:
 
     /**
      * Constructor for QgsTemporalRange. The \a begin and \a end are specified,
      * and optionally whether or not these bounds are included in the range.
+     * \note in Python \a begin and \a end must be provided.
      */
+#ifndef SIP_RUN
     QgsTemporalRange( const T &begin = T(), const T &end = T(), bool includeBeginning = true, bool includeEnd = true )
       : mLower( begin )
       , mUpper( end )
       , mIncludeLower( includeBeginning )
       , mIncludeUpper( includeEnd )
     {}
+#else
+    QgsTemporalRange( const T &begin, const T &end, bool includeBeginning = true, bool includeEnd = true );
+    // default constructor as default value for templates is not handled in SIP
+#endif
 
     /**
      * Returns the beginning of the range.