KI18n 5.109.0
Public Member Functions | List of all members
KLazyLocalizedString

Lazy-initialized variant of KLocalizedString. More...

#include <KLazyLocalizedString>

Public Member Functions

constexpr KLazyLocalizedString ()=default
 Construct an empty message.
 
KLocalizedString ignoreMarkup () const
 Do not resolve KUIT markup.
 
KLocalizedString inContext (const QString &key, const QString &value) const
 Add dynamic context to the message.
 
constexpr bool isEmpty () const
 Check whether the message is empty.
 
 operator KLocalizedString () const
 Convert to a KLocalizedString to actually perform the translation and obtain a concrete localized string.
 
KLocalizedString relaxSubs () const
 Relax matching between placeholders and arguments.
 
KLocalizedString subs (const KLocalizedString &a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const
 Substitute another KLocalizedString into the message.
 
KLocalizedString subs (const QString &a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const
 Substitute a QString argument into the message.
 
KLocalizedString subs (double a, int fieldWidth=0, char format='g', int precision=-1, QChar fillChar=QLatin1Char(' ')) const
 Substitute a double argument into the message.
 
KLocalizedString subs (int a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
 Substitute an int argument into the message.
 
KLocalizedString subs (long a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
 Substitute a long argument into the message.
 
KLocalizedString subs (QChar a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const
 Substitute a QChar argument into the message.
 
KLocalizedString subs (qlonglong a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
 Substitute a long long argument into the message.
 
KLocalizedString subs (qulonglong a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
 Substitute an unsigned long long argument into the message.
 
KLocalizedString subs (uint a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
 Substitute an unsigned int argument into the message.
 
KLocalizedString subs (ulong a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
 Substitute an unsigned long argument into the message.
 
QString toString () const
 Finalize the translation.
 
QString toString (const char *domain) const
 Like toString(), but look for translation in the given domain.
 
QString toString (const QStringList &languages) const
 Like toString(), but look for translation only in given languages.
 
QString toString (Kuit::VisualFormat format) const
 Like toString(), but resolve KUIT markup into given visual format.
 
constexpr const char * untranslatedText () const
 Returns the raw untranslated text as passed to kli18n*.
 
KLocalizedString withDomain (const char *domain) const
 Indicate to look for translation in the given domain.
 
KLocalizedString withFormat (Kuit::VisualFormat format) const
 Indicate to resolve KUIT markup into given visual format.
 
KLocalizedString withLanguages (const QStringList &languages) const
 Indicate to look for translation only in given languages.
 

Detailed Description

Lazy-initialized variant of KLocalizedString.

This is a safer replacement for the I18N_NOOP set of macros and allows marking strings for extraction without runtime-initializing KLocalizedString instances, for storing in static data tables.

Instances of KLazyLocalizedString are not created directly, unless they should be empty. Instead they have to be obtained via the kli18n* functions (similar to KLocalizedString and the ki18n* functions).

Example usage in a static message table:

struct {
MyClass::VehicleType type;
} static constexpr const vehicle_msg_table[] = {
{ MyClass::Train, kli18np("%1 train", "%1 trains") },
{ MyClass::Bus, kli18ncp("the vehicle, not the USB one", "%1 bus", "%1 buses") },
...
};
...
const auto it = std::find_if(std::begin(vehicle_msg_table), std::end(vehicle_msg_table), [vehicleType](const auto &m) { return m.type == vehicleType; });
QString translatedMessage = (*it).msg.subs(vehicleCount).toString();
Lazy-initialized variant of KLocalizedString.
Definition klazylocalizedstring.h:51
KLocalizedString subs(int a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const
Substitute an int argument into the message.
Definition klazylocalizedstring.h:207
friend constexpr KLazyLocalizedString kli18ncp(const char(&context)[ContextSize], const char(&singular)[SingularSize], const char(&plural)[PluralSize])
Mark the string singular and plural with context for extraction.
Definition klazylocalizedstring.h:494
QString toString() const
Finalize the translation.
Note
KLazyLocalizedString is primarily meant for storage in e.g. message tables, not for use in API, especially not across translation domains. This is due to it not carrying the translation domain in which it was created, but using the active translation domain at the point of converting to a KLocalizedString.
Since
5.89

Constructor & Destructor Documentation

◆ KLazyLocalizedString()

constexpr KLazyLocalizedString::KLazyLocalizedString ( )
inlineconstexprdefault

Construct an empty message.

Direct construction is used when e.g. a KLazyLocalizedString field in a data table needs to be set, but there is not message to be used. Directly constructed instances are not valid for finalization by toString methods.

See also
isEmpty

Member Function Documentation

◆ ignoreMarkup()

KLocalizedString KLazyLocalizedString::ignoreMarkup ( ) const
inline

Do not resolve KUIT markup.

If the message is markup-aware (constructed by one of *xi18n* calls), this function can be used to make it non-markup-aware. This may be useful for debugging markup.

Returns
updated KLocalizedString

◆ inContext()

KLocalizedString KLazyLocalizedString::inContext ( const QString &  key,
const QString &  value 
) const
inline

Add dynamic context to the message.

See dyn_ctxt for use cases.

Parameters
keycontext key
valuecontext value
Returns
updated KLocalizedString

◆ isEmpty()

constexpr bool KLazyLocalizedString::isEmpty ( ) const
inlineconstexpr

Check whether the message is empty.

The message is considered empty if the object was constructed via the default constructor.

Empty messages are not valid for finalization. The behavior of calling toString() on them is undefined. In debug mode, an error mark may appear in the returned string.

Returns
true if the message is empty, false otherwise

◆ operator KLocalizedString()

KLazyLocalizedString::operator KLocalizedString ( ) const
inline

Convert to a KLocalizedString to actually perform the translation and obtain a concrete localized string.

The translation domain active at this point will be used. This means this has to be called in the same translation domain the corresponding kli18n call is in.

◆ relaxSubs()

KLocalizedString KLazyLocalizedString::relaxSubs ( ) const
inline

Relax matching between placeholders and arguments.

Normally the placeholders should start from %1 and have no gaps, and on finalization there must be exactly as many arguments supplied through subs methods as there are unique plaecholders. If this is not satisfied, in debug mode warnings are printed and the finalized string may contain error marks.

This method relaxes the placeholder-argument matching, such that there must only be an argument available for every present unique placeholder (taking placeholder numbers to be 1-based indices into the argument list). This can come useful in some situations.

Returns
updated KLocalizedString

◆ subs() [1/10]

KLocalizedString KLazyLocalizedString::subs ( const KLocalizedString a,
int  fieldWidth = 0,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute another KLocalizedString into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [2/10]

KLocalizedString KLazyLocalizedString::subs ( const QString &  a,
int  fieldWidth = 0,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute a QString argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [3/10]

KLocalizedString KLazyLocalizedString::subs ( double  a,
int  fieldWidth = 0,
char  format = 'g',
int  precision = -1,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute a double argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
formattype of floating point formatting, like in QString::arg
precisionnumber of digits after the decimal separator
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [4/10]

KLocalizedString KLazyLocalizedString::subs ( int  a,
int  fieldWidth = 0,
int  base = 10,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute an int argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
basethe radix used to represent the number as a string. Valid values range from 2 to 36
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [5/10]

KLocalizedString KLazyLocalizedString::subs ( long  a,
int  fieldWidth = 0,
int  base = 10,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute a long argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
basethe radix used to represent the number as a string. Valid values range from 2 to 36
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [6/10]

KLocalizedString KLazyLocalizedString::subs ( QChar  a,
int  fieldWidth = 0,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute a QChar argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [7/10]

KLocalizedString KLazyLocalizedString::subs ( qlonglong  a,
int  fieldWidth = 0,
int  base = 10,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute a long long argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
basethe radix used to represent the number as a string. Valid values range from 2 to 36
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [8/10]

KLocalizedString KLazyLocalizedString::subs ( qulonglong  a,
int  fieldWidth = 0,
int  base = 10,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute an unsigned long long argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
basethe radix used to represent the number as a string. Valid values range from 2 to 36
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [9/10]

KLocalizedString KLazyLocalizedString::subs ( uint  a,
int  fieldWidth = 0,
int  base = 10,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute an unsigned int argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
basethe radix used to represent the number as a string. Valid values range from 2 to 36
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ subs() [10/10]

KLocalizedString KLazyLocalizedString::subs ( ulong  a,
int  fieldWidth = 0,
int  base = 10,
QChar  fillChar = QLatin1Char(' ') 
) const
inline

Substitute an unsigned long argument into the message.

Parameters
athe argument
fieldWidthwidth of the formatted field, padded by spaces. Positive value aligns right, negative aligns left
basethe radix used to represent the number as a string. Valid values range from 2 to 36
fillCharthe character used to fill up the empty places when field width is greater than argument width
Returns
updated KLocalizedString

◆ toString() [1/4]

QString KLazyLocalizedString::toString ( ) const
inline

Finalize the translation.

Creates translated QString. If the string has placeholders, make sure to call instead KLazyLocalizedString::subs and further KLocalizedString::subs methods before finalizing. Translated text is searched for based on the global locale.

Returns
finalized translation

◆ toString() [2/4]

QString KLazyLocalizedString::toString ( const char *  domain) const
inline

Like toString(), but look for translation in the given domain.

Parameters
domainthe translation domain
Returns
finalized translation

◆ toString() [3/4]

QString KLazyLocalizedString::toString ( const QStringList &  languages) const
inline

Like toString(), but look for translation only in given languages.

Given languages override languages defined by the global locale. If languages is empty, original message is returned.

Parameters
languageslist of language codes (by decreasing priority)
Returns
finalized translation

◆ toString() [4/4]

QString KLazyLocalizedString::toString ( Kuit::VisualFormat  format) const
inline

Like toString(), but resolve KUIT markup into given visual format.

Given visual format overrides that implied by the context UI marker. If the message is not markup-aware, this is same as toString().

Parameters
formatthe target visual format
Returns
finalized translation

◆ untranslatedText()

constexpr const char * KLazyLocalizedString::untranslatedText ( ) const
inlineconstexpr

Returns the raw untranslated text as passed to kli18n*.

◆ withDomain()

KLocalizedString KLazyLocalizedString::withDomain ( const char *  domain) const
inline

Indicate to look for translation in the given domain.

Parameters
domainthe translation domain
Returns
updated KLocalizedString

◆ withFormat()

KLocalizedString KLazyLocalizedString::withFormat ( Kuit::VisualFormat  format) const
inline

Indicate to resolve KUIT markup into given visual format.

If the message is not markup-aware, this has no effect.

Parameters
formatthe target visual format
Returns
updated KLocalizedString

◆ withLanguages()

KLocalizedString KLazyLocalizedString::withLanguages ( const QStringList &  languages) const
inline

Indicate to look for translation only in given languages.

Parameters
languageslist of language codes (by decreasing priority)
Returns
updated KLocalizedString