public member function
<locale>

std::ctype::narrow

single character (1)
            char narrow (char_type c, char dfault) const;
sequence (2)
const char_type* narrow (const char_type* low, const char_type* high,
                         char dfault, char* to) const;
Narrow character(s)
The first version (1) returns the transformation of c (possibly a wide character value) into its equivalent of type char.

The second version (2) fills the range beginning at to with the char transformations of the values in the range [low,high).

When a wide character has no equivalent of type char, the function considers argument dfault as its equivalent.

The transformation applied is the simplest reasonable transformation from the facet's character type (char_type) to char. Transformed characters cannot belong to categories (as returned by ctype::is) their original characters do not, except when this is dfault.

Internally, this function simply calls the virtual protected member do_narrow, which does the above by default in both the generic template and the char specialization (ctype<char>).

Parameters

c
Character to narrow.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).
low, high
Pointer to the beginning and end of the sequence of (wide) characters. The range used is [low,high), which contains all the characters between low and high, including the character pointed by low but not the character pointed by high.
Note that null characters (if any) are also converted, and the function proceeds beyond them, until the entire range is converted.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).
dfault
Default char value to be used for any character that cannot be mapped by the facet to a char equivalent from a char_type value.
to
Pointer to a range of elements of type char with enough storage to accommodate for as many characters as the range between low and high.
Notice that the type of this parameter is a pointer to an array of elements of type char, no matter the facet's character type.

Return value

The first version (1) returns the transformation of c.

The second version (2) always returns high.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
// ctype::narrow example
#include <iostream>       // std::cout, std::getline, std::wcin
#include <locale>         // std::locale, std::ctype, std::use_facet
#include <string>         // std::wstring

int main ()
{
  std::locale loc;
  std::wstring yourname;

  std::cout << "Please enter your name: ";
  std::getline (std::wcin,yourname);
  std::wstring::size_type length = yourname.length();

  std::cout << "The first (narrow) character in your name is: ";
  std::cout << std::use_facet< std::ctype<wchar_t> >(loc).narrow ( yourname[0], '?' );
  std::cout << '\n';

  std::cout << "The narrow transformation of your name is: ";
  char * pc = new char [length+1];
  std::use_facet< std::ctype<wchar_t> >(loc).narrow ( yourname.c_str(), yourname.c_str()+length+1, '?', pc);
  std::cout << pc << '\n';

  return 0;
}


Output:

Please enter your name: Juan Soulié
The first (narrow) character in your name is: J
The narrow transformation of your name is: Juan Soulié

Data races

The object is accessed.
In (2), the elements in the range [low,high) are accessed, and the elements in the array pointed by to are modified.

Exception safety

If an exception is thrown, there are no changes in the facet object, although characters in the destination array may have been affected.

See also

ctype::widen
Widen character(s) (public member function )

C++