File indexing completed on 2024-12-08 07:18:31

 /*
     SPDX-FileCopyrightText: 2020 Volker Krause <vkrause@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KOPENINGHOURS_OPENINGHOURS_H
 #define KOPENINGHOURS_OPENINGHOURS_H
 
 #include "kopeninghours_export.h"
 
 #include <QExplicitlySharedDataPointer>
 #include <QMetaType>
 
 class QByteArray;
 class QDateTime;
 class QJsonObject;
 class QString;
 class QTimeZone;
 
 /** OSM opening hours parsing and evaluation. */
 namespace KOpeningHours {
 
 class Interval;
 class OpeningHoursPrivate;
 
 /** An OSM opening hours specification.
  *  This is the main entry point into this library, providing both a way to parse opening hours expressions
  *  and to evaluate them.
  *  @see https://wiki.openstreetmap.org/wiki/Key:opening_hours
  */
 class KOPENINGHOURS_EXPORT OpeningHours
 {
     Q_GADGET
     Q_PROPERTY(Error error READ error)
     Q_PROPERTY(QString normalizedExpression READ normalizedExpressionString)
     Q_PROPERTY(float latitude READ latitude WRITE setLatitude)
     Q_PROPERTY(float longitude READ longitude WRITE setLongitude)
 #ifndef KOPENINGHOURS_VALIDATOR_ONLY
     Q_PROPERTY(QString region READ region WRITE setRegion)
 #endif
     Q_PROPERTY(QString timeZone READ timeZoneId WRITE setTimeZoneId)
 public:
     /** Evaluation modes for opening hours expressions. */
     enum Mode {
         IntervalMode = 1, ///< Expressions that describe time ranges
         PointInTimeMode = 2, ///< Expressions that describe points in time
     };
     Q_DECLARE_FLAGS(Modes, Mode)
     Q_FLAG(Modes)
 
     /** Create an empty/invalid instance. */
     explicit OpeningHours();
 
     /** Parse OSM opening hours expression @p openingHours.
      *  @param modes Specify whether time interval and/or point in time expressions are expected.
      *  If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
      */
     explicit OpeningHours(const QByteArray &openingHours, Modes modes = IntervalMode);
     /** Parse OSM opening hours expression @p openingHours.
      *  @param modes Specify whether time interval and/or point in time expressions are expected.
      *  If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
      */
     explicit OpeningHours(const char *openingHours, std::size_t size, Modes modes = IntervalMode);
 
     OpeningHours(const OpeningHours&);
     OpeningHours(OpeningHours&&);
     ~OpeningHours();
 
     OpeningHours& operator=(const OpeningHours&);
     OpeningHours& operator=(OpeningHours&&);
 
     /** Parse OSM opening hours expression @p openingHours.
      *  @param modes Specify whether time interval and/or point in time expressions are expected.
      *  If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
      *  Prefer this over creating new instances if you are processing <b>many</b> expressions
      *  at once.
      */
     void setExpression(const QByteArray &openingHours, Modes modes = IntervalMode);
     /** Parse OSM opening hours expression @p openingHours.
      *  @param modes Specify whether time interval and/or point in time expressions are expected.
      *  If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
      *  Prefer this over creating new instances if you are processing <b>many</b> expressions
      *  at once.
      */
     void setExpression(const char *openingHours, std::size_t size, Modes modes = IntervalMode);
 
     /** Returns the OSM opening hours expression reconstructed from this object.
      * In many cases it will be the same as the expression given to the constructor
      * or to setExpression, but some normalization can happen as well, especially in
      * case of non-conform input.
      */
     QByteArray normalizedExpression() const;
 
     /** Returns a simplified OSM opening hours expression reconstructed from this object.
      * In many cases it will be the same as normalizedExpression(), but further
      * simplifications can happen, to make the expression shorter/simpler.
      */
     QByteArray simplifiedExpression() const;
 
     /** Geographic coordinate at which this expression should be evaluated.
      *  This is needed for expressions containing location-based variable time references,
      *  such as "sunset". If the expression requires a location, error() returns @c MissingLocation
      *  if no location has been specified.
      */
     Q_INVOKABLE void setLocation(float latitude, float longitude);
 
     float latitude() const;
     void setLatitude(float latitude);
     float longitude() const;
     void setLongitude(float longitude);
 
 #ifndef KOPENINGHOURS_VALIDATOR_ONLY
     /** ISO 3166-2 region or ISO 316-1 country in which this expression should be evaluated.
      *  This is needed for expressions containing public holiday references ("PH").
      *  If the expression references a public holiday, error() returns @c MissingRegion
      *  if no region has been specified, or if no holiday data is available for the specified region.
      */
     void setRegion(QStringView region);
     QString region() const;
 #endif
 
     /** Timezone in which this expression should be evaluated.
      *  If not specified, this assumes local time.
      */
     void setTimeZone(const QTimeZone &tz);
     QTimeZone timeZone() const;
 
     /** Error codes. */
     enum Error {
         Null, ///< no expression is set
         NoError, ///< there is no error, the expression is valid and can be used
         SyntaxError, ///< syntax error in the opening hours expression
         MissingRegion, ///< expression refers to public or school holidays, but that information is not available
         MissingLocation, ///< evaluation requires location information and those aren't set
         IncompatibleMode, ///< expression mode doesn't match the expected mode
         UnsupportedFeature, ///< expression uses a feature that isn't implemented/supported (yet)
         EvaluationError, ///< runtime error during evaluating the expression
     };
     Q_ENUM(Error)
 
     /** Error status of this expression. */
     Error error() const;
 
 #ifndef KOPENINGHOURS_VALIDATOR_ONLY
     /** Returns the interval containing @p dt. */
     Q_INVOKABLE KOpeningHours::Interval interval(const QDateTime &dt) const;
     /** Returns the interval immediately following @p interval. */
     Q_INVOKABLE KOpeningHours::Interval nextInterval(const KOpeningHours::Interval &interval) const;
 #endif
 
     /** Convert opening hours in schema.org JSON-LD format.
      *  This supports the following formats:
      *  - https://schema.org/openingHours
      *  - https://schema.org/openingHoursSpecification
      *  - https://schema.org/specialOpeningHoursSpecification
      */
     static OpeningHours fromJsonLd(const QJsonObject &obj);
 
 private:
     // for QML bindings
     Q_DECL_HIDDEN QString normalizedExpressionString() const;
     Q_DECL_HIDDEN QString timeZoneId() const;
     Q_DECL_HIDDEN void setTimeZoneId(const QString &tzId);
 
     QExplicitlySharedDataPointer<OpeningHoursPrivate> d;
 };
 
 }
 
 Q_DECLARE_METATYPE(KOpeningHours::OpeningHours)
 
 #endif // KOPENINGHOURS_OPENINGHOURS_H