KOpeningHours

openinghours.h
1 /*
2  SPDX-FileCopyrightText: 2020 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef KOPENINGHOURS_OPENINGHOURS_H
8 #define KOPENINGHOURS_OPENINGHOURS_H
9 
10 #include "kopeninghours_export.h"
11 
12 #include <QExplicitlySharedDataPointer>
13 #include <QMetaType>
14 
15 class QByteArray;
16 class QDateTime;
17 class QJsonObject;
18 class QString;
19 class QTimeZone;
20 
21 /** OSM opening hours parsing and evaluation. */
22 namespace KOpeningHours {
23 
24 class Interval;
25 class OpeningHoursPrivate;
26 
27 /** An OSM opening hours specification.
28  * This is the main entry point into this library, providing both a way to parse opening hours expressions
29  * and to evaluate them.
30  * @see https://wiki.openstreetmap.org/wiki/Key:opening_hours
31  */
32 class KOPENINGHOURS_EXPORT OpeningHours
33 {
34  Q_GADGET
35  Q_PROPERTY(Error error READ error)
36  Q_PROPERTY(QString normalizedExpression READ normalizedExpressionString)
37  Q_PROPERTY(float latitude READ latitude WRITE setLatitude)
38  Q_PROPERTY(float longitude READ longitude WRITE setLongitude)
39 #ifndef KOPENINGHOURS_VALIDATOR_ONLY
40  Q_PROPERTY(QString region READ region WRITE setRegion)
41 #endif
42  Q_PROPERTY(QString timeZone READ timeZoneId WRITE setTimeZoneId)
43 public:
44  /** Evaluation modes for opening hours expressions. */
45  enum Mode {
46  IntervalMode = 1, ///< Expressions that describe time ranges
47  PointInTimeMode = 2, ///< Expressions that describe points in time
48  };
49  Q_DECLARE_FLAGS(Modes, Mode)
50  Q_FLAG(Modes)
51 
52  /** Create an empty/invalid instance. */
53  explicit OpeningHours();
54 
55  /** Parse OSM opening hours expression @p openingHours.
56  * @param modes Specify whether time interval and/or point in time expressions are expected.
57  * If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
58  */
59  explicit OpeningHours(const QByteArray &openingHours, Modes modes = IntervalMode);
60  /** Parse OSM opening hours expression @p openingHours.
61  * @param modes Specify whether time interval and/or point in time expressions are expected.
62  * If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
63  */
64  explicit OpeningHours(const char *openingHours, std::size_t size, Modes modes = IntervalMode);
65 
66  OpeningHours(const OpeningHours&);
68  ~OpeningHours();
69 
70  OpeningHours& operator=(const OpeningHours&);
71  OpeningHours& operator=(OpeningHours&&);
72 
73  /** Parse OSM opening hours expression @p openingHours.
74  * @param modes Specify whether time interval and/or point in time expressions are expected.
75  * If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
76  * Prefer this over creating new instances if you are processing <b>many</b> expressions
77  * at once.
78  */
79  void setExpression(const QByteArray &openingHours, Modes modes = IntervalMode);
80  /** Parse OSM opening hours expression @p openingHours.
81  * @param modes Specify whether time interval and/or point in time expressions are expected.
82  * If @p openingHours doesn't match @p modes, error() return IncompatibleMode.
83  * Prefer this over creating new instances if you are processing <b>many</b> expressions
84  * at once.
85  */
86  void setExpression(const char *openingHours, std::size_t size, Modes modes = IntervalMode);
87 
88  /** Returns the OSM opening hours expression reconstructed from this object.
89  * In many cases it will be the same as the expression given to the constructor
90  * or to setExpression, but some normalization can happen as well, especially in
91  * case of non-conform input.
92  */
93  QByteArray normalizedExpression() const;
94 
95  /** Returns a simplified OSM opening hours expression reconstructed from this object.
96  * In many cases it will be the same as normalizedExpression(), but further
97  * simplifications can happen, to make the expression shorter/simpler.
98  */
99  QByteArray simplifiedExpression() const;
100 
101  /** Geographic coordinate at which this expression should be evaluated.
102  * This is needed for expressions containing location-based variable time references,
103  * such as "sunset". If the expression requires a location, error() returns @c MissingLocation
104  * if no location has been specified.
105  */
106  Q_INVOKABLE void setLocation(float latitude, float longitude);
107 
108  float latitude() const;
109  void setLatitude(float latitude);
110  float longitude() const;
111  void setLongitude(float longitude);
112 
113 #ifndef KOPENINGHOURS_VALIDATOR_ONLY
114  /** ISO 3166-2 region or ISO 316-1 country in which this expression should be evaluated.
115  * This is needed for expressions containing public holiday references ("PH").
116  * If the expression references a public holiday, error() returns @c MissingRegion
117  * if no region has been specified, or if no holiday data is available for the specified region.
118  */
119  void setRegion(QStringView region);
120  QString region() const;
121 #endif
122 
123  /** Timezone in which this expression should be evaluated.
124  * If not specified, this assumes local time.
125  */
126  void setTimeZone(const QTimeZone &tz);
127  QTimeZone timeZone() const;
128 
129  /** Error codes. */
130  enum Error {
131  Null, ///< no expression is set
132  NoError, ///< there is no error, the expression is valid and can be used
133  SyntaxError, ///< syntax error in the opening hours expression
134  MissingRegion, ///< expression refers to public or school holidays, but that information is not available
135  MissingLocation, ///< evaluation requires location information and those aren't set
136  IncompatibleMode, ///< expression mode doesn't match the expected mode
137  UnsupportedFeature, ///< expression uses a feature that isn't implemented/supported (yet)
138  EvaluationError, ///< runtime error during evaluating the expression
139  };
140  Q_ENUM(Error)
141 
142  /** Error status of this expression. */
143  Error error() const;
144 
145 #ifndef KOPENINGHOURS_VALIDATOR_ONLY
146  /** Returns the interval containing @p dt. */
147  Q_INVOKABLE KOpeningHours::Interval interval(const QDateTime &dt) const;
148  /** Returns the interval immediately following @p interval. */
149  Q_INVOKABLE KOpeningHours::Interval nextInterval(const KOpeningHours::Interval &interval) const;
150 #endif
151 
152  /** Convert opening hours in schema.org JSON-LD format.
153  * This supports the following formats:
154  * - https://schema.org/openingHours
155  * - https://schema.org/openingHoursSpecification
156  * - https://schema.org/specialOpeningHoursSpecification
157  */
158  static OpeningHours fromJsonLd(const QJsonObject &obj);
159 
160 private:
161  // for QML bindings
162  Q_DECL_HIDDEN QString normalizedExpressionString() const;
163  Q_DECL_HIDDEN QString timeZoneId() const;
164  Q_DECL_HIDDEN void setTimeZoneId(const QString &tzId);
165 
167 };
168 
169 }
170 
171 Q_DECLARE_METATYPE(KOpeningHours::OpeningHours)
172 
173 #endif // KOPENINGHOURS_OPENINGHOURS_H
@ MissingRegion
expression refers to public or school holidays, but that information is not available
Definition: openinghours.h:134
@ NoError
there is no error, the expression is valid and can be used
Definition: openinghours.h:132
@ SyntaxError
syntax error in the opening hours expression
Definition: openinghours.h:133
@ MissingLocation
evaluation requires location information and those aren't set
Definition: openinghours.h:135
@ EvaluationError
runtime error during evaluating the expression
Definition: openinghours.h:138
@ UnsupportedFeature
expression uses a feature that isn't implemented/supported (yet)
Definition: openinghours.h:137
Mode
Evaluation modes for opening hours expressions.
Definition: openinghours.h:45
An OSM opening hours specification.
Definition: openinghours.h:32
@ Null
no expression is set
Definition: openinghours.h:131
@ IncompatibleMode
expression mode doesn't match the expected mode
Definition: openinghours.h:136
OSM opening hours parsing and evaluation.
Definition: display.h:14
A time interval for which an opening hours expression has been evaluated.
Definition: interval.h:24
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 04:03:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.