KOpeningHours

openinghours.h
1/*
2 SPDX-FileCopyrightText: 2020 Volker Krause <vkrause@kde.org>
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
15class QByteArray;
16class QDateTime;
17class QJsonObject;
18class QString;
19class QTimeZone;
20
21/** OSM opening hours parsing and evaluation. */
22namespace KOpeningHours {
23
24class Interval;
25class 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 */
32class 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)
43public:
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
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
160private:
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
171Q_DECLARE_METATYPE(KOpeningHours::OpeningHours)
172
173#endif // KOPENINGHOURS_OPENINGHOURS_H
A time interval for which an opening hours expression has been evaluated.
Definition interval.h:25
An OSM opening hours specification.
Mode
Evaluation modes for opening hours expressions.
@ MissingLocation
evaluation requires location information and those aren't set
@ UnsupportedFeature
expression uses a feature that isn't implemented/supported (yet)
@ EvaluationError
runtime error during evaluating the expression
@ IncompatibleMode
expression mode doesn't match the expected mode
@ Null
no expression is set
@ SyntaxError
syntax error in the opening hours expression
@ MissingRegion
expression refers to public or school holidays, but that information is not available
@ NoError
there is no error, the expression is valid and can be used
OSM opening hours parsing and evaluation.
Definition display.h:16
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:20:35 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.