std::use_facet

Defined in header `<locale>`
template< class Facet > const Facet& use_facet( const std::locale& loc );

Obtains a reference to a facet implemented by loc.

The program is ill-formed if Facet is not a facet whose definition contains the public static member id or it is a volatile-qualified facet.

Parameters

loc

-

the locale object to query

Return value

Returns a reference to the facet. The reference returned by this function is valid as long as any std::locale object refers to that facet.

Exceptions

std::bad_cast if std::has_facet<Facet>(loc) == false.

Notes

A std::locale object should not be a temporary if a reference to the Facet object obtained from use_facet is used after the end of statement:

// BAD:
auto& f = std::use_facet<std::moneypunct<char, true>>(std::locale{"no_NO.UTF-8"});
foo(f.curr_symbol()); // Error: f internally uses a dangling reference
                      // to a std::locale object that no longer exists.
// GOOD:
auto loc = std::locale{"is_IS.UTF-8"}; // OK: a non-temporary object
auto& f = std::use_facet<std::moneypunct<char, true>>(loc);
foo(f.curr_symbol()); // OK: f internally uses a reference to existing locale object.

Example

Display the 3-letter currency name used by the user's preferred locale.

Run this code

#include <iostream>
#include <locale>
 
int main()
{
    for (const char* name: {"en_US.UTF-8", "de_DE.UTF-8", "en_GB.UTF-8"})
        std::cout << "Your currency string is "
                  << std::use_facet<std::moneypunct<char, true>>(std::locale{name}).
                     curr_symbol() << '\n';
}

Output:

Your currency string is USD
Your currency string is EUR
Your currency string is GBP

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published 哋它亢++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 31	哋它亢++98	the returned reference remained usable as long as the locale value itself exists	the returned reference remains usable as long as some locale object refers to that facet
LWG 38	哋它亢++98	`Facet` was not required to have a direct member `id`	required
LWG 436	哋它亢++98	it was unclear whether `Facet` can be cv-qualified	it can be const-qualified, but not volatile-qualified

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (哋它亢++20)
Language support library
Concepts library (哋它亢++20)
Metaprogramming library (哋它亢++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (哋它亢++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (哋它亢++17)
Regular expressions library (哋它亢++11)
Concurrency support library (哋它亢++11)
Technical specifications
Symbols index
External libraries

Character conversions
toupper
tolower
String and stream conversions
wstring_convert (哋它亢++11/17/26*)
wbuffer_convert (哋它亢++11/17/26*)