format/format_to_nの戻り値の記述の詳細化 #1547
Description
問題点
std::format_to_n の戻り値である format_to_n_result の size メンバについて、これが「実際に書き込まれた長さ」ではなく「フォーマット後の全体の長さ（書き込まれるはずだった長さ）」であることが、現状のリファレンスでは数式から読み取る必要があり、直感的に分かりづらいと感じました。
## 戻り値
`format_to_n_result{out + M, N}` (ただし、`N` = `formatted_size(fmt, args...)` または `formatted_size(loc, fmt, args...)`、`M` = `min(max(n, 0), N)`)https://github.com/cpprefjp/site/blob/master/reference/format/format_to_n.md?plain=1#L82-L84
改善案
現状のドキュメントでも、与えられたコードを読めば誤解なく仕様を理解できますが、直感的なわかりやすさのための記述を追加したほうが親切だと思います。
## 戻り値
`format_to_n_result{out + M, N}` (ただし、`N` = `formatted_size(fmt, args...)` または `formatted_size(loc, fmt, args...)`、`M` = `min(max(n, 0), N)`)
戻り値のオブジェクトが保持するメンバ変数の意味は以下の通り：
* `out`: 出力範囲の末尾（実際に書き込まれた最後の文字の次）を指すイテレータ。
* `size`: バッファのサイズ指定`n`による切り捨てを考慮しない、フォーマットされた文字列全体の長さ（[`formatted_size`](formatted_size.md)の結果と等しい）。
したがって、戻り値の`size`が引数`n`より大きい場合、出力が途中で切り捨てられたことを意味する。あるいはコード例でバッファサイズが足りない場合の例を追加すると、仕様が理解しやすいかと思います。
## 例
```cpp example
#include <iostream>
#include <string>
#include <format>
#include <vector>
int main()
{
// 十分なバッファサイズがある場合
{
char buffer[256];
auto result = std::format_to_n(buffer, std::size(buffer)-1, "The answer is {}.", 42);
*result.out = '\0';
std::cout << buffer << std::endl;
std::cout << "size: " << result.size << std::endl;
}
// バッファサイズにより切り捨てられる場合
{
char buffer[10]; // 小さいバッファ
// "The answer is 42." は17文字必要だが、バッファは9文字分(null文字分除く)しかない
auto result = std::format_to_n(buffer, std::size(buffer)-1, "The answer is {}.", 42);
*result.out = '\0';
std::cout << "truncated: " << buffer << std::endl;
// result.size は本来出力されるはずだった長さ (17) を返す
std::cout << "required: " << result.size << std::endl;
}
}
```
### 出力
```
The answer is 42.
size: 17
truncated: The answe
required: 17
```