public member function
<locale>

std::ctype::widen

  char_type widen (char c) const;
const char* widen (const char* low, const char* high, char_type* to) const;
Widen character(s)
The first version (1) returns the transformation of c into its equivalent of the facet's character type (char_type, which is a member type alias of ctype's template parameter, charT).

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

The transformation applied is the simplest reasonable transformation from char values to their corresponding values of the destination type (char_type). Transformed characters cannot belong to categories (as returned by ctype::is) their original characters do not.

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

Parameters

c
Character (of type char) to widen.
Notice that the type of this parameter is the fundamental type char, no matter the character type the facet uses.
low, high
Pointer to the beginning and end of the sequence of 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.
to
Pointer to a range of elements of the facet's character type (aliased as member type char_type) with enough storage to accommodate for as many elements as the range between low and high.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).

Return value

The first version (1) returns the transformation of c.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).

The second version (2) always returns high.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
// ctype::widen example
#include <iostream>       // std::wcout, std::endl
#include <locale>         // std::locale, std::ctype, std::use_facet

int main ()
{
  std::locale loc;

  const char narrow_phrase[] = "Seventy-seven foxes";
  wchar_t wide_phrase[sizeof(narrow_phrase)];

  std::wcout << L"The first wide character is: ";
  wchar_t wc = std::use_facet< std::ctype<wchar_t> >(loc).widen ( *narrow_phrase );
  std::wcout << wc << std::endl;

  std::wcout << L"The wide-character phrase is: ";
  std::use_facet< std::ctype<wchar_t> >(loc).widen (narrow_phrase,
                                                    narrow_phrase+sizeof(narrow_phrase),
                                                    wide_phrase);
  std::wcout << wide_phrase << std::endl;

  return 0;
}


Output:

The first wide character is: S
The wide-character phrase is: Seventy-seven foxes

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::narrow
Narrow character(s) (public member function )

C++