libQuotient
A Qt library for building matrix clients
Loading...
Searching...
No Matches
util.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2016 Kitsune Ral <kitsune-ral@users.sf.net>
2// SPDX-FileCopyrightText: 2019 Alexey Andreyev <aa13q@ya.ru>
3// SPDX-License-Identifier: LGPL-2.1-or-later
4
5#pragma once
6
8
9#include <QtCore/QDebug>
10#include <QtCore/QElapsedTimer>
11#include <QtCore/QFuture>
12#include <QtCore/QHashFunctions>
13#include <QtCore/QLatin1String>
14#include <QtCore/QScopedPointer>
15#include <QtCore/QUrl>
16
17#include <memory>
18#include <optional>
19#include <source_location>
20#include <unordered_map>
21
22#define DECL_DEPRECATED_ENUMERATOR(Deprecated, Recommended)
23 Deprecated Q_DECL_ENUMERATOR_DEPRECATED_X("Use " #Recommended) = Recommended
24
25/// \brief Copy an object with slicing
26///
27/// Unintended slicing is bad, which is why there's a C++ Core Guideline that
28/// basically says "don't slice, or if you do, make it explicit". Sonar and
29/// clang-tidy have warnings matching this guideline; unfortunately, those
30/// warnings trigger even when you have a dedicated method (as the guideline
31/// recommends) that makes a slicing copy.
32///
33/// This macro is meant for cases when slicing is intended: the static cast
34/// silences the static analysis warning, and the macro appearance itself makes
35/// it very clear that slicing is wanted here. It is made as a macro
36/// (not as a function template) to support the case of private inheritance
37/// in which a function template would not be able to cast to the private base
38/// (see Uri::toUrl() for an example of just that situation).
39#define SLICE(Object, ToType) ToType{static_cast<const ToType&>(Object)}
40
41namespace Quotient {
42
43namespace _impl {
44 template <typename S>
45 constexpr inline auto toUtf8(S&& s)
46 {
47 if constexpr (std::convertible_to<S, std::string_view>)
48 return std::string_view(std::forward<S>(s));
49 else if constexpr (std::convertible_to<S, QByteArray>)
50 return QByteArray(std::forward<S>(s));
51 else //if constexpr (std::convertible_to<S, QString>)
52 return QString(std::forward<S>(s)).toUtf8();
53 }
54}
55
56//! \brief q(Utf8)Printable that can handle more than just QStrings
57//!
58//! This macro accepts all kinds of string-like input, from const char* all the way to raw
59//! QStringBuilder constructs. It returns a `const char*` pointer to a UTF-8 string; if the original
60//! input was QChar/u16-based, it creates a temporary buffer to store the UTF-8 representation that
61//! is destroyed once the statement containing QUO_CSTR() is done (therefore, ALWAYS copy the result
62//! based on QUO_CSTR() contents if you need to store it).
63#define QUO_CSTR(StringConvertible_) std::data(::Quotient::_impl::toUtf8(StringConvertible_))
64
65inline bool alarmX(bool alarmCondition, const auto& msg, bool invertReturnValue = false,
66 [[maybe_unused]] std::source_location loc = std::source_location::current())
67{
68 if (alarmCondition) [[unlikely]] {
69 qt_assert_x(loc.function_name(), QUO_CSTR(msg), loc.file_name(), loc.line());
70 qCritical() << msg;
71 }
72 return alarmCondition != invertReturnValue;
73}
74
75//! \brief A negative assertion facility that can be put in an if statement
76//!
77//! Unlike most other assertion functions or macros, this doesn't collapse to no-op in Release
78//! builds; rather, it sends a critical level message to the log and returns true so that you could
79//! immediately return or do some other damage control for Release builds. Also unlike most other
80//! assertion functions, \p AlarmCondition is the condition for failure, not for health; in other
81//! words, \p Message is sent to logs (and, in Debug configuration, the assertion fails)
82//! if \p AlarmCondition holds, not the other way around.
83//!
84//! This macro is a trivial wrapper around alarmX(), provided for API uniformity with QUO_ALARM()
85#define QUO_ALARM_X(...) ::Quotient::alarmX(__VA_ARGS__)
86
87#define QUO_ALARM(...) ::Quotient::alarmX((__VA_ARGS__) ? true : false, "Alarm: " #__VA_ARGS__)
88
89//! Evaluate the boolean expression and, in Debug mode, assert it to be true
90#define QUO_CHECK(...)
91 ::Quotient::alarmX((__VA_ARGS__) ? false : true, "Failing expression: " #__VA_ARGS__, true)
92
93//! A substitute for QtFuture::makeReadyVoidFuture() for compatibility with Qt pre-6.6
95{
96#if QT_VERSION >= QT_VERSION_CHECK(6, 6, 0)
97 return QtFuture::makeReadyVoidFuture();
98#else
99 return QtFuture::makeReadyFuture<void>();
100#endif
101}
102
103//! A substitute for QtFuture::makeReadyValueFuture() for compatibility with Qt pre-6.6
104template <typename T>
105inline auto makeReadyValueFuture(T&& value)
106{
107#if QT_VERSION >= QT_VERSION_CHECK(6, 6, 0)
108 return QtFuture::makeReadyValueFuture(std::forward<T>(value));
109#else
110 return QtFuture::makeReadyFuture(std::forward<T>(value));
111#endif
112}
113
114inline namespace Literals { using namespace Qt::Literals; }
115
116/** A replica of std::find_first_of that returns a pair of iterators
117 *
118 * Convenient for cases when you need to know which particular "first of"
119 * [sFirst, sLast) has been found in [first, last).
120 */
121template <typename InputIt, typename ForwardIt>
122inline std::pair<InputIt, ForwardIt> findFirstOf(InputIt first, InputIt last,
123 ForwardIt sFirst,
124 ForwardIt sLast, auto pred)
125{
126 for (; first != last; ++first)
127 for (auto it = sFirst; it != sLast; ++it)
128 if (pred(*first, *it))
129 return { first, it };
130
131 return { last, sLast };
132}
133
134//! \brief Common custom deleter for std::unique_ptr and QScopedPointer
135//!
136//! Since Qt 6, this is merely an alias for QScopedPointerDeleteLater (which is suitable
137//! for std::unique_ptr too).
139
140template <std::derived_from<QObject> T>
142
143//! \brief An owning implementation pointer
144//!
145//! This is basically std::unique_ptr<> to hold your pimpl's but without having
146//! to define default constructors/operator=() out of line.
147//! Thanks to https://oliora.github.io/2015/12/29/pimpl-and-rule-of-zero.html
148//! for inspiration
149template <typename ImplType, typename TypeToDelete = ImplType>
150using ImplPtr = std::unique_ptr<ImplType, void (*)(TypeToDelete*)>;
151
152// Why this works (see also the link above): because this defers the moment
153// of requiring sizeof of ImplType to the place where makeImpl is invoked
154// (which is located, necessarily, in the .cpp file after ImplType definition).
155// The stock unique_ptr deleter (std::default_delete) normally needs sizeof
156// at the same spot - as long as you defer definition of the owning type
157// constructors and operator='s to the .cpp file as well. Which means you
158// have to explicitly declare and define them (even if with = default),
159// formally breaking the rule of zero; informally, just adding boilerplate code.
160// The custom deleter itself is instantiated at makeImpl invocation - there's
161// no way earlier to even know how ImplType will be deleted and whether that
162// will need sizeof(ImplType) earlier. In theory it's a tad slower because
163// the deleter is called by the pointer; however, the difference will not
164// be noticeable (if exist at all) for any class with non-trivial contents.
165
166//! \brief make_unique for ImplPtr
167//!
168//! Since std::make_unique is not compatible with ImplPtr, this should be used
169//! in constructors of frontend classes to create implementation instances.
170template <typename ImplType, typename TypeToDelete = ImplType, typename... ArgTs>
171inline ImplPtr<ImplType, TypeToDelete> makeImpl(ArgTs&&... args)
172{
173 return ImplPtr<ImplType, TypeToDelete> {
174 new ImplType{std::forward<ArgTs>(args)...},
175 [](TypeToDelete* impl) { delete impl; }
176 };
177}
178
179template <typename ImplType, typename TypeToDelete = ImplType>
180inline ImplPtr<ImplType, TypeToDelete> acquireImpl(ImplType* from)
181{
182 return ImplPtr<ImplType, TypeToDelete> { from, [](TypeToDelete* impl) {
183 delete impl;
184 } };
185}
186
187template <typename ImplType, typename TypeToDelete = ImplType>
189{
190 return { nullptr, [](TypeToDelete*) { /* nullptr doesn't need deletion */ } };
191}
192
193template <typename T>
195 size_t (*destructor)(T*);
196
197 void operator()(T* toDelete)
198 {
199 destructor(toDelete);
200 delete[] reinterpret_cast<std::byte*>(toDelete);
201 }
202};
203
204//! \brief An owning pointer to a C structure
205//!
206//! This is intented to ease lifecycle management of Olm structures.
207//! \sa makeCStruct
208template <typename T>
209using CStructPtr = std::unique_ptr<T, CStructDeleter<T>>;
210
211//! \brief Create a C structure with pre-programmed deletion logic
212//!
213//! This facility function creates a CStructPtr that owns the pointer returned
214//! by \p constructor. The memory passed to \p constructor is allocated
215//! as an array of bytes; the size of that array is determined by calling
216//! \p sizeFn. Finally, since the returned pointer is owning, it also stores
217//! the corresponding CStructDeleter instance; when called at destruction of
218//! the owning pointer, this deleter first calls \p destructor passing the
219//! original C pointer returned by \p constructor; and then deletes the
220//! allocated array of bytes.
221template <typename T>
222inline auto makeCStruct(T* (*constructor)(void*), size_t (*sizeFn)(),
223 auto destructor)
224{
225 return CStructPtr<T>{ constructor(new std::byte[sizeFn()]), { destructor } };
226}
227
228//! \brief Multiplex several functors in one
229//!
230//! This is a well-known trick to wrap several lambdas into a single functor
231//! class that can be passed to std::visit.
232//! \sa https://en.cppreference.com/w/cpp/utility/variant/visit
233template <typename... FunctorTs>
234struct Overloads : FunctorTs... {
235 using FunctorTs::operator()...;
236};
237
238template <typename... FunctorTs>
239Overloads(FunctorTs&&...) -> Overloads<FunctorTs...>;
240
241/** Convert what looks like a URL or a Matrix ID to an HTML hyperlink */
242QUOTIENT_API void linkifyUrls(QString& htmlEscapedText);
243
244/** Sanitize the text before showing in HTML
245 *
246 * This does toHtmlEscaped() and removes Unicode BiDi marks.
247 */
249
250/** Pretty-print plain text into HTML
251 *
252 * This includes HTML escaping of <,>,",& and calling linkifyUrls()
253 */
255
256/** Return a path to cache directory after making sure that it exists
257 *
258 * The returned path has a trailing slash, clients don't need to append it.
259 * \param dirName path to cache directory relative to the standard cache path
260 */
262
263/** Hue color component of based of the hash of the string.
264 *
265 * The implementation is based on XEP-0392:
266 * https://xmpp.org/extensions/xep-0392.html
267 * Naming and range are the same as QColor's hueF method:
268 * https://doc.qt.io/qt-5/qcolor.html#integer-vs-floating-point-precision
269 */
271
272/** Extract the serverpart from MXID */
274
279
280// QDebug manipulators
281
282//! \brief QDebug manipulator to setup the stream for JSON output
283//!
284//! Originally made to encapsulate the change in QDebug behavior in Qt 5.4
285//! and the respective addition of QDebug::noquote().
286//! Together with the operator<<() helper, the proposed usage is
287//! (similar to std:: I/O manipulators):
288//! `qCDebug(MAIN) << formatJson << json_object; // (QJsonObject etc.)`
289inline QDebug formatJson(QDebug dbg) { return dbg.noquote(); }
290
291//! Suppress full qualification of enums/QFlags when logging
292inline QDebug terse(QDebug dbg)
293{
294 return dbg.verbosity(QDebug::MinimumVerbosity);
295}
296
298#ifdef PROFILER_LOG_USECS
300#else
301 200
302#endif
303 * 1000;
304} // namespace Quotient
305
306//! \brief A helper operator for QDebug manipulators, e.g. formatJson
307//!
308//! \param dbg to output the json to
309//! \param manipFn a QDebug manipulator
310//! \return a copy of dbg that has its mode altered by manipFn
311inline QDebug operator<<(QDebug dbg, std::invocable<QDebug> auto manipFn)
312{
313 return std::invoke(manipFn, dbg);
314}
315
316inline QDebug operator<<(QDebug dbg, QElapsedTimer et)
317{
318 // NOLINTNEXTLINE(bugprone-integer-division)
319 dbg << static_cast<double>(et.nsecsElapsed() / 1000) / 1000
320 << "ms"; // Show in ms with 3 decimal digits precision
321 return dbg;
322}
323
324namespace Quotient {
325//! \brief Lift an operation into dereferenceable types (std::optional or pointers)
326//!
327//! This is a more generic version of std::optional::and_then() that accepts an arbitrary number of
328//! arguments of any type that is dereferenceable (i.e. unary operator*() can be applied to it) and
329//! (explicitly or implicitly) convertible to bool. This allows to streamline checking for
330//! nullptr/nullopt before applying the operation on the underlying types. \p fn is only invoked if
331//! all \p args are "truthy" (i.e. <tt>(... && bool(args)) == true</tt>).
332//! \param fn A callable that should accept the types stored inside optionals/pointers passed in
333//! \p args (NOT optionals/pointers themselves; they are unwrapped)
334//! \return Always an optional: if \p fn returns another type, lift() wraps it in std::optional;
335//! if \p fn returns std::optional, that return value (or std::nullopt) is returned as is.
336template <typename FnT>
337inline auto lift(FnT&& fn, auto&&... args)
338{
339 if constexpr (std::is_void_v<std::invoke_result_t<FnT, decltype(*args)...>>) {
340 if ((... && bool(args)))
341 std::invoke(std::forward<FnT>(fn), *args...);
342 } else
343 return (... && bool(args))
344 ? std::optional(std::invoke(std::forward<FnT>(fn), *args...))
345 : std::nullopt;
346}
347
348//! \brief Merge the value from an optional
349//!
350//! Assigns the value stored at \p rhs to \p lhs if, and only if, \p rhs is not omitted and
351//! `lhs != *rhs`. \p lhs can be either an optional or an ordinary variable.
352//! \return `true` if \p rhs is not omitted and the \p lhs value was different, in other words,
353//! if \p lhs has changed; `false` otherwise
354template <typename T1, typename T2>
355 requires std::is_assignable_v<T1&, const T2&>
356constexpr inline bool merge(T1& lhs, const std::optional<T2>& rhs)
357{
358 if (!rhs || lhs == *rhs)
359 return false;
360 lhs = *rhs;
361 return true;
362}
363
364//! \brief Merge structure-like types
365//!
366//! Merges fields in \p lhs from counterparts in \p rhs. The list of fields to merge is passed
367//! in additional parameters (\p fields). E.g.:
368//! \codeline mergeStruct(struct1, struct2, &Struct::field1, &Struct::field2, &Struct::field3)
369//! \return the number of fields in \p lhs that were changed
370template <typename StructT>
371constexpr inline size_t mergeStruct(StructT& lhs, const StructT& rhs, const auto... fields)
372{
373 return ((... + static_cast<size_t>(merge(lhs.*fields, rhs.*fields))));
374}
375
376// These are meant to eventually become separate classes derived from QString (or perhaps
377// QByteArray?), with their own construction and validation logic; for now they are just aliases
378// for QString to make numerous IDs at least semantically different in the code.
379
383
384QUOTIENT_API bool isGuestUserId(const UserId& uId);
385
390
392};
393} // namespace Quotient
QUOTIENT_API bool isGuestUserId(const UserId &uId)
auto lift(FnT &&fn, auto &&... args)
Lift an operation into dereferenceable types (std::optional or pointers)
Definition util.h:337
auto makeReadyValueFuture(T &&value)
A substitute for QtFuture::makeReadyValueFuture() for compatibility with Qt pre-6....
Definition util.h:105
QUOTIENT_API int patchVersion()
QUOTIENT_API int minorVersion()
QDebug formatJson(QDebug dbg)
QDebug manipulator to setup the stream for JSON output.
Definition util.h:289
std::pair< InputIt, ForwardIt > findFirstOf(InputIt first, InputIt last, ForwardIt sFirst, ForwardIt sLast, auto pred)
Definition util.h:122
Overloads(FunctorTs &&...) -> Overloads< FunctorTs... >
constexpr qint64 ProfilerMinNsecs
Definition util.h:297
constexpr ImplPtr< ImplType, TypeToDelete > ZeroImpl()
Definition util.h:188
QUOTIENT_API void linkifyUrls(QString &htmlEscapedText)
bool alarmX(bool alarmCondition, const auto &msg, bool invertReturnValue=false, std::source_location loc=std::source_location::current())
Definition util.h:65
constexpr bool merge(T1 &lhs, const std::optional< T2 > &rhs)
Merge the value from an optional.
Definition util.h:356
constexpr size_t mergeStruct(StructT &lhs, const StructT &rhs, const auto... fields)
Merge structure-like types.
Definition util.h:371
ImplPtr< ImplType, TypeToDelete > makeImpl(ArgTs &&... args)
make_unique for ImplPtr
Definition util.h:171
QDebug terse(QDebug dbg)
Suppress full qualification of enums/QFlags when logging.
Definition util.h:292
auto makeReadyVoidFuture()
A substitute for QtFuture::makeReadyVoidFuture() for compatibility with Qt pre-6.6.
Definition util.h:94
auto makeCStruct(T *(*constructor)(void *), size_t(*sizeFn)(), auto destructor)
Create a C structure with pre-programmed deletion logic.
Definition util.h:222
QUOTIENT_API int majorVersion()
ImplPtr< ImplType, TypeToDelete > acquireImpl(ImplType *from)
Definition util.h:180
#define QUOTIENT_API
void operator()(T *toDelete)
Definition util.h:197
Multiplex several functors in one.
Definition util.h:234
QDebug operator<<(QDebug dbg, std::invocable< QDebug > auto manipFn)
A helper operator for QDebug manipulators, e.g. formatJson.
Definition util.h:311
#define QUO_CSTR(StringConvertible_)
q(Utf8)Printable that can handle more than just QStrings
Definition util.h:63