Doc: Unclear contract for retention of fmt::arg results

[BillyDonahue]

Docs for fmt::arg() seem to indicate that the returned object my depend on temporaries created in the function call expression, and that it would be unsafe to use the returned object after the full expression expires.

fmt/include/fmt/core.h

Lines 1622 to 1623 in b8ff3c1

	Returns a named argument to be used in a formatting function. It should only
	be used in a call to a formatting function.

That's no longer true as other examples like

fmt/include/fmt/args.h

Lines 180 to 181 in b8ff3c1

	auto a1 = fmt::arg("a1_", a1_val);
	store.push_back(std::cref(a1));

show the result being retained in auto variables and passed to fmt::dynamic_format_arg_store via push_back.

I want to use dynamic_format_arg_store but it looks like I'm breaking the fmt::arg contract to do it.
I know it's safe, but the docs don't quite match the reality.

Should the "It should only be used in a call to a formatting function" be removed or updated?

[vitaut]

Good catch, thanks!

The example in fmt/args.h is pretty bad, we shouldn't be storing the return value of fmt::args. I've updated the comments in 5a1127b and disabled wrapping named arguments in cref since it's misleading (argument name is always stored by reference) and doesn't work with rvalue references.

[BillyDonahue]

A new comment says "The name is always stored by reference", but it is actually copied into the dynamic_args_ as a std::basic_string<char_type>.

fmt/include/fmt/args.h

Lines 190 to 205 in 6151d0d

	/**
	Adds named argument into the dynamic store for later passing to a formatting
	function. ``std::reference_wrapper`` is supported to avoid copying of the
	argument. The name is always stored by reference.
	*/
	template <typename T>
	void push_back(const detail::named_arg<char_type, T>& arg) {
	const char_type* arg_name =
	dynamic_args_.push<std::basic_string<char_type>>(arg.name).c_str();
	if (detail::const_check(need_copy<T>::value)) {
	emplace_arg(
	fmt::arg(arg_name, dynamic_args_.push<stored_type<T>>(arg.value)));
	} else {
	emplace_arg(fmt::arg(arg_name, arg.value));
	}
	}

Maybe it's hard to see because arg_name looks like arg.name.

[vitaut]

You are right. Fixed in 8308f52.