# std::regex_traits<CharT>::transform_primary

> C++ Atlas: `cppatlas.com/w/cpp/regex/regex_traits/transform_primary` | Source: https://en.cppreference.com/w/cpp/regex/regex_traits/transform_primary | Domain: Regular expressions

For the character sequence [first, last), obtains the primary sort key in the imbued locale's collating order, that is, the sort key that is based on the positions of the letters and collation units in the national alphabet, ignoring…

## Official Specification Summary (cppreference)

```cpp
template< class ForwardIt >
string_type transform_primary( ForwardIt first, ForwardIt last ) const;
```

For the character sequence `[first,` `last)`, obtains the primary sort key in the imbued locale's collating order, that is, the sort key that is based on the positions of the letters and collation units in the national alphabet, ignoring case, diacritics, variants, etc. If a primary sort key compares less than another primary sort key with `operator<`, then the character sequence that produced the first sort key comes before the character sequence that produced the second sort key, in the currently imbued locale's primary collation order.

The regex library uses this trait to match characters against equivalence classes. For example, the regex `[[=a=]]` is equivalent to the character `c1` if `traits.transform_primary(c1)` is equivalent to `traits.transform_primary("a")` (which is true for any `c1` from `"AÀÁÂÃÄÅaàáâãäå"` in the U.S. English locale). Note that `transform_primary()` takes a character sequence argument because equivalence classes may be multicharacter, such as `[[=ch=]]` in Czech or `[[=dzs=]]` in Hungarian.

There is no portable way to define primary sort key in terms of `std::locale` since the conversion from the collation key returned by `std::collate::transform()` to the primary equivalence key is locale-specific, and if the user replaces the `std::collate` facet, that conversion is no longer known to the standard library's `std::regex_traits`. Standard library specializations of `std::regex_traits` return an empty string unless the `std::collate` facet of the currently-imbued locale was not replaced by the user, and still matches the system-supplied `std::collate` facet), in which case `std::collate_byname<CharT>::transform(first, last)` is executed and the sort key it produces is converted to the expected primary sort key using a locale-specific conversion.

### Parameters

- `first, last` - a pair of iterators which determines the sequence of characters to compare

**Type requirements**

- `ForwardIt` must meet the requirements of *LegacyForwardIterator*.

### Return value

The primary sort key for the character sequence `[first,` `last)` in the currently imbued locale, ignoring case, variant, diacritics, etc.

### Example

Demonstrates the regex feature that works through `transform_primary()`.

```cpp
#include <iostream>
#include <regex>

int main()
{
    std::locale::global(std::locale("en_US.UTF-8"));
    std::wstring str = L"AÀÁÂÃÄÅaàáâãäå";
    std::wregex re(L"[[=a=]]*", std::regex::basic);
    std::cout << std::boolalpha << std::regex_match(str, re) << '\n';
}
```

Possible output:

```text
true
```

> Note: This section is incomplete Reason: could use an example with user-defined regex_traits supplying user-defined transform_primary

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