Hello,
On 10 August 2017 at 20:41, Mårten Nordheim <marten.nordh...@qt.io> wrote: > > Hello, I'm back with round 2 of QStringFormatter > ===== > > The WIP is still located over here: > https://codereview.qt-project.org/#/c/192873/ > > Name > ----- > > I think it would be nice to change the class' name as typing > QStringFormatter repeatedly is fairly cumbersome. One suggestion was > QFormat (unless it's already used, though I haven't seen any uses > from searching). If there're no objections or other suggestions then > I will rename the class. IMHO, "QFormat" isn't a suitable name. First, this class itself does not describe a format, unlike: * QTextFormat * Qt::DateFormat * QSettings::Format * QAudioFormat * QImage::Format * QPixelFormat * QVideoFrame::PixelFormat * QVideoSurfaceFormat * QSurfaceFormat * QOpenGLFramebufferObjectFormat So, at the very least, call it "QFormatter" Second, from a quick glance of the list above, I can guess the type of format that most the classes/enums above describe. "QFormat"/"QFormatter" doesn't contain any clues that it's related to string formatting. (Minor tangent: I feel that QTextFormat and QText(Char|Block|List|Table)Format would be clearer if renamed to QTextDocumentFormat and QTextDocument(Char|Block|List|Table)Format respectively) Finally, one of the guidelines in https://wiki.qt.io/API_Design_Principles#The_Art_of_Naming is "Do not abbreviate". For these reasons, I'd personally prefer sticking to "QStringFormatter". Having said that, the verbosity of a name is a valid concern. It is the reason why I personally prefer to write raw C string literals instead of wrapping them in QStringLiteral, unless the performance penalty is noticeable. I can't think of a better name than "QStringFormatter" though. Perhaps, in our documentation/examples, we can suggest that the user introduce a typedef in their own code (as opposed to adding an official abbreviation) to shorten things? typedef QStringFormatter QSF; QSF formatter(...); > API > ----- > > Changes since I last wrote about QStringFormatter on the mailing list: > > - the in-string formatting's separator was changed from '$' to ':' to > match other string formatting APIs. > - ::multiArg was introduced > - Variadic template which simply forwards each parameter to a > separate ::arg-call > - Currently returns a QString directly. Should it return > QStringFormatter& like ::arg? > - Static function ::format > - Another variadic template, instantiates QStringFormatter and > forwards arguments to multiArg > - example: > `QStringFormatter::format("{} {}", "Hello,", "World!");` > - Remove? Nice to have? > - (QStringFormatter::)Formatting > - ::arg methods have an optional Formatting argument which can be > used to override or augment any previously specified in-string > formatting > - Can be constructed from a string of formatting options > (e.g. "L<10") or using its methods (e.g. setLocale, > setJustification) > - Named replacements uses an alias for QPair<QString, T> called > Argument. > - e.g. `QStringFormatter("Hello, {Name}").arg({"Name", "World"});` > - A qMakePair-style function called `qArg` for use in > situations with template argument deduction trouble. > - e.g. > `QStringFormatter("Hello, {Name}").arg(QStringFormatter::qArg("Name", 47));` > > Any feedback on API is appreciated. A proposal for the API for > formatting custom types follows. > > Replacement format > ----- > > The replacement options now have formatting features matching > QString::arg. The current options (open to change) are: > > - `L` for localization (localize numbers, like in QString::arg) > - `</>/=` for justification. Left, right and center justification > - Followed by an optional padding character (excluding 1-9) > - Followed by field-width > - e.g. "==16" (pad using '=', centered, field-width 16), > "<10" (left-justify using spaces, field-width 10), > ">-3" (right-justify using '-', field-width 3) > - `f/g/G/e/E` for floating-point number formatting > (https://doc.qt.io/qt-5/qstring.html#argument-formats) > - followed by a dot and then precision > - e.g. "f.2" > - `b/B` for setting base. Supports bases 2-36. Using 'b' produces > lower-case letters for digits 10-35, and 'B' produces upper-case. > For bases 2-10 they make no difference. > - `:` everything after the colon gets put into an 'extra' field, more > on this later.. > - e.g. `{:<10:this is the extra field}` > - or `{::yyyy-MM-dd HH:mm:ss}` > > Currently the formatting options can come in any order (e.g. "L<10" > and "<10L" does the same, the only exception being ':'). > However it would be good to enforce some sort of order for the sake > of consistency. With a defined order we could also change > justification format from [<>=]cn to c[<>=]n, which would allow > people to use 1-9 as a fill-character. If this is done, what should > the order be like? > > QString::arg compatibility > ----- > > Currently QString::arg compatibility is activated using a parameter > in the constructor. All this does is let you use %nn style tokens and > 'disable' use of the brace-style tokens. It also supports `%L` to > enable localization of numbers, but any other formatting must be done > using the `QStringFormatter::Formatting` class. > > API for formatting custom types > ----- > > One idea I've been experimenting with a little bit is using template > specialization to deal with formatting custom types. To support a > custom type you'd create a specialization of a struct called > `Formatter`. It would use the `extra` field in `Formatting` which > you could optionally parse for custom formatting options. The parser > would be a separate class inheriting `Formatting` and be specified in > the Formatter using a typedef. > > E.g. > `struct QStringFormatter::Formatter<QDateTime> > { > typedef DateTimeInfo FormatType; > QString operator()(const QDateTime &dateTime, const FormatType &format); > }` > > `QStringFormatter` will then instantiate this struct when it receives > a `QDateTime` object, and create a `FormatType` object to parse the > data located in the `extra` field of formatting options. The > `FormatType` object is then expected to store whatever info it needs > and then the `Formatter` will use it later. > > Feedback on the approach, pitfalls etc. is much appreciated! > > Thanks, > > > -- Mårten Nordheim Regards, Sze-Howe Koh _______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development