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
94[[deprecated("Use QtFuture::makeReadyVoidFuture() directly")]]
96{
97 return QtFuture::makeReadyVoidFuture();
98}
99
100//! A substitute for QtFuture::makeReadyValueFuture() for compatibility with Qt pre-6.6
101template <typename T>
102[[deprecated("Use QtFuture::makeReadyValueFuture() directly")]]
103inline auto makeReadyValueFuture(T&& value)
104{
105 return QtFuture::makeReadyValueFuture(std::forward<T>(value));
106}
107
108inline namespace Literals { using namespace Qt::Literals; }
109
110/** A replica of std::find_first_of that returns a pair of iterators
111 *
112 * Convenient for cases when you need to know which particular "first of"
113 * [sFirst, sLast) has been found in [first, last).
114 */
115template <typename InputIt, typename ForwardIt>
116inline std::pair<InputIt, ForwardIt> findFirstOf(InputIt first, InputIt last,
117 ForwardIt sFirst,
118 ForwardIt sLast, auto pred)
119{
120 for (; first != last; ++first)
121 for (auto it = sFirst; it != sLast; ++it)
122 if (pred(*first, *it))
123 return { first, it };
124
125 return { last, sLast };
126}
127
128//! \brief Common custom deleter for std::unique_ptr and QScopedPointer
129//!
130//! Since Qt 6, this is merely an alias for QScopedPointerDeleteLater (which is suitable
131//! for std::unique_ptr too).
133
134template <std::derived_from<QObject> T>
136
137//! \brief An owning implementation pointer
138//!
139//! This is basically std::unique_ptr<> to hold your pimpl's but without having
140//! to define default constructors/operator=() out of line.
141//! Thanks to https://oliora.github.io/2015/12/29/pimpl-and-rule-of-zero.html
142//! for inspiration
143template <typename ImplType, typename TypeToDelete = ImplType>
144using ImplPtr = std::unique_ptr<ImplType, void (*)(TypeToDelete*)>;
145
146// Why this works (see also the link above): because this defers the moment
147// of requiring sizeof of ImplType to the place where makeImpl is invoked
148// (which is located, necessarily, in the .cpp file after ImplType definition).
149// The stock unique_ptr deleter (std::default_delete) normally needs sizeof
150// at the same spot - as long as you defer definition of the owning type
151// constructors and operator='s to the .cpp file as well. Which means you
152// have to explicitly declare and define them (even if with = default),
153// formally breaking the rule of zero; informally, just adding boilerplate code.
154// The custom deleter itself is instantiated at makeImpl invocation - there's
155// no way earlier to even know how ImplType will be deleted and whether that
156// will need sizeof(ImplType) earlier. In theory it's a tad slower because
157// the deleter is called by the pointer; however, the difference will not
158// be noticeable (if exist at all) for any class with non-trivial contents.
159
160//! \brief make_unique for ImplPtr
161//!
162//! Since std::make_unique is not compatible with ImplPtr, this should be used
163//! in constructors of frontend classes to create implementation instances.
164template <typename ImplType, typename TypeToDelete = ImplType, typename... ArgTs>
165inline ImplPtr<ImplType, TypeToDelete> makeImpl(ArgTs&&... args)
166{
167 return ImplPtr<ImplType, TypeToDelete> {
168 new ImplType{std::forward<ArgTs>(args)...},
169 [](TypeToDelete* impl) { delete impl; }
170 };
171}
172
173template <typename ImplType, typename TypeToDelete = ImplType>
174inline ImplPtr<ImplType, TypeToDelete> acquireImpl(ImplType* from)
175{
176 return ImplPtr<ImplType, TypeToDelete> { from, [](TypeToDelete* impl) {
177 delete impl;
178 } };
179}
180
181template <typename ImplType, typename TypeToDelete = ImplType>
183{
184 return { nullptr, [](TypeToDelete*) { /* nullptr doesn't need deletion */ } };
185}
186
187template <typename T>
189 size_t (*destructor)(T*);
190
191 void operator()(T* toDelete)
192 {
193 destructor(toDelete);
194 delete[] reinterpret_cast<std::byte*>(toDelete);
195 }
196};
197
198//! \brief An owning pointer to a C structure
199//!
200//! This is intented to ease lifecycle management of Olm structures.
201//! \sa makeCStruct
202template <typename T>
203using CStructPtr = std::unique_ptr<T, CStructDeleter<T>>;
204
205//! \brief Create a C structure with pre-programmed deletion logic
206//!
207//! This facility function creates a CStructPtr that owns the pointer returned
208//! by \p constructor. The memory passed to \p constructor is allocated
209//! as an array of bytes; the size of that array is determined by calling
210//! \p sizeFn. Finally, since the returned pointer is owning, it also stores
211//! the corresponding CStructDeleter instance; when called at destruction of
212//! the owning pointer, this deleter first calls \p destructor passing the
213//! original C pointer returned by \p constructor; and then deletes the
214//! allocated array of bytes.
215template <typename T>
216inline auto makeCStruct(T* (*constructor)(void*), size_t (*sizeFn)(),
217 auto destructor)
218{
219 return CStructPtr<T>{ constructor(new std::byte[sizeFn()]), { destructor } };
220}
221
222//! \brief Multiplex several functors in one
223//!
224//! This is a well-known trick to wrap several lambdas into a single functor
225//! class that can be passed to std::visit.
226//! \sa https://en.cppreference.com/w/cpp/utility/variant/visit
227template <typename... FunctorTs>
228struct Overloads : FunctorTs... {
229 using FunctorTs::operator()...;
230};
231
232template <typename... FunctorTs>
233Overloads(FunctorTs&&...) -> Overloads<FunctorTs...>;
234
235/** Convert what looks like a URL or a Matrix ID to an HTML hyperlink */
236QUOTIENT_API void linkifyUrls(QString& htmlEscapedText);
237
238/** Sanitize the text before showing in HTML
239 *
240 * This does toHtmlEscaped() and removes Unicode BiDi marks.
241 */
243
244/** Pretty-print plain text into HTML
245 *
246 * This includes HTML escaping of <,>,",& and calling linkifyUrls()
247 */
249
250/** Return a path to cache directory after making sure that it exists
251 *
252 * The returned path has a trailing slash, clients don't need to append it.
253 * \param dirName path to cache directory relative to the standard cache path
254 */
256
257/** Hue color component of based of the hash of the string.
258 *
259 * The implementation is based on XEP-0392:
260 * https://xmpp.org/extensions/xep-0392.html
261 * Naming and range are the same as QColor's hueF method:
262 * https://doc.qt.io/qt-5/qcolor.html#integer-vs-floating-point-precision
263 */
265
266/** Extract the serverpart from MXID */
268
273
274// QDebug manipulators
275
276//! \brief QDebug manipulator to setup the stream for JSON output
277//!
278//! Originally made to encapsulate the change in QDebug behavior in Qt 5.4
279//! and the respective addition of QDebug::noquote().
280//! Together with the operator<<() helper, the proposed usage is
281//! (similar to std:: I/O manipulators):
282//! `qCDebug(MAIN) << formatJson << json_object; // (QJsonObject etc.)`
283inline QDebug formatJson(QDebug dbg) { return dbg.noquote(); }
284
285//! Suppress full qualification of enums/QFlags when logging
286inline QDebug terse(QDebug dbg)
287{
288 return dbg.verbosity(QDebug::MinimumVerbosity);
289}
290
292#ifdef PROFILER_LOG_USECS
294#else
295 200
296#endif
297 * 1000;
298} // namespace Quotient
299
300//! \brief A helper operator for QDebug manipulators, e.g. formatJson
301//!
302//! \param dbg to output the json to
303//! \param manipFn a QDebug manipulator
304//! \return a copy of dbg that has its mode altered by manipFn
305inline QDebug operator<<(QDebug dbg, std::invocable<QDebug> auto manipFn)
306{
307 return std::invoke(manipFn, dbg);
308}
309
310inline QDebug operator<<(QDebug dbg, QElapsedTimer et)
311{
312 // NOLINTNEXTLINE(bugprone-integer-division)
313 dbg << static_cast<double>(et.nsecsElapsed() / 1000) / 1000
314 << "ms"; // Show in ms with 3 decimal digits precision
315 return dbg;
316}
317
318namespace Quotient {
319//! \brief Lift an operation into dereferenceable types (std::optional or pointers)
320//!
321//! This is a more generic version of std::optional::and_then() that accepts an arbitrary number of
322//! arguments of any type that is dereferenceable (i.e. unary operator*() can be applied to it) and
323//! (explicitly or implicitly) convertible to bool. This allows to streamline checking for
324//! nullptr/nullopt before applying the operation on the underlying types. \p fn is only invoked if
325//! all \p args are "truthy" (i.e. <tt>(... && bool(args)) == true</tt>).
326//! \param fn A callable that should accept the types stored inside optionals/pointers passed in
327//! \p args (NOT optionals/pointers themselves; they are unwrapped)
328//! \return Always an optional: if \p fn returns another type, lift() wraps it in std::optional;
329//! if \p fn returns std::optional, that return value (or std::nullopt) is returned as is.
330template <typename FnT>
331inline auto lift(FnT&& fn, auto&&... args)
332{
333 if constexpr (std::is_void_v<std::invoke_result_t<FnT, decltype(*args)...>>) {
334 if ((... && bool(args)))
335 std::invoke(std::forward<FnT>(fn), *args...);
336 } else
337 return (... && bool(args))
338 ? std::optional(std::invoke(std::forward<FnT>(fn), *args...))
339 : std::nullopt;
340}
341
342//! \brief Merge the value from an optional
343//!
344//! Assigns the value stored at \p rhs to \p lhs if, and only if, \p rhs is not omitted and
345//! `lhs != *rhs`. \p lhs can be either an optional or an ordinary variable.
346//! \return `true` if \p rhs is not omitted and the \p lhs value was different, in other words,
347//! if \p lhs has changed; `false` otherwise
348template <typename T1, typename T2>
349 requires std::is_assignable_v<T1&, const T2&>
350constexpr inline bool merge(T1& lhs, const std::optional<T2>& rhs)
351{
352 if (!rhs || lhs == *rhs)
353 return false;
354 lhs = *rhs;
355 return true;
356}
357
358//! \brief Merge structure-like types
359//!
360//! Merges fields in \p lhs from counterparts in \p rhs. The list of fields to merge is passed
361//! in additional parameters (\p fields). E.g.:
362//! \codeline mergeStruct(struct1, struct2, &Struct::field1, &Struct::field2, &Struct::field3)
363//! \return the number of fields in \p lhs that were changed
364template <typename StructT>
365constexpr inline size_t mergeStruct(StructT& lhs, const StructT& rhs, const auto... fields)
366{
367 return ((... + static_cast<size_t>(merge(lhs.*fields, rhs.*fields))));
368}
369
370// These are meant to eventually become separate classes derived from QString (or perhaps
371// QByteArray?), with their own construction and validation logic; for now they are just aliases
372// for QString to make numerous IDs at least semantically different in the code.
373
377
378QUOTIENT_API bool isGuestUserId(const UserId& uId);
379
384
386};
387} // 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:331
auto makeReadyValueFuture(T &&value)
A substitute for QtFuture::makeReadyValueFuture() for compatibility with Qt pre-6....
Definition util.h:103
QUOTIENT_API int patchVersion()
QUOTIENT_API int minorVersion()
QDebug formatJson(QDebug dbg)
QDebug manipulator to setup the stream for JSON output.
Definition util.h:283
std::pair< InputIt, ForwardIt > findFirstOf(InputIt first, InputIt last, ForwardIt sFirst, ForwardIt sLast, auto pred)
Definition util.h:116
Overloads(FunctorTs &&...) -> Overloads< FunctorTs... >
constexpr qint64 ProfilerMinNsecs
Definition util.h:291
constexpr ImplPtr< ImplType, TypeToDelete > ZeroImpl()
Definition util.h:182
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:350
constexpr size_t mergeStruct(StructT &lhs, const StructT &rhs, const auto... fields)
Merge structure-like types.
Definition util.h:365
ImplPtr< ImplType, TypeToDelete > makeImpl(ArgTs &&... args)
make_unique for ImplPtr
Definition util.h:165
QDebug terse(QDebug dbg)
Suppress full qualification of enums/QFlags when logging.
Definition util.h:286
auto makeReadyVoidFuture()
A substitute for QtFuture::makeReadyVoidFuture() for compatibility with Qt pre-6.6.
Definition util.h:95
auto makeCStruct(T *(*constructor)(void *), size_t(*sizeFn)(), auto destructor)
Create a C structure with pre-programmed deletion logic.
Definition util.h:216
QUOTIENT_API int majorVersion()
ImplPtr< ImplType, TypeToDelete > acquireImpl(ImplType *from)
Definition util.h:174
#define QUOTIENT_API
void operator()(T *toDelete)
Definition util.h:191
Multiplex several functors in one.
Definition util.h:228
QDebug operator<<(QDebug dbg, std::invocable< QDebug > auto manipFn)
A helper operator for QDebug manipulators, e.g. formatJson.
Definition util.h:305
#define QUO_CSTR(StringConvertible_)
q(Utf8)Printable that can handle more than just QStrings
Definition util.h:63