qgis.h

Go to the documentation of this file.

/***************************************************************************
                          qgis.h - QGIS namespace
                             -------------------
    begin                : Sat Jun 30 2002
    copyright            : (C) 2002 by Gary E.Sherman
    email                : sherman at mrcc.com
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef QGIS_H
#define QGIS_H

#include <QMetaEnum>
#include <cfloat>
#include <memory>
#include <cmath>

#include "qgstolerance.h"
#include "qgis_core.h"
#include "qgis_sip.h"

#ifdef SIP_RUN
% ModuleHeaderCode
#include <qgis.h>
% End

% ModuleCode
int QgisEvent = QEvent::User + 1;
% End
#endif


class CORE_EXPORT Qgis
{
  public:
    // Version constants
    //
    static const QString QGIS_VERSION;
    static const int QGIS_VERSION_INT;
    static const QString QGIS_RELEASE_NAME;
    static const char *QGIS_DEV_VERSION;

    // Enumerations
    //

    enum MessageLevel
    {
      Info = 0,
      Warning = 1,
      Critical = 2,
      Success = 3,
      None = 4
    };

    enum DataType
    {
      UnknownDataType = 0, 
      Byte = 1, 
      UInt16 = 2, 
      Int16 = 3, 
      UInt32 = 4, 
      Int32 = 5, 
      Float32 = 6, 
      Float64 = 7, 
      CInt16 = 8, 
      CInt32 = 9, 
      CFloat32 = 10, 
      CFloat64 = 11, 
      ARGB32 = 12, 
      ARGB32_Premultiplied = 13 
    };

    static const double DEFAULT_SEARCH_RADIUS_MM;

    static const float DEFAULT_MAPTOPIXEL_THRESHOLD;

    static const QColor DEFAULT_HIGHLIGHT_COLOR;

    static const double DEFAULT_HIGHLIGHT_BUFFER_MM;

    static const double DEFAULT_HIGHLIGHT_MIN_WIDTH_MM;

    static const double SCALE_PRECISION;

    static const double DEFAULT_Z_COORDINATE;

    static const double UI_SCALE_FACTOR;

    static const double DEFAULT_SNAP_TOLERANCE;

    static const QgsTolerance::UnitType DEFAULT_SNAP_UNITS;
};

// hack to workaround warnings when casting void pointers
// retrieved from QLibrary::resolve to function pointers.
// It's assumed that this works on all systems supporting
// QLibrary
#define cast_to_fptr(f) f


// based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
template<class Object> class QgsSignalBlocker SIP_SKIP SIP_SKIP // clazy:exclude=rule-of-three
{
  public:

    explicit QgsSignalBlocker( Object *object )
      : mObject( object )
      , mPreviousState( object->blockSignals( true ) )
    {}

    ~QgsSignalBlocker()
    {
      mObject->blockSignals( mPreviousState );
    }

    Object *operator->() { return mObject; }

  private:

    Object *mObject = nullptr;
    bool mPreviousState;

};

// based on Boojum's code from http://stackoverflow.com/questions/3556687/prevent-firing-signals-in-qt
template<class Object> inline QgsSignalBlocker<Object> whileBlocking( Object *object ) SIP_SKIP SIP_SKIP
{
  return QgsSignalBlocker<Object>( object );
}

CORE_EXPORT uint qHash( const QVariant &variant );

inline QString qgsDoubleToString( double a, int precision = 17 )
{
  if ( precision )
  {
    QString str = QString::number( a, 'f', precision );
    if ( str.contains( QLatin1Char( '.' ) ) )
    {
      // remove ending 0s
      int idx = str.length() - 1;
      while ( str.at( idx ) == '0' && idx > 1 )
      {
        idx--;
      }
      if ( idx < str.length() - 1 )
        str.truncate( str.at( idx ) == '.' ? idx : idx + 1 );
    }
    return str;
  }
  else
  {
    // avoid printing -0
    // see https://bugreports.qt.io/browse/QTBUG-71439
    const QString str( QString::number( a, 'f', precision ) );
    if ( str == QLatin1String( "-0" ) )
    {
      return QLatin1String( "0" );
    }
    else
    {
      return str;
    }
  }
}

inline bool qgsDoubleNear( double a, double b, double epsilon = 4 * std::numeric_limits<double>::epsilon() )
{
  const double diff = a - b;
  return diff > -epsilon && diff <= epsilon;
}

inline bool qgsFloatNear( float a, float b, float epsilon = 4 * FLT_EPSILON )
{
  const float diff = a - b;
  return diff > -epsilon && diff <= epsilon;
}

inline bool qgsDoubleNearSig( double a, double b, int significantDigits = 10 )
{
  // The most simple would be to print numbers as %.xe and compare as strings
  // but that is probably too costly
  // Then the fastest would be to set some bits directly, but little/big endian
  // has to be considered (maybe TODO)
  // Is there a better way?
  int aexp, bexp;
  double ar = std::frexp( a, &aexp );
  double br = std::frexp( b, &bexp );

  return aexp == bexp &&
         std::round( ar * std::pow( 10.0, significantDigits ) ) == std::round( br * std::pow( 10.0, significantDigits ) );
}

inline double qgsRound( double number, int places )
{
  double m = ( number < 0.0 ) ? -1.0 : 1.0;
  double scaleFactor = std::pow( 10.0, places );
  return ( std::round( number * m * scaleFactor ) / scaleFactor ) * m;
}


#ifndef SIP_RUN


namespace qgis
{
  // as_const

  template <typename T> struct QgsAddConst { typedef const T Type; };

  template <typename T>
  constexpr typename QgsAddConst<T>::Type &as_const( T &t ) noexcept { return t; }

  template <typename T>
  void as_const( const T && ) = delete;

  // make_unique - from https://stackoverflow.com/a/17902439/1861260

  template<class T> struct _Unique_if
  {
    typedef std::unique_ptr<T> _Single_object;
  };

  template<class T> struct _Unique_if<T[]>
  {
    typedef std::unique_ptr<T[]> _Unknown_bound;
  };

  template<class T, size_t N> struct _Unique_if<T[N]>
  {
    typedef void _Known_bound;
  };

  template<class T, class... Args>
  typename _Unique_if<T>::_Single_object
  make_unique( Args &&... args )
  {
    return std::unique_ptr<T>( new T( std::forward<Args>( args )... ) );
  }

  template<class T>
  typename _Unique_if<T>::_Unknown_bound
  make_unique( size_t n )
  {
    typedef typename std::remove_extent<T>::type U;
    return std::unique_ptr<T>( new U[n]() );
  }

  template<class T, class... Args>
  typename _Unique_if<T>::_Known_bound
  make_unique( Args &&... ) = delete;

  template<typename... Args> struct overload
  {
    template<typename C, typename R>
    static constexpr auto of( R( C::*pmf )( Args... ) ) -> decltype( pmf )
    {
      return pmf;
    }
  };
}
#endif

template<class T> const QMap<T, QString> qgsEnumMap() SIP_SKIP
{
  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
  Q_ASSERT( metaEnum.isValid() );
  QMap<T, QString> enumMap;
  for ( int idx = 0; idx < metaEnum.keyCount(); ++idx )
  {
    const char *enumKey = metaEnum.key( idx );
    enumMap.insert( static_cast<T>( metaEnum.keyToValue( enumKey ) ), QString( enumKey ) );
  }
  return enumMap;
}

template<class T> QString qgsEnumValueToKey( const T &value ) SIP_SKIP
{
  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
  Q_ASSERT( metaEnum.isValid() );
  return QString::fromUtf8( metaEnum.valueToKey( value ) );
}

template<class T> T qgsEnumKeyToValue( const QString &key, const T &defaultValue ) SIP_SKIP
{
  QMetaEnum metaEnum = QMetaEnum::fromType<T>();
  Q_ASSERT( metaEnum.isValid() );
  bool ok = false;
  T v = static_cast<T>( metaEnum.keyToValue( key.toUtf8().data(), &ok ) );
  if ( ok )
    return v;
  else
    return defaultValue;
}


CORE_EXPORT double qgsPermissiveToDouble( QString string, bool &ok );

CORE_EXPORT int qgsPermissiveToInt( QString string, bool &ok );

CORE_EXPORT qlonglong qgsPermissiveToLongLong( QString string, bool &ok );

CORE_EXPORT bool qgsVariantLessThan( const QVariant &lhs, const QVariant &rhs );

CORE_EXPORT bool qgsVariantEqual( const QVariant &lhs, const QVariant &rhs );


CORE_EXPORT bool qgsVariantGreaterThan( const QVariant &lhs, const QVariant &rhs );

CORE_EXPORT QString qgsVsiPrefix( const QString &path );

void CORE_EXPORT *qgsMalloc( size_t size ) SIP_SKIP;

void CORE_EXPORT *qgsCalloc( size_t nmemb, size_t size ) SIP_SKIP;

void CORE_EXPORT qgsFree( void *ptr ) SIP_SKIP;

extern CORE_EXPORT const QString GEOWKT;
extern CORE_EXPORT const QString PROJECT_SCALES;

extern CORE_EXPORT const QString GEOPROJ4;
const long GEOSRID = 4326;
const long GEOCRS_ID = 3452;
const long GEO_EPSG_CRS_ID = 4326;
extern CORE_EXPORT const QString GEO_EPSG_CRS_AUTHID;

const int USER_CRS_START_ID = 100000;

extern CORE_EXPORT const QString GEO_NONE;

//
// Constants for point symbols
//

const double DEFAULT_POINT_SIZE = 2.0;
const double DEFAULT_LINE_WIDTH = 0.26;

const double DEFAULT_SEGMENT_EPSILON = 1e-8;

#ifndef SIP_RUN

const int PREVIEW_JOB_DELAY_MS = 250;

const int MAXIMUM_LAYER_PREVIEW_TIME_MS = 250;
#endif


typedef QMap<QString, QString> QgsStringMap SIP_SKIP;

typedef unsigned long long qgssize;

#ifndef SIP_RUN
#if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)) || defined(__clang__)

#define Q_NOWARN_DEPRECATED_PUSH \
  _Pragma("GCC diagnostic push") \
  _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
#define Q_NOWARN_DEPRECATED_POP \
  _Pragma("GCC diagnostic pop");
#define Q_NOWARN_UNREACHABLE_PUSH
#define Q_NOWARN_UNREACHABLE_POP

#elif defined(_MSC_VER)

#define Q_NOWARN_DEPRECATED_PUSH \
  __pragma(warning(push)) \
  __pragma(warning(disable:4996))
#define Q_NOWARN_DEPRECATED_POP \
  __pragma(warning(pop))
#define Q_NOWARN_UNREACHABLE_PUSH \
  __pragma(warning(push)) \
  __pragma(warning(disable:4702))
#define Q_NOWARN_UNREACHABLE_POP \
  __pragma(warning(pop))

#else

#define Q_NOWARN_DEPRECATED_PUSH
#define Q_NOWARN_DEPRECATED_POP
#define Q_NOWARN_UNREACHABLE_PUSH
#define Q_NOWARN_UNREACHABLE_POP

#endif
#endif

#ifndef QGISEXTERN
#ifdef Q_OS_WIN
#  define QGISEXTERN extern "C" __declspec( dllexport )
#  ifdef _MSC_VER
// do not warn about C bindings returning QString
#    pragma warning(disable:4190)
#  endif
#else
#  if defined(__GNUC__) || defined(__clang__)
#    define QGISEXTERN extern "C" __attribute__ ((visibility ("default")))
#  else
#    define QGISEXTERN extern "C"
#  endif
#endif
#endif
#endif

#if __cplusplus >= 201500
#define FALLTHROUGH [[fallthrough]];
#elif defined(__clang__)
#define FALLTHROUGH [[clang::fallthrough]];
#elif defined(__GNUC__) && __GNUC__ >= 7
#define FALLTHROUGH [[gnu::fallthrough]];
#else
#define FALLTHROUGH
#endif

// see https://infektor.net/posts/2017-01-19-using-cpp17-attributes-today.html#using-the-nodiscard-attribute
#if __cplusplus >= 201703L
#define NODISCARD [[nodiscard]]
#elif defined(__clang__)
#define NODISCARD [[nodiscard]]
#elif defined(_MSC_VER)
#define NODISCARD // no support
#elif defined(__has_cpp_attribute)
#if __has_cpp_attribute(nodiscard)
#define NODISCARD [[nodiscard]]
#elif __has_cpp_attribute(gnu::warn_unused_result)
#define NODISCARD [[gnu::warn_unused_result]]
#else
#define NODISCARD Q_REQUIRED_RESULT
#endif
#else
#define NODISCARD Q_REQUIRED_RESULT
#endif

#if __cplusplus >= 201703L
#define MAYBE_UNUSED [[maybe_unused]]
#elif defined(__clang__)
#define MAYBE_UNUSED [[maybe_unused]]
#elif defined(_MSC_VER)
#define MAYBE_UNUSED // no support
#elif defined(__has_cpp_attribute)
#if __has_cpp_attribute(gnu::unused)
#define MAYBE_UNUSED [[gnu::unused]]
#else
#define MAYBE_UNUSED
#endif
#else
#define MAYBE_UNUSED
#endif

#ifndef FINAL
#define FINAL final
#endif