home | help
std::use_facet(3)	       C++ Standard Libary	       std::use_facet(3)

NAME
     std::use_facet - std::use_facet

Synopsis
	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 con-
     tains 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  func-
     tion 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::lo-
     cale{"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 lo-
     cale 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::lo-
     cale{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	retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to    Behavior as published		  Correct behav-
     ior
			   the	returned  reference	  the returned reference
     remains
	LWG 31	C++98	   remained usable		usable as
			   as long as the locale value	long as some locale  ob-
     ject refers to
			   itself exists		that facet
	LWG 38	C++98	   Facet was not required to	required
			   have a direct member id
	LWG  436  C++98      it was unclear whether Facet it can be const-quali-
     fied, but not
			   can be cv-qualified		volatile-qualified

See also
	locale	  set of polymorphic facets that  encapsulate  cultural  differ-
     ences
		  (class)
	has_facet checks if a locale implements a specific facet
		  (function template)

http://cppreference.com 	   2024.06.10		       std::use_facet(3)

home | help