include/QtCore/qregularexpression.h

0001 // Copyright (C) 2020 Giuseppe D'Angelo <dangelog@gmail.com>.
0002 // Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
0003 // Copyright (C) 2021 The Qt Company Ltd.
0004 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0005
0006 #ifndef QREGULAREXPRESSION_H
0007 #define QREGULAREXPRESSION_H
0008
0009 #include <QtCore/qglobal.h>
0010 #include <QtCore/qstring.h>
0011 #include <QtCore/qstringview.h>
0012 #include <QtCore/qshareddata.h>
0013 #include <QtCore/qvariant.h>
0014
0015 #include <iterator>
0016
0017 QT_REQUIRE_CONFIG(regularexpression);
0018
0019 QT_BEGIN_NAMESPACE
0020
0021 class QRegularExpressionMatch;
0022 class QRegularExpressionMatchIterator;
0023 struct QRegularExpressionPrivate;
0024 class QRegularExpression;
0025
0026 QT_DECLARE_QESDP_SPECIALIZATION_DTOR_WITH_EXPORT(QRegularExpressionPrivate, Q_CORE_EXPORT)
0027
0028 Q_CORE_EXPORT size_t qHash(const QRegularExpression &key, size_t seed = 0) noexcept;
0029
0030 class Q_CORE_EXPORT QRegularExpression
0031 {
0032 public:
0033     enum PatternOption {
0034         NoPatternOption                = 0x0000,
0035         CaseInsensitiveOption          = 0x0001,
0036         DotMatchesEverythingOption     = 0x0002,
0037         MultilineOption                = 0x0004,
0038         ExtendedPatternSyntaxOption    = 0x0008,
0039         InvertedGreedinessOption       = 0x0010,
0040         DontCaptureOption              = 0x0020,
0041         UseUnicodePropertiesOption     = 0x0040,
0042         // Formerly (no-ops deprecated in 5.12, removed 6.0):
0043         // OptimizeOnFirstUsageOption = 0x0080,
0044         // DontAutomaticallyOptimizeOption = 0x0100,
0045     };
0046     Q_DECLARE_FLAGS(PatternOptions, PatternOption)
0047
0048     PatternOptions patternOptions() const;
0049     void setPatternOptions(PatternOptions options);
0050
0051     QRegularExpression();
0052     explicit QRegularExpression(const QString &pattern, PatternOptions options = NoPatternOption);
0053     QRegularExpression(const QRegularExpression &re) noexcept;
0054     QRegularExpression(QRegularExpression &&re) = default;
0055     ~QRegularExpression();
0056     QRegularExpression &operator=(const QRegularExpression &re) noexcept;
0057     QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(QRegularExpression)
0058
0059     void swap(QRegularExpression &other) noexcept { d.swap(other.d); }
0060
0061     QString pattern() const;
0062     void setPattern(const QString &pattern);
0063
0064     [[nodiscard]]
0065     bool isValid() const;
0066     qsizetype patternErrorOffset() const;
0067     QString errorString() const;
0068
0069     int captureCount() const;
0070     QStringList namedCaptureGroups() const;
0071
0072     enum MatchType {
0073         NormalMatch = 0,
0074         PartialPreferCompleteMatch,
0075         PartialPreferFirstMatch,
0076         NoMatch
0077     };
0078
0079     enum MatchOption {
0080         NoMatchOption              = 0x0000,
0081         AnchorAtOffsetMatchOption  = 0x0001,
0082         AnchoredMatchOption Q_DECL_ENUMERATOR_DEPRECATED_X(
0083             "Use AnchorAtOffsetMatchOption instead") = AnchorAtOffsetMatchOption, // Rename@Qt6.0
0084         DontCheckSubjectStringMatchOption = 0x0002
0085     };
0086     Q_DECLARE_FLAGS(MatchOptions, MatchOption)
0087
0088     [[nodiscard]]
0089     QRegularExpressionMatch match(const QString &subject,
0090                                   qsizetype offset          = 0,
0091                                   MatchType matchType       = NormalMatch,
0092                                   MatchOptions matchOptions = NoMatchOption) const;
0093
0094 #if QT_DEPRECATED_SINCE(6, 8)
0095     [[nodiscard]]
0096     QT_DEPRECATED_VERSION_X_6_8("Use matchView instead.")
0097     QRegularExpressionMatch match(QStringView subjectView,
0098                                   qsizetype offset          = 0,
0099                                   MatchType matchType       = NormalMatch,
0100                                   MatchOptions matchOptions = NoMatchOption) const;
0101 #endif
0102
0103     [[nodiscard]]
0104     QRegularExpressionMatch matchView(QStringView subjectView,
0105                                       qsizetype offset          = 0,
0106                                       MatchType matchType       = NormalMatch,
0107                                       MatchOptions matchOptions = NoMatchOption) const;
0108
0109     [[nodiscard]]
0110     QRegularExpressionMatchIterator globalMatch(const QString &subject,
0111                                                 qsizetype offset          = 0,
0112                                                 MatchType matchType       = NormalMatch,
0113                                                 MatchOptions matchOptions = NoMatchOption) const;
0114
0115 #if QT_DEPRECATED_SINCE(6, 8)
0116     [[nodiscard]]
0117     QT_DEPRECATED_VERSION_X_6_8("Use globalMatchView instead.")
0118     QRegularExpressionMatchIterator globalMatch(QStringView subjectView,
0119                                                 qsizetype offset          = 0,
0120                                                 MatchType matchType       = NormalMatch,
0121                                                 MatchOptions matchOptions = NoMatchOption) const;
0122 #endif
0123
0124     [[nodiscard]]
0125     QRegularExpressionMatchIterator globalMatchView(QStringView subjectView,
0126                                                     qsizetype offset          = 0,
0127                                                     MatchType matchType       = NormalMatch,
0128                                                     MatchOptions matchOptions = NoMatchOption) const;
0129
0130     void optimize() const;
0131
0132     enum WildcardConversionOption {
0133         DefaultWildcardConversion = 0x0,
0134         UnanchoredWildcardConversion = 0x1,
0135         NonPathWildcardConversion = 0x2,
0136     };
0137     Q_DECLARE_FLAGS(WildcardConversionOptions, WildcardConversionOption)
0138
0139     static QString escape(const QString &str)
0140     {
0141         return escape(qToStringViewIgnoringNull(str));
0142     }
0143
0144     static QString wildcardToRegularExpression(const QString &str, WildcardConversionOptions options = DefaultWildcardConversion)
0145     {
0146         return wildcardToRegularExpression(qToStringViewIgnoringNull(str), options);
0147     }
0148
0149     static inline QString anchoredPattern(const QString &expression)
0150     {
0151         return anchoredPattern(qToStringViewIgnoringNull(expression));
0152     }
0153
0154     static QString escape(QStringView str);
0155     static QString wildcardToRegularExpression(QStringView str, WildcardConversionOptions options = DefaultWildcardConversion);
0156     static QString anchoredPattern(QStringView expression);
0157
0158     static QRegularExpression fromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive,
0159                                            WildcardConversionOptions options = DefaultWildcardConversion);
0160
0161     bool operator==(const QRegularExpression &re) const;
0162     inline bool operator!=(const QRegularExpression &re) const { return !operator==(re); }
0163
0164 private:
0165     friend struct QRegularExpressionPrivate;
0166     friend class QRegularExpressionMatch;
0167     friend struct QRegularExpressionMatchPrivate;
0168     friend class QRegularExpressionMatchIterator;
0169     friend Q_CORE_EXPORT size_t qHash(const QRegularExpression &key, size_t seed) noexcept;
0170
0171     QRegularExpression(QRegularExpressionPrivate &dd);
0172     QExplicitlySharedDataPointer<QRegularExpressionPrivate> d;
0173 };
0174
0175 Q_DECLARE_SHARED(QRegularExpression)
0176 Q_DECLARE_OPERATORS_FOR_FLAGS(QRegularExpression::PatternOptions)
0177 Q_DECLARE_OPERATORS_FOR_FLAGS(QRegularExpression::MatchOptions)
0178 Q_DECLARE_OPERATORS_FOR_FLAGS(QRegularExpression::WildcardConversionOptions)
0179
0180 #ifndef QT_NO_DATASTREAM
0181 Q_CORE_EXPORT QDataStream &operator<<(QDataStream &out, const QRegularExpression &re);
0182 Q_CORE_EXPORT QDataStream &operator>>(QDataStream &in, QRegularExpression &re);
0183 #endif
0184
0185 #ifndef QT_NO_DEBUG_STREAM
0186 Q_CORE_EXPORT QDebug operator<<(QDebug debug, const QRegularExpression &re);
0187 Q_CORE_EXPORT QDebug operator<<(QDebug debug, QRegularExpression::PatternOptions patternOptions);
0188 #endif
0189
0190 struct QRegularExpressionMatchPrivate;
0191 QT_DECLARE_QESDP_SPECIALIZATION_DTOR_WITH_EXPORT(QRegularExpressionMatchPrivate, Q_CORE_EXPORT)
0192
0193 class Q_CORE_EXPORT QRegularExpressionMatch
0194 {
0195 public:
0196     QRegularExpressionMatch();
0197     ~QRegularExpressionMatch();
0198     QRegularExpressionMatch(const QRegularExpressionMatch &match);
0199     QRegularExpressionMatch(QRegularExpressionMatch &&match) = default;
0200     QRegularExpressionMatch &operator=(const QRegularExpressionMatch &match);
0201     QRegularExpressionMatch &operator=(QRegularExpressionMatch &&match) noexcept
0202     { d.swap(match.d); return *this; }
0203     void swap(QRegularExpressionMatch &other) noexcept { d.swap(other.d); }
0204
0205     QRegularExpression regularExpression() const;
0206     QRegularExpression::MatchType matchType() const;
0207     QRegularExpression::MatchOptions matchOptions() const;
0208
0209     bool hasMatch() const;
0210     bool hasPartialMatch() const;
0211
0212     bool isValid() const;
0213
0214     int lastCapturedIndex() const;
0215
0216     bool hasCaptured(const QString &name) const
0217     { return hasCaptured(QStringView(name)); }
0218     bool hasCaptured(QStringView name) const;
0219     bool hasCaptured(int nth) const;
0220
0221     QString captured(int nth = 0) const;
0222     QStringView capturedView(int nth = 0) const;
0223
0224     QString captured(const QString &name) const
0225     { return captured(QStringView(name)); }
0226     QString captured(QStringView name) const;
0227     QStringView capturedView(QStringView name) const;
0228
0229     QStringList capturedTexts() const;
0230
0231     qsizetype capturedStart(int nth = 0) const;
0232     qsizetype capturedLength(int nth = 0) const;
0233     qsizetype capturedEnd(int nth = 0) const;
0234
0235     qsizetype capturedStart(const QString &name) const
0236     { return capturedStart(QStringView(name)); }
0237     qsizetype capturedLength(const QString &name) const
0238     { return capturedLength(QStringView(name)); }
0239     qsizetype capturedEnd(const QString &name) const
0240     { return capturedEnd(QStringView(name)); }
0241
0242     qsizetype capturedStart(QStringView name) const;
0243     qsizetype capturedLength(QStringView name) const;
0244     qsizetype capturedEnd(QStringView name) const;
0245
0246 private:
0247     friend class QRegularExpression;
0248     friend struct QRegularExpressionMatchPrivate;
0249     friend class QRegularExpressionMatchIterator;
0250
0251     QRegularExpressionMatch(QRegularExpressionMatchPrivate &dd);
0252     QExplicitlySharedDataPointer<QRegularExpressionMatchPrivate> d;
0253 };
0254
0255 Q_DECLARE_SHARED(QRegularExpressionMatch)
0256
0257 #ifndef QT_NO_DEBUG_STREAM
0258 Q_CORE_EXPORT QDebug operator<<(QDebug debug, const QRegularExpressionMatch &match);
0259 #endif
0260
0261 namespace QtPrivate {
0262 class QRegularExpressionMatchIteratorRangeBasedForIterator;
0263 class QRegularExpressionMatchIteratorRangeBasedForIteratorSentinel {};
0264 }
0265
0266 struct QRegularExpressionMatchIteratorPrivate;
0267 QT_DECLARE_QESDP_SPECIALIZATION_DTOR_WITH_EXPORT(QRegularExpressionMatchIteratorPrivate, Q_CORE_EXPORT)
0268
0269 class Q_CORE_EXPORT QRegularExpressionMatchIterator
0270 {
0271 public:
0272     QRegularExpressionMatchIterator();
0273     ~QRegularExpressionMatchIterator();
0274     QRegularExpressionMatchIterator(const QRegularExpressionMatchIterator &iterator);
0275     QRegularExpressionMatchIterator(QRegularExpressionMatchIterator &&iterator) = default;
0276     QRegularExpressionMatchIterator &operator=(const QRegularExpressionMatchIterator &iterator);
0277     QRegularExpressionMatchIterator &operator=(QRegularExpressionMatchIterator &&iterator) noexcept
0278     { d.swap(iterator.d); return *this; }
0279     void swap(QRegularExpressionMatchIterator &other) noexcept { d.swap(other.d); }
0280
0281     bool isValid() const;
0282
0283     bool hasNext() const;
0284     QRegularExpressionMatch next();
0285     QRegularExpressionMatch peekNext() const;
0286
0287     QRegularExpression regularExpression() const;
0288     QRegularExpression::MatchType matchType() const;
0289     QRegularExpression::MatchOptions matchOptions() const;
0290
0291 private:
0292     friend class QRegularExpression;
0293     friend Q_CORE_EXPORT QtPrivate::QRegularExpressionMatchIteratorRangeBasedForIterator begin(const QRegularExpressionMatchIterator &iterator);
0294     friend QtPrivate::QRegularExpressionMatchIteratorRangeBasedForIteratorSentinel end(const QRegularExpressionMatchIterator &) { return {}; }
0295
0296     QRegularExpressionMatchIterator(QRegularExpressionMatchIteratorPrivate &dd);
0297     QExplicitlySharedDataPointer<QRegularExpressionMatchIteratorPrivate> d;
0298 };
0299
0300 namespace QtPrivate {
0301
0302 // support for range-based for loop
0303 class QRegularExpressionMatchIteratorRangeBasedForIterator
0304 {
0305 public:
0306     using value_type = QRegularExpressionMatch;
0307     using difference_type = int;
0308     using reference_type = const QRegularExpressionMatch &;
0309     using pointer_type = const QRegularExpressionMatch *;
0310     using iterator_category = std::forward_iterator_tag;
0311
0312     QRegularExpressionMatchIteratorRangeBasedForIterator()
0313         : m_atEnd(true)
0314     {
0315     }
0316
0317     explicit QRegularExpressionMatchIteratorRangeBasedForIterator(const QRegularExpressionMatchIterator &iterator)
0318         : m_matchIterator(iterator),
0319         m_currentMatch(),
0320         m_atEnd(false)
0321     {
0322         ++*this;
0323     }
0324
0325     const QRegularExpressionMatch &operator*() const
0326     {
0327         Q_ASSERT_X(!m_atEnd, Q_FUNC_INFO, "operator* called on an iterator already at the end");
0328         return m_currentMatch;
0329     }
0330
0331     QRegularExpressionMatchIteratorRangeBasedForIterator &operator++()
0332     {
0333         Q_ASSERT_X(!m_atEnd, Q_FUNC_INFO, "operator++ called on an iterator already at the end");
0334         if (m_matchIterator.hasNext()) {
0335             m_currentMatch = m_matchIterator.next();
0336         } else {
0337             m_currentMatch = QRegularExpressionMatch();
0338             m_atEnd = true;
0339         }
0340
0341         return *this;
0342     }
0343
0344     QRegularExpressionMatchIteratorRangeBasedForIterator operator++(int)
0345     {
0346         QRegularExpressionMatchIteratorRangeBasedForIterator i = *this;
0347         ++*this;
0348         return i;
0349     }
0350
0351 private:
0352     // [input.iterators] imposes operator== on us. Unfortunately, it's not
0353     // trivial to implement, so just do the bare minimum to satifisfy
0354     // Cpp17EqualityComparable.
0355     friend bool operator==(const QRegularExpressionMatchIteratorRangeBasedForIterator &lhs,
0356                            const QRegularExpressionMatchIteratorRangeBasedForIterator &rhs) noexcept
0357     {
0358         return (&lhs == &rhs);
0359     }
0360
0361     friend bool operator!=(const QRegularExpressionMatchIteratorRangeBasedForIterator &lhs,
0362                            const QRegularExpressionMatchIteratorRangeBasedForIterator &rhs) noexcept
0363     {
0364         return !(lhs == rhs);
0365     }
0366
0367     // This is what we really use in a range-based for.
0368     friend bool operator==(const QRegularExpressionMatchIteratorRangeBasedForIterator &lhs,
0369                            QRegularExpressionMatchIteratorRangeBasedForIteratorSentinel) noexcept
0370     {
0371         return lhs.m_atEnd;
0372     }
0373
0374     friend bool operator!=(const QRegularExpressionMatchIteratorRangeBasedForIterator &lhs,
0375                            QRegularExpressionMatchIteratorRangeBasedForIteratorSentinel) noexcept
0376     {
0377         return !lhs.m_atEnd;
0378     }
0379
0380     QRegularExpressionMatchIterator m_matchIterator;
0381     QRegularExpressionMatch m_currentMatch;
0382     bool m_atEnd;
0383 };
0384
0385 } // namespace QtPrivate
0386
0387 Q_DECLARE_SHARED(QRegularExpressionMatchIterator)
0388
0389 QT_END_NAMESPACE
0390
0391 #endif // QREGULAREXPRESSION_H