public member function
<locale>

std::codecvt::length

int length (state_type& state, const extern_type* from,
            const extern_type* from_end, size_t max) const;
Return length of translated sequence
Returns the number of external characters in the range [from,from_end) that could be translated into at maximum of max internal characters, as if applying codecvt::in.

state is also updated as if codecvt::in was called for a buffer of max internal characters.

Internally, this function simply calls the virtual protected member do_length, which behaves as described above by default.

Parameters

state
A state object, as required by the facet instantiation.
Typically, this is an object of type mbstate_t, able to keep track of the shift state of a multibyte character conversion.
Member type state_type is the facet's state type (defined as an alias of codecvt's third template parameter, stateT).
from, from_end
Pointer to the initial and final characters of the source sequence. The range used is [from,from_end), which contains all the characters between from and from_end, including the character pointed by from but not the character pointed by from_end.
Note that null characters are considered valid characters and do not stop the function from proceeding until from_end.
Member type extern_type is the facet's external character type (defined as an alias of codecvt's second template parameter, exnternT).
max
Maximum length of the translated sequence (in terms of internal characters).
size_t is an unsigned integral type.

Return value

The length of the sequence of characters, in terms of translated internal characters.

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
26
27
28
29
30
31
32
 
// codecvt::length example
#include <iostream>       // std::wcout, std::endl
#include <locale>         // std::locale, std::codecvt, std::use_facet
#include <cwchar>         // std::mbstate_t
#include <cstddef>        // std::size_t

int main ()
{
  typedef std::codecvt<wchar_t,char,std::mbstate_t> facet_type;

  std::locale loc;
  const facet_type& myfacet = std::use_facet<facet_type>(loc);

  const char source[] = "abcdefghijklmnopqrstuvwxyz";

  // prepare objects for codecvt::length:
  std::mbstate_t mystate;
  const char * pc;
  wchar_t * pwc;

  // calculate length of dest (max 30):
  std::size_t length = myfacet.length (mystate, source, source+sizeof(source), 30);

  wchar_t* dest = new wchar_t[length];
  myfacet.in (mystate, source, source+sizeof(source), pc, dest, dest+length, pwc);

  std::wcout << dest << std::endl;

  delete[] dest;

  return 0;
}


Output:

abcdefghijklmnopqrstuvwxyz

Data races

The facet object and up to all the characters in the range [from,from_end) are accessed.
The argument passed as state is modified.

Exception safety

If an exception is thrown, there are no changes in the facet object (although state may have changed).

See also

codecvt::in
Translate in characters (public member function )
codecvt::max_length
Return max length of one character (public member function )
codecvt::do_length
Return length of translated sequence [virtual] (public member function )

C++