[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.
Questions:
- 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
kept?
- QUrlQuery does not keep the order of the items (it's kept in a hash). Is
the order important?
Observations:
- 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"))
class Q_CORE_EXPORT QUrl
{
public:
enum ParsingMode {
TolerantMode,
StrictMode
};
// 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 |
DecodeUnicode,
MostDecoded = PrettyDecoded | DecodeAllDelimiters
};
Q_DECLARE_FLAGS(ComponentFormattingOptions, ComponentFormattingOption)
#ifdef qdoc
Q_DECLARE_FLAGS(FormattingOptions, UrlFormattingOption)
#else
typedef QUrlTwoFlags<UrlFormattingOption, ComponentFormattingOption>
FormattingOptions;
#endif
QUrl();
QUrl(const QUrl ©);
QUrl &operator =(const QUrl ©);
#ifdef QT_NO_URL_CAST_FROM_STRING
explicit QUrl(const QString &url, ParsingMode mode = TolerantMode);
#else
QUrl(const QString &url, ParsingMode mode = TolerantMode);
QUrl &operator=(const QString &url);
#endif
#ifdef Q_COMPILER_RVALUE_REFS
QUrl(QUrl &&other) : d(0)
{ qSwap(d, other.d); }
inline QUrl &operator=(QUrl &&other)
{ qSwap(d, other.d); return *this; }
#endif
~QUrl();
inline void swap(QUrl &other) { qSwap(d, other.d); }
void setUrl(const QString &url, ParsingMode mode = TolerantMode);
QString url(FormattingOptions options = FormattingOptions(PrettyDecoded))
const;
QString toString(FormattingOptions options =
FormattingOptions(PrettyDecoded)) const;
QByteArray toEncoded(FormattingOptions options = FullyEncoded) const;
static QUrl fromEncoded(const QByteArray &url, ParsingMode mode =
TolerantMode);
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)
const;
void setUserInfo(const QString &userInfo);
QString userInfo(ComponentFormattingOptions options = PrettyDecoded)
const;
void setUserName(const QString &userName);
QString userName(ComponentFormattingOptions options = PrettyDecoded)
const;
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)
const;
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)
const;
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;
#if QT_DEPRECATED_SINCE(5,0)
QT_DEPRECATED static QString fromPercentEncoding(const QByteArray
&encoded)
{ 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 =
TolerantMode)
{ 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)); }
#endif
public:
static QString fromAce(const QByteArray &);
static QByteArray toAce(const QString &);
static QStringList idnWhitelist();
static void setIdnWhitelist(const QStringList &);
};
class Q_CORE_EXPORT QUrlQuery
{
public:
QUrlQuery();
explicit QUrlQuery(const QUrl &url);
explicit QUrlQuery(const QString &queryString);
QUrlQuery(const QUrlQuery &other);
QUrlQuery &operator=(const QUrlQuery &other);
#ifdef Q_COMPILER_RVALUE_REFS
QUrlQuery &operator=(QUrlQuery &&other)
{ qSwap(d, other.d); return *this; }
#endif
~QUrlQuery();
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)
const;
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