[Development] API review for the new QUrl

Thiago Macieira thiago at kde.org
Tue Oct 25 11:59:54 CEST 2011

I can't post the code just yet, but I can post the new API.

 - I un-deprecated fromEncoded and toEncoded, as they're used everywhere. 
Should I do the same for fromPercentEncoding and toPercentEncoding? They 
convert from QString to QByteArray and vice-versa, while 
QByteArray::fromPercentEncoding operates only on QByteArray.

 - QUrl::url() returns a QString. It should have a "to" prefix, since it 
returns a temporary. It's the exact same function as toString(). Should it be 

 - QUrlQuery does not keep the order of the items (it's kept in a hash). Is 
the order important?

 - unlike what I had proposed before, I kept the StrictMode parsing (or will 
have kept). However, unlike Qt 4, the actual parser is tolerant, with 
StrictMode implemented as a checker before the actual parser. This should 
improve in performance because 99% of the users use TolerantMode.

 - errorString is much more limited than in Qt 4 because I was only willing to 
dedicate 4 bytes for the error (one error code and one QChar). I feel that if 
you need a *real* URL validator, with very detailed explanations, you should 
use a dedicated class, not a generic URL container.

 - QString-based methods are rehabilitated, including the constructor and 
toString(). The constructor and copy operator from QString are still 
"disablable" with an #ifdef so you can spot unnecessary parsing. The 
QByteArray based methods are deprecated, except for fromEncoded / toEncoded.

 - talking about parsing: it's NOT lazy anymore. It's done at the moment you 
set the URL. Why? Because the one in Qt 4 was NOT THREAD-SAFE. Any use of 
const_cast<T *>(this) in a non-detached class is just plain wrong.

 - QUrl now operates *only* in encoded mode, but it does partially decode 
wherever possible. The default mode (PrettyDecoded) means most components will 
actually appear decoded, unless the component contains a character that should 
appear encoded in URL or cannot be represented at all in QString (such as a 
lone %80).

 - IP addresses are actually parsed and fixed appropriately (see the blog)

 - QUrl lowercases the scheme, so you no longer have to write:
    if (url.scheme().compare(QLatin1String("http"), Qt::CaseInsensitive) == 0)
or the much worse:
    if (url.scheme().toLower() == QLatin1String("http"))

    enum ParsingMode {

    // encoding / toString values
    enum UrlFormattingOption {
        None = 0x0,
        RemoveScheme = 0x1,
        RemovePassword = 0x2,
        RemoveUserInfo = RemovePassword | 0x4,
        RemovePort = 0x8,
        RemoveAuthority = RemoveUserInfo | RemovePort | 0x10,
        RemovePath = 0x20,
        RemoveQuery = 0x40,
        RemoveFragment = 0x80,
        // 0x100 was a private code in Qt 4, keep unused for a while
        StripTrailingSlash = 0x200

    enum ComponentFormattingOption {
        FullyEncoded = 0x0000,
        DecodeSpaces = 0x1000,
        DecodeUnambiguousDelimiters = 0x2000,
        DecodeAllDelimiters = DecodeUnambiguousDelimiters | 0x4000,
        DecodeUnicode = 0x8000,

        PrettyDecoded = DecodeSpaces | DecodeUnambiguousDelimiters | 
        MostDecoded = PrettyDecoded | DecodeAllDelimiters
    Q_DECLARE_FLAGS(ComponentFormattingOptions, ComponentFormattingOption)
#ifdef qdoc
    Q_DECLARE_FLAGS(FormattingOptions, UrlFormattingOption)
    typedef QUrlTwoFlags<UrlFormattingOption, ComponentFormattingOption> 

    QUrl(const QUrl &copy);
    QUrl &operator =(const QUrl &copy);
    explicit QUrl(const QString &url, ParsingMode mode = TolerantMode);
    QUrl(const QString &url, ParsingMode mode = TolerantMode);
    QUrl &operator=(const QString &url);
    QUrl(QUrl &&other) : d(0)
    { qSwap(d, other.d); }
    inline QUrl &operator=(QUrl &&other)
    { qSwap(d, other.d); return *this; }

    inline void swap(QUrl &other) { qSwap(d, other.d); }

    void setUrl(const QString &url, ParsingMode mode = TolerantMode);
    QString url(FormattingOptions options = FormattingOptions(PrettyDecoded)) 
    QString toString(FormattingOptions options = 
FormattingOptions(PrettyDecoded)) const;

    QByteArray toEncoded(FormattingOptions options = FullyEncoded) const;
    static QUrl fromEncoded(const QByteArray &url, ParsingMode mode = 

    static QUrl fromUserInput(const QString &userInput);

    bool isValid() const;
    QString errorString() const;

    bool isEmpty() const;
    void clear();

    void setScheme(const QString &scheme);
    QString scheme() const;

    void setAuthority(const QString &authority);
    QString authority(ComponentFormattingOptions options = PrettyDecoded) 

    void setUserInfo(const QString &userInfo);
    QString userInfo(ComponentFormattingOptions options = PrettyDecoded) 

    void setUserName(const QString &userName);
    QString userName(ComponentFormattingOptions options = PrettyDecoded) 

    void setPassword(const QString &password);
    QString password(ComponentFormattingOptions = PrettyDecoded) const;

    void setHost(const QString &host);
    QString host(ComponentFormattingOptions = PrettyDecoded) const;
    QString topLevelDomain(ComponentFormattingOptions options = PrettyDecoded) 

    void setPort(int port);
    int port(int defaultPort = -1) const;

    void setPath(const QString &path);
    QString path(ComponentFormattingOptions options = PrettyDecoded) const;

    bool hasQuery() const;
    void setQuery(const QString &query);
    void setQuery(const QUrlQuery &query);
    QString query(ComponentFormattingOptions = PrettyDecoded) const;

    bool hasFragment() const;
    QString fragment(ComponentFormattingOptions options = PrettyDecoded) 
    void setFragment(const QString &fragment);

    QUrl resolved(const QUrl &relative) const;

    bool isRelative() const;
    bool isParentOf(const QUrl &url) const;

    bool isLocalFile() const;
    static QUrl fromLocalFile(const QString &localfile);
    QString toLocalFile() const;

    void detach();
    bool isDetached() const;

    bool operator <(const QUrl &url) const;
    bool operator ==(const QUrl &url) const;
    bool operator !=(const QUrl &url) const;

    QT_DEPRECATED static QString fromPercentEncoding(const QByteArray 
    { return QString::fromUtf8(QByteArray::fromPercentEncoding(encoded)); }
    QT_DEPRECATED static QByteArray toPercentEncoding(const QString &string,
                                                      const QByteArray 
&exclude = QByteArray(),
                                                      const QByteArray 
&include = QByteArray())
    { return string.toUtf8().toPercentEncoding(exclude, include); }
    QT_DEPRECATED static QString fromPunycode(const QByteArray &punycode)
    { return fromAce(punycode); }
    QT_DEPRECATED static QByteArray toPunycode(const QString &string)
    { return toAce(string); }

    QT_DEPRECATED void setEncodedUrl(const QByteArray &url, ParsingMode mode = 
    { setUrl(QString::fromUtf8(url), mode); }

    QT_DEPRECATED QByteArray encodedUserName() const
    { return userName(FullyEncoded).toLatin1(); }
    QT_DEPRECATED void setEncodedUserName(const QByteArray &value)
    { setUserName(QString::fromLatin1(value)); }

    QT_DEPRECATED QByteArray encodedPassword() const
    { return password(FullyEncoded).toLatin1(); }
    QT_DEPRECATED void setEncodedPassword(const QByteArray &value)
    { setPassword(QString::fromLatin1(value)); }

    QT_DEPRECATED QByteArray encodedHost() const
    { return host(FullyEncoded).toLatin1(); }
    QT_DEPRECATED void setEncodedHost(const QByteArray &value)
    { setHost(QString::fromLatin1(value)); }

    QT_DEPRECATED QByteArray encodedPath() const
    { return path(FullyEncoded).toLatin1(); }
    QT_DEPRECATED void setEncodedPath(const QByteArray &value)
    { setPath(QString::fromLatin1(value)); }

    QT_DEPRECATED QByteArray encodedQuery() const
    { return toLatin1_helper(query(FullyEncoded)); }
    QT_DEPRECATED void setEncodedQuery(const QByteArray &value)
    { setQuery(QString::fromLatin1(value)); }

    QT_DEPRECATED QByteArray encodedFragment() const
    { return toLatin1_helper(fragment(FullyEncoded)); }
    QT_DEPRECATED void setEncodedFragment(const QByteArray &value)
    { setFragment(QString::fromLatin1(value)); }

    static QString fromAce(const QByteArray &);
    static QByteArray toAce(const QString &);
    static QStringList idnWhitelist();
    static void setIdnWhitelist(const QStringList &);

class Q_CORE_EXPORT QUrlQuery
    explicit QUrlQuery(const QUrl &url);
    explicit QUrlQuery(const QString &queryString);
    QUrlQuery(const QUrlQuery &other);
    QUrlQuery &operator=(const QUrlQuery &other);
    QUrlQuery &operator=(QUrlQuery &&other)
    { qSwap(d, other.d); return *this; }

    bool operator==(const QUrlQuery &other) const;
    bool operator!=(const QUrlQuery &other) const
    { return !(*this == other); }

    void swap(QUrlQuery &other) { qSwap(d, other.d); }

    bool isEmpty() const;
    bool isDetached() const;
    void clear();

    QString query(QUrl::ComponentFormattingOptions encoding = 
QUrl::PrettyDecoded) const;
    void setQuery(const QString &queryString);
    QString toString(QUrl::ComponentFormattingOptions encoding = 
QUrl::PrettyDecoded) const
    { return query(encoding); }

    void setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter);
    QChar queryValueDelimiter() const;
    QChar queryPairDelimiter() const;

    void setQueryItems(const QList<QPair<QString, QString> > &query);
    QList<QPair<QString, QString> > 
queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) 

    bool hasQueryItem(const QString &key) const;
    void addQueryItem(const QString &key, const QString &value);
    void removeQueryItem(const QString &key);
    QString queryItemValue(const QString &key, 
QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const;
    QStringList allQueryItemValues(const QString &key, 
QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const;
    void removeAllQueryItems(const QString &key);

    static QChar defaultQueryValueDelimiter();
    static QChar defaultQueryPairDelimiter();
Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
   Software Architect - Intel Open Source Technology Center
      PGP/GPG: 0x6EF45358; fingerprint:
      E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20111025/f20d5e97/attachment.sig>

More information about the Development mailing list