# std::numpunct<CharT>::grouping, std::numpunct<CharT>::do_grouping

> C++ Atlas: `cppatlas.com/w/cpp/locale/numpunct/grouping` | Source: https://en.cppreference.com/w/cpp/locale/numpunct/grouping | Domain: Localization

This function returns a string, vec, which is used as a vector of integer values. (For example, "\003" specifies groups of 3 digits each, while "3" implies groups of 51 digits each.).

## Official Specification Summary (cppreference)

```cpp
// Defined in header <locale>

public:
std::string grouping() const; // (1)

protected:
virtual std::string do_grouping() const; // (2)
```

1) Public member function, calls the member function `do_grouping` of the most derived class.

2) Returns an `std::string` holding, in each `char` element, the number of digits in each group of the numeric output formatted by `num_put::put()` (and, therefore, `basic_ostream::operator<<`).

This function returns a string, `vec`, which is used as a vector of integer values. (For example, `"\003"` specifies groups of 3 digits each, while `"3"` implies groups of 51 digits each.). Each element `vec[i]` represents the number of digits in the `i`th digit group of the integer part of the number, counting from the right: `vec[0]` holds the number of digits in the rightmost group, `vec[1]` - in the second group from the right, etc. The grouping indicated by the last character, `vec[vec.size()-1]`, is repeatedly reused to group all remaining digits in the (left part of) the number. If `vec[i]` is non-positive or equals `CHAR_MAX` the size of the corresponding digit group is unlimited.

### Return value

The object of type `std::string` holding the groups. The standard specializations of `std::numpunct` return an empty string, indicating no grouping. Typical groupings (e.g. the `en_US` locale) return `"\003"`.

### Example

```cpp
#include <iostream>
#include <limits>
#include <locale>

struct space_out : std::numpunct<char>
{
    char do_thousands_sep()   const { return ' ';  } // separate with spaces
    std::string do_grouping() const { return "\1"; } // groups of 1 digit
};

struct g123 : std::numpunct<char>
{
    std::string do_grouping() const { return "\1\2\3"; }
};

int main()
{
    std::cout << "Default locale: " << 12345678 << '\n';
    std::cout.imbue(std::locale(std::cout.getloc(), new space_out));
    std::cout << "Locale with modified numpunct: " << 12345678 << '\n';
    std::cout.imbue(std::locale(std::cout.getloc(), new g123));
    std::cout << "Locale with \\1\\2\\3 grouping: "
              << std::numeric_limits<unsigned long long>::max() << '\n'
              << "Same, for a floating-point number: "
              << std::fixed << 123456789.123456789 << '\n';
}
```

Output:

```text
Default locale: 12345678
Locale with modified numpunct: 1 2 3 4 5 6 7 8
Locale with \1\2\3 grouping: 18,446,744,073,709,551,61,5
Same, for a floating-point number: 123,456,78,9.123457
```

### See also

- [`do_thousands_sep`](https://en.cppreference.com/w/cpp/locale/numpunct/thousands_sep) [virtual]: provides the character to use as thousands separator (virtual protected member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/locale/numpunct/grouping (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.