ezFormatString Class Reference

Implements formating of strings with placeholders and formatting options. More...

#include <FormatString.h>

Inheritance diagram for ezFormatString:

Public Member Functions
EZ_ALWAYS_INLINE	ezFormatString (const char *szString)
EZ_ALWAYS_INLINE	ezFormatString (ezStringView sString)
	ezFormatString (const ezStringBuilder &s)
virtual ezStringView	GetText (ezStringBuilder &) const
	Generates the formatted text. Make sure to only call this function once and only when the formatted string is really needed. More...
virtual const char *	GetTextCStr (ezStringBuilder &out_sString) const
	Similar to GetText() but guaranteed to copy the string into the given string builder, and thus guaranteeing that the generated string is zero terminated.
bool	IsEmpty () const
ezStringView	BuildFormattedText (ezStringBuilder &ref_sStorage, ezStringView *pArgs, ezUInt32 uiNumArgs) const
	Helper function to build the formatted text with the given arguments. More...

Protected Attributes
ezStringView	m_sString

Detailed Description

Implements formating of strings with placeholders and formatting options.

ezFormatString can be used anywhere where a string should be formatable when passing it into a function. Good examples are ezStringBuilder::SetFormat() or ezLog::Info().

A function taking an ezFormatString can internally call ezFormatString::GetText() to retrieve he formatted result. When calling such a function, one must wrap the parameter into 'ezFmt' to enable formatting options, example: void MyFunc(const ezFormatString& text); MyFunc(ezFmt("Cool Story {}", "Bro"));

To provide more convenience, one can add a template-function overload like this: template <typename... ARGS> void MyFunc(const char* szFormat, ARGS&&... args) { MyFunc(ezFormatStringImpl<ARGS...>(szFormat, std::forward<ARGS>(args)...)); }

This allows to call MyFunc() without the 'ezFmt' wrapper.

=== Formatting ===

Placeholders for variables are specified using '{}'. These may use numbers from 0 to 9, ie. {0}, {3}, {2}, etc. which allows to change the order or insert duplicates. If no number is provided, each {} instance represents the next argument.

To specify special formatting, wrap the argument into an ezArgXY call: ezArgC - for characters ezArgI - for integer formatting ezArgU - for unsigned integer formatting (e.g. HEX) ezArgF - for floating point formatting ezArgP - for pointer formatting ezArgDateTime - for ezDateTime formatting options ezArgErrorCode - for Windows error code formatting ezArgHumanReadable - for shortening numbers with common abbreviations ezArgFileSize - for representing file sizes

Example: ezStringBuilder::SetFormat("HEX: {}", ezArgU(1337, 8 /*width*‍/, true /*pad with zeros*‍/, 16 /*base16*‍/, true/*upper case*‍/));

Arbitrary other types can support special formatting even without an ezArgXY call. E.g. ezTime and ezAngle do special formatting. ezArgXY calls are only necessary if formatting options are needed for a specific formatting should be enforced (e.g. ezArgErrorCode would otherwise just use uint32 formatting).

To implement custom formatting see the various free standing 'BuildString' functions.

Member Function Documentation

BuildFormattedText()

ezStringView ezFormatString::BuildFormattedText	(	ezStringBuilder &	ref_sStorage,
		ezStringView *	pArgs,
		ezUInt32	uiNumArgs
	)		const

Helper function to build the formatted text with the given arguments.

Note

We can't use ezArrayPtr here because of include order.

GetText()

virtual ezStringView ezFormatString::GetText ( ezStringBuilder &  ) const

inlinevirtual

Generates the formatted text. Make sure to only call this function once and only when the formatted string is really needed.

Requires an ezStringBuilder as storage, ie. POTENTIALLY writes the formatted text into it. However, if no formatting is required, it may not touch the string builder at all and just return a string directly.

Note

Do not assume that the result is stored in sb. Always only use the return value. The string builder is only used when necessary.

Reimplemented in ezFormatStringImpl< ARGS >.

---

The documentation for this class was generated from the following files:

• /home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Strings/FormatString.h
• /home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Strings/Implementation/FormatString.cpp