Commit 931627e8 authored by hjk's avatar hjk
Browse files

Core: add convenience functions to Core::Id.



These are meant to help the outphasing of the Id(QString) constructor
and generally split the interface into "persistent" and "non-persistent".

Change-Id: Id23f613c304e020044e4996448d68164725c898c
Reviewed-by: default avatarChristian Kandeler <christian.kandeler@digia.com>
parent 262b5b12
......@@ -43,9 +43,22 @@ namespace Core {
/*!
\class Core::Id
\brief The class Id encapsulates an identifier. It is used as a type-safe
helper class instead of a \c QString or \c QByteArray. The internal
representation of the id is assumed to be plain 7-bit-clean ASCII.
\brief The class Id encapsulates an identifier that is unique
within a specific running Qt Creator process.
\c{Core::Id} is used as facility to identify objects of interest
in a more typesafe and faster manner than a plain \c QString or
\c QByteArray would provide.
An id is internally represented as a 32 bit integer (its \c UID)
and associated with a be plain 7-bit-clean ASCII name used
for display and persistency.
Each plugin that is distributed as part of Qt Creator has a
private range of 10000 UIDs that are guaranteed to be unique.
Third party plugins are advised to construct ids from their
string representation.
*/
......@@ -97,7 +110,8 @@ struct IdCache : public QHash<StringHolder, int>
};
static int lastUid = 1000 * 1000;
static int firstUnusedId = Id::IdsPerPlugin * Id::ReservedPlugins;
static QHash<int, StringHolder> stringFromId;
static IdCache idFromString;
......@@ -107,7 +121,7 @@ static int theId(const char *str, int n = 0)
StringHolder sh(str, n);
int res = idFromString.value(sh, 0);
if (res == 0) {
res = ++lastUid;
res = firstUnusedId++;
sh.str = qstrdup(sh.str);
idFromString[sh] = res;
stringFromId[res] = sh;
......@@ -120,28 +134,133 @@ static int theId(const QByteArray &ba)
return theId(ba.constData(), ba.size());
}
/*!
\fn Core::Id(int uid)
\brief Constructs an id given a UID.
The UID is an integer value that is unique within the running
Qt Creator process.
It is the callers responsibility to ensure the uniqueness of
the passed integer. The recommended approach is to use
\c{registerId()} with an value taken from the plugin's
private range.
\sa registerId()
*/
/*!
Constructs an id given its associated name. The internal
representation will be unspecified, but consistent within a
Qt Creator process.
*/
Id::Id(const char *name)
: m_id(theId(name, 0))
{}
/*!
\overload
*/
Id::Id(const QByteArray &name)
: m_id(theId(name))
{}
/*!
\overload
\deprecated
*/
Id::Id(const QString &name)
: m_id(theId(name.toUtf8()))
{}
/*!
Returns an internal representation of the id.
*/
QByteArray Id::name() const
{
return stringFromId.value(m_id).str;
}
/*!
Returns a string representation of the id suitable
for UI display.
This should not be used to create a persistent version
of the Id, use \c{toSetting()} instead.
\sa fromString(), toSetting()
*/
QString Id::toString() const
{
return QString::fromUtf8(stringFromId.value(m_id).str);
}
/*!
Creates an id from a string representation.
This should not be used to handle a persistent version
of the Id, use \c{fromSetting()} instead.
\sa toString(), fromSetting()
*/
Id Id::fromString(const QString &name)
{
return Id(theId(name.toUtf8()));
}
/*!
Returns a persistent value representing the id which is
suitable to be stored in QSettings.
\sa fromSetting()
*/
QVariant Id::toSetting() const
{
return QVariant(QString::fromUtf8(stringFromId.value(m_id).str));
}
/*!
Reconstructs an id from a persistent value.
\sa toSetting()
*/
Id Id::fromSetting(const QVariant &variant)
{
const QByteArray ba = variant.toString().toUtf8();
return Id(theId(ba));
}
Id Id::withSuffix(Id id, int suffix)
{
const QByteArray ba = id.name() + QByteArray::number(suffix);
return Id(ba.constData());
}
Id Id::withSuffix(Id id, const char *suffix)
{
const QByteArray ba = id.name() + suffix;
return Id(ba.constData());
}
/*!
Associates a id with its uid and its string
representation.
The uid should be taken from the plugin's private range.
\sa fromSetting()
*/
void Id::registerId(int uid, const char *name)
{
StringHolder sh(name, 0);
......
......@@ -34,6 +34,7 @@
#include <QMetaType>
#include <QString>
#include <QVariant>
namespace Core {
......@@ -41,6 +42,8 @@ namespace Core {
class CORE_EXPORT Id
{
public:
enum { IdsPerPlugin = 10000, ReservedPlugins = 1000 };
Id() : m_id(0) {}
Id(int uid) : m_id(uid) {}
Id(const char *name);
......@@ -48,7 +51,8 @@ public:
// FIXME: Remove
explicit Id(const QString &name);
QByteArray name() const;
QString toString() const;
QString toString() const; // Avoid.
QVariant toSetting() const; // Good to use.
bool isValid() const { return m_id; }
bool operator==(Id id) const { return m_id == id.m_id; }
bool operator==(const char *name) const;
......@@ -58,6 +62,10 @@ public:
bool operator>(Id id) const { return m_id > id.m_id; }
int uniqueIdentifier() const { return m_id; }
static Id fromUniqueIdentifier(int uid) { return Id(uid); }
static Id fromString(const QString &str); // FIXME: avoid.
static Id fromSetting(const QVariant &variant); // Good to use.
static Id withSuffix(Id base, int suffix);
static Id withSuffix(Id base, const char *name);
static void registerId(int uid, const char *name);
private:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment