Fmt wrappers by tomc271 · Pull Request #3505 · boutproject/BOUT-dev

tomc271 · 2026-09-29T11:33:02Z

Implement template specializations for the fmt library (or format_as() wrapper for enums).
This removes the need to call toString() on these types when passing them to BoutException.

so that fmt library will handle them automatically.

(by falling back to the default 'c' representation).

as fmt will handle it (via the new `format_as` wrappers).

…fined (ODR) Prevents fmt compilation issues.

to match the original code flow.

(Clang-Tidy)

…ions ('*' has higher precedence than '+').

…s implicitly inlined

so no need to call `toString()` explicitly.

(as it's needed for other functions, such as ::SQ).

… to bout_types.cxx and add `toString` and `format_as()` to bout_types.hxx for the `const DirectionTypes&` type

to call its `toString()` method.

Not required as handled by fmt::formatter for SpecificInd.

Clang-Tidy: No header providing "UNUSED" is directly included

Not required as handled by fmt::formatter for SpecificInd.

github-actions

clang-tidy made some suggestions

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions

clang-tidy made some suggestions

ZedThree

Thanks @tomc271, I didn't realise it was as simple as adding format_as, very nice!

As well as the comments below, a couple of other things:

could we flip the implementations, so that format_as has the actual implementation and toString just calls format_as?
then we can add [deprecated] to all toString definitions with a nice message about using fmt::format instead

ZedThree · 2026-09-29T12:52:37Z

+std::string toString(const DirectionTypes& dir);
+inline std::string format_as(const DirectionTypes& dir) { return toString(dir); }


It doesn't particularly matter, but could these be moved below the definition of DirectionTypes, and then we can drop the forward-decl on L31?

ZedThree · 2026-09-29T12:57:23Z

+namespace bout {
+inline std::string format_as(const ConductionMethod& method) { return toString(method); }
+} // namespace bout


If we add this to the BOUT_ENUM_CLASS{,_NS} macros, then we don't need to add it manually

ZedThree · 2026-09-29T13:01:03Z

 #include <type_traits>

-template <IND_TYPE N>
-struct fmt::formatter<SpecificInd<N>> {


What was the issue that required this being moved?

The motivation for having it in this header, rather than region.hxx, was to make compilation cheaper -- this would only be included where needed

Just because having it in the same file prevented "unknown format specifier" errors at compile-time when the output_bout_types.hxx file isn't explicitly included
e.g.

include/bout/field.hxx: In instantiation of ‘void bout::checkFinite(const T&, const std::string&, const std::string&) [with T = Field2D; std::string = std::__cxx11::basic_string]’:
src/mesh/metric_tensor.cxx:33:20: required from here
include/bout/field.hxx:303:13: in ‘constexpr’ expansion of ‘fmt::v12::fstring<const std::__cxx11::basic_string<char, std::char_traits, std::allocator >&, SpecificInd<IND_TYPE::IND_2D>&>("{:s} is not finite at {:s}")’

ZedThree · 2026-09-29T13:03:23Z

+struct fmt::formatter<SpecificInd<N>> {
+  char presentation = 'c';
+
+  // Parses format specifications: ['c' | 'i' | 's'] or empty {}


What does s do?

It was added to prevent this line failing:
throw BoutException("{:s} is not finite at {:s}", name, i);

The second :s here is a SpecificInd, so the parse() method of fmt::formatter<SpecificInd<N>> fails unless 's' is explicitly handled.

Perhaps the right solution is instead to change the calling code to:
throw BoutException("{:s} is not finite at {:c}", name, i);
or:
throw BoutException("{:s} is not finite at {:i}", name, i);

Oh, that's because it has migrated from %s when we were using printf style formatting. Probably {:c} makes the most sense.

ZedThree · 2026-09-29T13:04:22Z

+// Custom fmt formatter for SpecificInd
+template <IND_TYPE N>
+struct fmt::formatter<SpecificInd<N>> {
+  char presentation = 'c';


This has lost the docstring about the meanings of c and i

which were accidentally deleted when moving.

…w its definition so forward declaration is not needed.

in SpecificInd fmt formatter

…itive()` to field.cxx

(Clang-Tidy suggestion)

…nd is defined (ODR)" This reverts commit 163fda2

dschwoerer · 2026-09-30T12:37:36Z

@@ -135,30 +135,30 @@ struct DerivativeStore {
      if (standard.count(key) != 0) {
        throw BoutException("Trying to override standard derivative : "
                            "direction {:s}, stagger {:s}, key {:s}",


Suggested change

"direction {:s}, stagger {:s}, key {:s}",

"direction {}, stagger {}, key {:s}",

I assume the s should always be removed?

Enums using format_as support {:s} automatically, so it's only those types using a custom fmt::formatter<T> template specialisation (such as SpecificInd<N>) that may not handle :s
(because their custom parse() method defines the parsing of format presentation characters).

Even though not necessary, {} might still still be preferable though?

Yeah, nice to be consistent, then new developers looking at this are less likely to get tripped up

now that fmt::formatter<SpecificInd<N>> is there

github-actions

clang-tidy made some suggestions

github-actions · 2026-10-08T14:25:03Z

+    throw BoutException("{:s} is not allocated", name);
+  }
+
+  BOUT_FOR_SERIAL(i, f.getRegion(rgn)) {


warning: no header providing "BOUT_FOR_SERIAL" is directly included [misc-include-cleaner]

src/field/field.cxx:25:

- #include <bout/bout_types.hxx> + #include "bout/region.hxx" + #include <bout/bout_types.hxx>

tomchapman added 29 commits September 29, 2026 09:37

Add format_as methods delegating to existing toString methods

aa5ea58

so that fmt library will handle them automatically.

Handle 's' format specification in fmt::formatter<SpecificInd<N>>

2f82759

(by falling back to the default 'c' representation).

No longer need to call toString() on CELL_LOC types

f5ec5e0

as fmt will handle it (via the new `format_as` wrappers).

Move fmt::formatter<SpecificInd<N>> to same file as SpecificInd is de…

163fda2

…fined (ODR) Prevents fmt compilation issues.

Refactor fmt::formatter<SpecificInd<N>>::format() method

670310a

to match the original code flow.

Prefer const

9b1ce11

Directly include fmt/base.h header

4f5987c

(Clang-Tidy)

Redundant 'typename' keyword

d7b458e

(Clang-Tidy)

Clang-Tidy: add parentheses to explicitly specify the order of operat…

5a6048b

…ions ('*' has higher precedence than '+').

Clang-Tidy: Redundant parentheses around expression

753fd1f

Clang-Tidy: add parentheses to explicitly specify the order of operat…

05cc34f

…ions ('*' has higher precedence than '+').

Clang-Tidy: Function 'createRegionIndices' has inline specifier but i…

40ad179

…s implicitly inlined

Add custom formatter for DirectionTypes

f15068e

so no need to call `toString()` explicitly.

Restore #include utils.hxx to field.hxx

8055c18

(as it's needed for other functions, such as ::SQ).

Move std::string toString(const DirectionTypes& dir) from utils.hxx…

9a72d7f

… to bout_types.cxx and add `toString` and `format_as()` to bout_types.hxx for the `const DirectionTypes&` type

Add format_as() wrapper for BoundaryParType

762b618

to call its `toString()` method.

Remove call to toString() in BoutException arguments

2fab339

Not required as handled by fmt::formatter for SpecificInd.

Redundant 'typename' keyword

aca326b

Clang-Tidy: No header providing "BoutException" is directly included

8e2de4f

Clang-Tidy: No header providing "std::set" is directly included

0538320

Clang-Tidy: No header providing "UNUSED" is directly included

Remove redundant const qualifier

c5bd564

Clang-Tidy: Pointer parameter 'localmesh' can be pointer to const

ce45224

Parameter can be made const

b3719a6

Apply clang-format

75a6a28

Remove more to toString() calls in BoutException arguments

badede6

Not required as handled by fmt::formatter for SpecificInd.

Apply clang-format

c9db23a

Add format_as() wrapper for ConductionMethod type

0e90ad5

Make format_as() parameters const (ref)

48363a0

Apply clang-format

7b77b11

github-actions Bot reviewed Sep 29, 2026

View reviewed changes

Comment thread include/bout/output_bout_types.hxx

Remove unused #include "bout/utils.hxx"

d9b4d51

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions Bot reviewed Sep 29, 2026

View reviewed changes

Comment thread include/bout/output_bout_types.hxx

ZedThree requested changes Sep 29, 2026

View reviewed changes

tomchapman added 2 commits September 29, 2026 14:42

Restore comments in fmt::formatter<SpecificInd<N>>

8046c2f

which were accidentally deleted when moving.

Move toString() and format_as() methods for DirectionTypes belo…

2e41f70

…w its definition so forward declaration is not needed.

tomc271 force-pushed the fmt-wrappers branch from 03533e1 to 2e41f70 Compare September 29, 2026 14:17

tomchapman added 7 commits September 29, 2026 16:39

Revert s option for presentation format

f0239f6

in SpecificInd fmt formatter

Remove unused #include "bout/utils.hxx"

d5d1027

Move definitions and specializations of checkFinite() and `checkPos…

8e5b27d

…itive()` to field.cxx

Directly include headers

ad83aa6

(Clang-Tidy suggestion)

Revert "Move fmt::formatter<SpecificInd<N>> to same file as SpecificI…

641e54b

…nd is defined (ODR)" This reverts commit 163fda2

Remove unused #include directives

ff8a337

Apply clang-format

4952b23

dschwoerer reviewed Sep 30, 2026

View reviewed changes

tomchapman added 4 commits September 30, 2026 16:56

Don't include region.hxx in field.cxx

5c7d768

Include output_bout_types.hxx in operatorstencil.hxx

dd6b000

now that fmt::formatter<SpecificInd<N>> is there

Reset to original function order

6033b79

No need to call toString() on a string

c29857c

github-actions Bot reviewed Oct 8, 2026

View reviewed changes

Apply clang-format

d279cf5

		std::string toString(const DirectionTypes& dir);
		inline std::string format_as(const DirectionTypes& dir) { return toString(dir); }

	"direction {:s}, stagger {:s}, key {:s}",
	"direction {}, stagger {}, key {:s}",

Conversation

tomc271 commented Sep 29, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ZedThree left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants