Doc No: X3J16/94-0083, WG21/N0470 Date: May 31, 1994 Reply-to: Norihiro KUMAGAI, Sharp Corporation, kuma@slab.tnr.sharp.co.jp Title: A Draft for the Specification of the IOStream Classes [PRELIMINARY VERSION] A Draft for the Specification of the IOStream Classes Norihiro KUMAGAI Sharp Corporation A member of IPSJ/ITSCJ/SC22/C WG,C++WG kuma@slab.tnr.sharp.co.jp This document describes a draft of the specification of the library part(section 17.4 "Input/output") for templated IOStream classes. The following shows only the differential (and essentian change) part to the original specification(WP:Working Paper in the pre San Diego Mailing -- DRAFT: 25 January 1994). Although, this is not the complete document, this covers all of the technically essential points of view. This is a preliminary version and there are several point to be finalized (especially in the descriptions). These immature parts will be finalized until the Waterloo meeting. The document, "Overview of the Proposal for the template IOStream classes"[X3J16/94-0082,WG21/N0469] will tell you the background and overview in supporting the template IOStream class. === BEGIN ===================================== 17.4 Input/output ###################################################################### ## This format of paragraphs(surrounded by a lot of '#' characters) ## represent a rationale of the Standard. In order to construct the ## specification from this draft, this format of paragraphs shall be ## ignored. ###################################################################### ['Character'] In this chapter, the term 'character' means the generalized element of text data. Each text data consist of a sequence of 'character'. So the term does not only means the 'char' type object, and the 'wchar_t' type object but also any sort of classes which provides the definitions specified in 17.4.1.1. [Character container type] Character container type is a class or a type which represent 'character'. It is used for one of the template parameter of the template IOStream classes. [The template IOStream classes] The template IOStream classes are the template classes which takes two template parameters; charT and baggage. The class, charT, represents the character container class and the class, baggage, represents the baggage structure which provides the definition of the functionality necessary to implement the template IOStream classes. The names of the template IOStream classes specified in the Standard are as follows; basic_ios, basic_streambuf, basic_istream, basic_ostream, basic_smanip, basic_imanip, basic_omanip, basic_strstreambuf, basic_istrstream, basic_ostrstream, basic_stringbuf, basic_istringstream, basic_ostringstream, basic_convbuf, basic_filebuf, basic_ifstream, basic_ofstream. [Narrow-oriented IOStream classes] The narrow-oriented IOStream classes are the versions of the template IOStream classes specialized with the character container class, 'char'. The traditional IOStream classes aree regarded as the narrow-oriented IOStream classes. The names of the narrow-oriented IOStream classes specified in the Standard are as follows; ios, streambuf, istream, ostream, smanip, imanip, omanip, strstreambuf, istrstream, ostrstream, stringbuf, istringstream, ostringstream, convbuf, filebuf, ifstream, ofstream. Every implementation shall have the above narrow-oriented IOStream classes. [Wide-oriented IOStream classes] The wide-oriented IOStream classes are the versions of the template IOStream classes specialized with the character container class, 'wchar_t'. The names of the narrow-oriented IOStream classes specified in the Standard are as follows; wios, wstreambuf, wistream, wostream, wsmanip, wimanip, womanip, wstrstreambuf, wistrstream, wostrstream, wstringbuf, wistringstream, wostringstream, wconvbuf, wfilebuf, wifstream, wofstream. Every implementation shall have the above wide-oriented IOStream classes. 17.4.1 Header The Header defines three types that controlls input from and output to 'character' sequence. All of the definition in the subclause 17.4.1.1 and 17.4.1.2 are defined in the Header (forward reference; 17.4.2). 17.4.1.1 Template struct ios_baggage template struct ios_baggage {}; struct ios_baggage { typedef ios_char_baggage char_bag; typedef ios_pos_baggage pos_bag; }; struct ios_baggage { typedef ios_char_baggage char_bag; typedef ios_pos_baggage pos_bag; }; The template struct ios_baggage is an baggage class which maintains the definitions of the types and functions necessary to implement the template IOStream classes. The template parameter, charT represents the character container type and each specialized version provides the default definitions corresponding to the specialized character container type. All of the types and functions provided in this struct can be classified into two categories, character-container-type-related and positional-information-related. Each of the specialized struct, ios_baggage, in which 'CHAR_T' represents the specialized type of the character container type, typedefs two specialized template structs, ios_char_baggage and ios_pos_baggage, in which 'POS_T' represents a specialized version of the repositioning information class(forward reference; 17.4.1.2 Repositioning information classes). 17.4.1.1.1 Template struct ios_char_baggage ###################################################################### ## There are several types and functions needed for implementing the ## template IOStream classes. Some of these types and functions ## depend on the definition of the character container type. The ## collection of these functions describes the behavior which the ## implementation of the template IOStream class expects to the ## character container class. Those who provide a character container ## class as the template parameter have to provide all of these ## functions as well as the container class itself. From the point of ## view, the collection of these functions can be regarded as the ## collection of the common definitions for the implementation of the ## character container class. ###################################################################### template struct ios_char_baggage : public string_char_baggage {}; ###################################################################### ## No special definition/declaration is provided here. The base class ## (or struct), 'string_char_baggage' provides the common definitions ## common between the template string .classes and the template ## IOStream classes. ###################################################################### The template struct, ios_char_baggage, is a struct derived from the class, string_char_baggage. For each of the character container classes, 'CHAR_T', the corresponding specialized struct ios_char_baggage, prepares the definitions related to the character container type so that it provides all the functionality necessary to implement the template IOStream classes. Each of the specialization of the struct 'ios_char_baggage' shall have the following definitions; struct ios_char_baggage { typedef CHAR_T char_type; typedef INT_T int_type; static char_type to_char_type (int_type); static int_type to_int_type (char_type); static bool eq_char_type (char_type, char_type); static bool eq_int_type (int_type, int_type); static int_type eof(); static int_type not_eof(); static bool is_eof(int_type); static char_type newline(); static bool is_whitespace(locale::ctype ctype, char_type c); }; A type, CHAR_T is the character container type and can represent every valid character values. Every implementation shall provide both the types, 'char' and 'wchar_t' as CHAR_T specializations. A type, INT_T is the another character container type which can also hold end-of-file value. It is specified as the return type of some of the IOStream class member functions. If CHAR_T is either 'char' or 'wchar_t', INT_T shall be 'int' or 'wint_t', respectively. A typedef type, char_type is a synonim of the character container type, CHAR_T. A typedef type, int_type is a synonim of the character container type, INT_T. A static member function, char_type to_char_type (int_type c); converts a valid character value represented in the int_type to the corresponding char_type value. If c is end-of-file value, the return value is unspecified. A static member function, int_type to_int_type (char_type c); converts a valid character value represented in the char_type to the corresponding int_type value. A static member function, bool eq_char_type (char_type c1, char_type c2); determines whether two character values, c1 and c2, represent the same character or not. A static member function, bool eq_int_type (int_type c1, int_type c2); determines whether two character values, c1 and c2, represent the same character or not. A static member function, int_type eof(); returns an 'int_type' value which represents the end-of-file. It is returned by several functions to indicate end-of-file state(no more input from an input sequence or no more output permitted to an output sequence), or to indicate an invalid return value. A static member function, int_type not_eof (); returns a certain 'int_type' value other than the end-of-file. It is used in the member function, basic_streambuf::overflow(). A static member function, bool is_eof (int_type c); determines whether the character value, c represent the end-of-file. A static member function, char_type newline(); returns a 'character' value which represent the newline character of the basic character set. It appears as the default parameter of the member function, basic_istream::getline(). A static member function, bool is_whitespace (char_type c, locale::ctype ctype); determines whether the character value, c represents one of the white space characters. The default definition is as if it invokes, ctype.isspace(c); and returns its return value. An implementation of the template IOStream classes may use all of the above static member functions in addition to the following three functions provided from the base struct, 'string_char_baggage' A static member function, char_type eos (); returns the null character which is used for the terminator of null terminated character strings. The default constructor for the character container type provides the value. A static member function, size_t length (const char_type* s); determine the length of a null terminated character string pointed to by s. A static member function, char_type* copy (char_type* dest, const char_type* src, size_t n); Copies n characters from the object pointed to by src into the object pointed to by dest. If copying takes place between objects that overlap, the behavior is undefined. ###################################################################### ## The reason that these two member functions, length and copy, are ## prepared is to achive efficiency for char and wchar_t specialized ## versions. If the character container type require no special ## construction/ destruction operations (or it is a immutable class), ## the memory copy operation leads us to avoid inefficiency which an ## explicit copy loop in the implementation of the template IOStream ## classes give rise to. ###################################################################### Every implementation shall provide the following two specialization versions of the ios_char_baggage<>; struct ios_char_baggage { typedef char char_type; typedef int int_type; static char_type to_char_type (int_type c) { return c; } static int_type to_int_type (char_type c) { return c; } static bool eq_char_type (char_type c1, char_type c2) { return c1 == c2; } static bool eq_int_type (int_type c1, int_type c2) { return c1 == c2; } static int_type eof() { return EOF; } static int_type not_eof() { return ~EOF; } static bool is_eof(int_type c) { return c == EOF; } static char_type newline() { return '\n'; } static bool is_whitespace(char_type c, locale::ctype ctype) { return ctype.isspace(c); } }; struct ios_char_baggage { typedef wchar_t char_type; typedef wint_t int_type; static char_type to_char_type (int_type c) { return c; } static int_type to_int_type (char_type c) { return c; } static bool eq_char_type (char_type c1, char_type c2) { return c1 == c2; } static bool eq_int_type (int_type c1, int_type c2) { return c1 == c2; } static int_type eof() { return WEOF; } static int_type not_eof() { return ~WEOF; } static bool is_eof(int_type c) { return c == WEOF; } static char_type newline() { return L'\n'; } static bool is_whitespace(char_type c, locale::ctype ctype) { return ctype.isspace(c); } }; Note that there are the two types, wchar_t and wint_t, which are declared in . 17.4.1.2 Repositional information classes ###################################################################### ## I am sorry I cannot fill the description of the following member ## functions. The behavior and specification of the ## streampos/streamoff should need more discussion. ###################################################################### 17.4.1.2.1 Template struct ios_pos_baggage template struct ios_pos_baggage {}; struct ios_pos_baggage { typedef streampos pos_type; typedef streamoff off_type; }; struct ios_pos_baggage { typedef wstreampos pos_type; typedef wstreamoff off_type; }; The template struct, ios_pos_baggage, is a struct. For each of the repositional information class, 'POS_T', the corresponding specialized struct, ios_pos_baggage, prepares the typedefs related to the POS_T. Each of the specialization of the struct 'ios_pos_baggage' shall have the following definitions; struct ios_pos_baggage { typedef POS_T pos_type; typedef OFF_T off_type; A type, OFF_T; which is a synonym for one of the signed integral types whose representation has at least as many bits as type 'long'. A typedef, off_type; which is a synonym of the OFF_T and is used for declaring/implementing the template IOStream class. A class, POS_T; which is an implementation-defined class for seek operation which describes an object that can store all the information necessary to restore to the position. A typedef, pos_type; which is a synonym for the class POS_T which is used for declaring/ implementing the template IOStream classes. 17.4.1.2.2 The specialized class POS_T, OFF_T Every class that can apply to the template parameter posT in the template struct, 'ios_pos_baggage' shall have following definitions; typedef T1 OFF_T; class POS_T { public: POS_T (int off); POS_T (OFF_T off = 0); OFF_T offset() const; OFF_T operator-(POS_T& rhs); POS_T& operator+=(OFF_T off); POS_T& operator-=(OFF_T off); POS_T operator+(OFF_T off); POS_T operator-(OFF_T off); bool operator==(POS_T& rhs) const; bool operator!=(POS_T& rhs) const; }; ###################################################################### ## This subsection need more to discuss. How we treat the case if the ## external source/sink stream does not ensure to accept POS_T, OFF_T ## object to which some arithmetic operations performed? ###################################################################### The type OFF_T is a synonym for one if the signed basic integral types T1 whose representation at least as many bits as type long. It is used to represent: -- a signed displacement, measured in characters, from a specified position within a sequence. -- an absolute position within a sequence. The class POS_T describes an object that can store all the information necessary to restore one or more types of sequences, to a previous stream position. Every POS_T class has the corresponding OFF_T type and the set of applicable stream classes. [Repositional Streams and Arbitrary-positional Streams] There are two types of stream, repositional, and arbitrary-positional. With a repositional stream, we can seek to only the position where we previously encountered. On the other hand, with a arbitrary- positional stream, we can seek to any integral position within the length of the stream. For a stream buffer which is corresponding to a repositional stream (but not a arbitrary-positional stream), all we can do is either to fetch the current position of the stream buffer or to specify the previous position which we have already fetched from the stream buffer. Every arbitrary-positional stream is a repositional. If a repositional stream returns a POS_T object, and some arithmetic operations (operator+=, operator-, operator+=, operator-=) are applied, the behavior of the stream after restoring the position with the modified POS_T object is undefined. It means that a POS_T object whose parent stream is repositional shall not apply any arithmetic operations. It is not ensured that in case the validity of a certain POS_T object is broken, the error shall be informed. Or there is no way to check the validity of a certain POS_T object. [Invalid POS_T value] The stream operations whose return type is POS_T may return POS_T((OFF_T)(-1)) as signal to some error occurs. This return value is called the 'invalid POS_T value'. The constructor, POS_T::POS_T((OFF_T)(-1)) constructs the invalid POS_T value, which is available only for comparing to the return value of such member functions. 17.4.1.2.2.1 POS_T::POS_T(OFF_T); [Almost same as in the WP:17.4.2.2.1] 17.4.1.2.2.2 POS_T::offset() const; [Almost same as in the WP:17.4.2.2.2] 17.4.1.2.2.3 POS_T::operator-(POS_T&); [Almost same as in the WP:17.4.2.2.3] If the parent stream is not arbitrary-positional, the value of the operation becomes invalid so it may not apply the parent stream. 17.4.1.2.2.4 POS_T::operator+=(OFF_T); [Almost same as in the WP:17.4.2.2.4] If the parent stream is not arbitrary-positional, the value of the operation becomes invalid so it may not apply the parent stream. 17.4.1.2.2.5 POS_T::operator-=(OFF_T); [Almost same as in the WP:17.4.2.2.5] If the parent stream is not arbitrary-positional, the value of the operation becomes invalid so it may not apply the parent stream. 17.4.1.2.2.6 POS_T::operator==(POS_T&); [Almost same as in the WP:17.4.2.2.6] 17.4.1.2.2.7 POS_T::operator!=(POS_T&); [Almost same as in the WP:17.4.2.2.7] 17.4.1.2.3 Type streamoff typedef T2 streamoff; The type streamoff is a synonym for one of the singed basic integral types T2 whose representation has at least as many bits as type long. The corresponding POS_T class is the class, streampos. It is used to represent; -- a signed displacement, measured in bytes, from a specified position within a sequence. If a streamoff object has a value other than the parent stream returns (for example, assigned an arbitrary integer), the value may not apply any streams. Any streamoff object can be converted to a streampos object is ensured. But no validity of the result streampos object is ensured, whether the streamoff object is valid or else. 17.4.1.2.4 Class streampos class streampos { public: streampos (streamoff off = 0); streamoff offset () const; streamoff operator-(streampos& rhs); streampos& operator+=(streamoff off); streampos& operator-=(streamoff off); streampos operator+(streamoff off); streampos operator-(streamoff off); bool operator==(streampos& rhs) const; bool operator!=(streampos& rhs) const; }; [Almost the same description as in the WP:17.4.2.2 streampos] 17.4.1.2.5 Type wstreamoff [Almost the same description as in the WP:17.4.2.1 streamoff] 17.4.1.2.6 Class wstreampos [Almost the same description as in the WP:17.4.2.2 streampos] 17.4.1.3 Class basic_ios ###################################################################### ## A part of the declaration is omitted because the part is quite ## the same as those in the traditional 'ios' class. ###################################################################### template > class basic_ios { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } private: typedef basic_ios ios_type; ###################################################################### ## Note: An idea to declare eof as a constant, that is, static const ## IEOF = baggage::char_bag::eof();, is rejected because it cause a ## constraint that charT and int_type should be integral ## types. ###################################################################### public: class failure public: xmsg { ... (same as in the traditional ios) }; typedef T1 fmtflags; ... (same as in the traditional ios) basic_ios (basic_streambuf* sb_arg); virtual ~basic_ios(); operator void*(); int operator!() const; ios_type& copyfmt(const ios_type& rhs); basic_ostream* tie() const; basic_ostream* tie(basic_ostream* tiestr_arg); basic_streambuf* rdbuf() const; basic_streambuf* rdbuf(basic_streambuf* sb_arg); ###################################################################### ## Note: template parameter coupling between basic_ios and ## basic_streambuf: Both basic_ios and basic_streambuf corresponding ## to it should take the same template parameter . We ## need not allow to make a couple of basic_ios and ## basic_streambuf. ###################################################################### ... (same as in the ios) ###################################################################### ## Specifying fill character. It is represented as int_type. ###################################################################### int_type fill(int_type ch); ###################################################################### ## Imbueing locale object. ###################################################################### locale imbue (locale loc); locale getloc (); ###################################################################### ## Note: imbue/getloc member functions based on Nathan's 93-0167R1, ## N0374R1 ###################################################################### protected: basic_ios(); init(basic_streambuf* sb_arg); private: // basic_streambuf* sb; exposition only // basic_ostream* tiestr; exposition only // iostate state; exposition only // iostate except; exposition only // fmtflags fmtfl; exposition only // int prec, wide; exposition only // char_type fillch; exposition only // static int index; exposition only // int* iarray; exposition only // void** parray; exposition only ###################################################################### ## the locale member object. Class locale object is immutable. So we ## do not worry about its size. ###################################################################### // locale local; exposition only }; The template class basic_ios serves as a base class for the classes basic_istream and basic_ostream. It defines several member types: -- a class failure derived from xmsg; -- a class Init; -- three bitmask types, fmtflags, iostate, and openmode; -- an enumerated type seekdir. It maintains several kinds of data: -- a pointer to a stream buffer, an object of class basic_streambuf, that controls sources (input) and sinks (output) of 'character' sequences; the parameter 'charT' specifies the type of 'character'; -- state information that reflects the integrity of the stream buffer. -- constrol information that influences how to interpret (format) input sequences and how to generate (format) output sequences; -- additional information that is stored by the program for its private use. For the sake of exception, the maintained data is presented here as; -- ...(to be defined) 17.4.1.3.1 Class basic_ios::failure ... 17.4.1.3.2 Type basic_ios::fmtflags ... 17.4.1.3.3 Type basic_ios::iostate ... 17.4.1.3.4 Type basic_ios::openmode (To be defined: How should we handle the Coment Box 135,136?) 17.4.1.3.5 Type basic_ios::seekdir ... 17.4.1.3.6 Type basic_ios::io_state ... 17.4.1.3.7 Type basic_ios::open_mode ... 17.4.1.3.8 Type basic_ios::seek_dir ... 17.4.1.3.9 Class basic_ios::Init ... ###################################################################### ### Note: The behavior of cin, cout, cerr, clog will be specified in ### each definition part. ###################################################################### class Init { public: Init(); ~Init(); private: // static init init_cnt; exposition only }; The class Init describes an object whose construction ensures the construction of the four objects declared in that associate file stream buffers with the standard C streams provided for by the founctions declared in . For the sake of exposition, the maintained data is presented here as; -- static int init_cnt, counts the number of constructor and destructor calls for class Init, initialized to zero. 17.4.1.3.9.1 basic_ios::Init::Init() Init(); Constructs an object of class Init. If init_cnt is zero, the function stores the value one in init_cnt, then constructs and initializes the four objects cin(17.4.9.1), cout (17.4.9.2), cerr (17.4.9.3), and clog (17.4.9.4). In any case, the function then adds one to the value stored in init_cnt. 17.4.1.3.10 basic_ios::basic_ios(basic_streambuf*) basic_ios(basic_streambuf* sb_arg); Constructs ...(same as the corresponding description in WP) 17.4.1.3.11 basic_ios::~basic_ios() ... 17.4.1.3.12 basic_ios::operator void*() ... 17.4.1.3.13 basic_ios::operator!() ... 17.4.1.3.14 basic_ios::copyfmt(const basic_ios&) ... 17.4.1.3.15 basic_ios::tie() ... 17.4.1.3.16 basic_ios::tie(basic_ostream*) ... 17.4.1.3.17 basic_ios::rdbuf() ... 17.4.1.3.18 basic_ios::rdbuf(basic_streambuf*) ### Note: need to modify so as to describe the occurence of imbueing ### local::codecnv into the argument stream buffer. 17.4.1.3.19 basic_ios::rdstate()... 17.4.1.3.20 basic_ios::clear(iostate)... 17.4.1.3.21 basic_ios::clear(io_state)... 17.4.1.3.22 basic_ios::setstate(iostate)... 17.4.1.3.23 basic_ios::setstate(io_state)... 17.4.1.3.24 basic_ios::good()... 17.4.1.3.25 basic_ios::eof()... 17.4.1.3.26 basic_ios::fail()... 17.4.1.3.27 basic_ios::bad()... 17.4.1.3.28 basic_ios::exceptions()... 17.4.1.3.29 basic_ios::exceptions(iostate)... 17.4.1.3.30 basic_ios::exceptions(io_state)... 17.4.1.3.31 basic_ios::flags()... 17.4.1.3.32 basic_ios::flags(fmtflags)... 17.4.1.3.33 basic_ios::setf(fmtflags)... 17.4.1.3.34 basic_ios::setf(fmtflags, fmtflags)... 17.4.1.3.35 basic_ios::unsetf(fmtflags)... 17.4.1.3.36 basic_ios::fill() int_type fill() const; Returns fillch. 17.4.1.3.37 basic_ios::fill(int_type) int_type fill(int_type fillch_arg); Assigns fillch_arg to fillch and then returns the previous stored in fillch. 17.4.1.3.38 basic_ios::precision()... 17.4.1.3.39 basic_ios::precision(int)... 17.4.1.3.40 basic_ios::width()... 17.4.1.3.41 basic_ios::width(int)... 17.4.1.3.42 basic_ios::xalloc()... 17.4.1.3.43 basic_ios::iword(int)... 17.4.1.3.44 basic_ios::pword(int)... 17.4.1.3.45 basic_ios::imbue(locale const&) locale basic_ios::imbue(locale const& loc); Imbues the basic_ios with the locale object, loc. In case the member pointer of the basic_streambuf, sb has already initialized, this function imbues the object pointed to by sb, too. 17.4.1.3.46 basic_ios::getloc() locale basic_ios::getloc() const; Returns the classic "C" locale if no locale has been imbued. Otherwise it returns the member local. 17.4.1.3.47 basic_ios::basic_ios() basic_ios(); Constructs ...[Same as in the Draft] 17.4.1.3.48 basic_ios::init(basic_streambuf*) init(basic_streambuf* sb_arg); Assigns: -- sb_arg to sb; ...[same as in the Draft] -- new locale() to local, which means the default value is the current global locale. ###################################################################### ### Note: the default locale value shall be 'global' but not ### transparent because the locality of the stream buffer will be ### unchanged between its lifetime. ###################################################################### 17.4.1.4 dec(basic_ios&)... 17.4.1.5 fixed(basic_ios&)... 17.4.1.6 hex(basic_ios&)... 17.4.1.7 internal(basic_ios&)... 17.4.1.8 left(basic_ios&)... 17.4.1.9 noshowbase(basic_ios&)... 17.4.1.10 noshowpoint(basic_ios&)... 17.4.1.11 noshowpos(basic_ios&)... 17.4.1.12 noskipsws(basic_ios&)... 17.4.1.13 nouppercase(basic_ios&)... 17.4.1.14 oct(basic_ios&)... 17.4.1.15 right(basic_ios&)... 17.4.1.16 scientific(basic_ios&)... 17.4.1.17 showbase(basic_ios&)... 17.4.1.18 showpoint(basic_ios&)... 17.4.1.19 showpos(basic_ios&)... 17.4.1.20 skipws(basic_ios&)... 17.4.1.21 uppercase(basic_ios&)... 17.4.1.22 Class ios; class ios : public basic_ios {} The class ios is a version of the template class, basic_ios, specialized by the type 'char'. 17.4.1.23 Class wios; class wios : public basic_ios {} The class wios is a version of the template class, basic_ios specialized by the type wchar_t. 17.4.2 Header The Header defines two macro and three types that control input from and output to character sequences. The following template struct defined in the Header has already been specified in the correponding subsections of the Standard; 17.4.1.1 template struct ios_baggage, 17.4.1.1.1 template struct ios_char_baggage, 17.4.1.2.1 template struct ios_pos_baggage, The following specialized template struct defined in the Header has already been specified in the corresponding subsection of the Standard; 17.4.1.1.1 struct ios_char_baggage, 17.4.1.1.1 struct ios_char_baggage, 17.4.1.2.1 struct ios_pos_baggage, 17.4.1.2.1 struct ios_pos_baggage, 17.4.1.2.3 Type streamoff, 17.4.1.2.4 Class streampos, 17.4.1.2.5 Type wstreamoff, 17.4.1.2.6 Class wstreampos. 17.4.2.1 Template class basic_streambuf template > class basic_streambuf { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: ~virtual basic_streambuf (); pos_type pubseekoff (off_type off, ios_seekdir way, ios_openmode which = ios::in | ios::out); pos_type pubseekpos (pos_type sp, ios_openmode which = ios::in | ios::out); basic_streambuf* pubsetbuf (char_type* s, streamsize n); int pubsync(); int_type sbumpc(); int_type sgetc(); int sgetn(char_type* s, streamsize n); int_type snextc(); int_type sputbackc(char_type c); int sputn(const char_type* s, streamsize n); protected: basic_streambuf (); char_type* eback() const; char_type* gptr() const; char_type* egptr() const; void gbump(int n); void setg(char_type* gbeg_arg, char_type* gnext_arg, char_type* gend_arg); char_type* pbase() const; char_type* pptr() const; char_type* epptr() const; void pbump(int n); void setp(char_type* pbeg_arg, char_type* pend_arg); virtual int overflow(int_type c = eof()); virtual int pbackfail(int_type c = eof()); virtual int underflow(); virtual int uflow(); virtual int xsgetn(char_type* s, streamsize n); virtual int xsputn(const char_type* s, streamsize n); virtual pos_type seekoff(off_type, ios::seekdir way, ios_openmode:: which = ios::in | ios::out); virtual pos_type seekpos(pos_type sp, ios_openmode:: which = ios::in | ios::out); virtual basic_streambuf* setbuf(char_type* s, streamsize n); virtual int sync(); ###################################################################### ## The following two member functions are introduced to support Raw ## byte I/O, whose behaviors are implementation-defined. ###################################################################### virtual streamsize write_byte (const char* buf, streamsize len); virtual streamsize read_byte (char* buf, streamsize len); private: char_type* gbeg; char_type* gnext; char_type* gend; char_type* pbeg; char_type* pnext; char_type* pend; }; The template class basic_streambuf serves as an abstract base class for deriving various stream buffers whose objects each control two 'character' sequences: -- a 'character' input sequence; -- a 'character' output sequence. Stream buffers can impose various constraints on the sequence they control. Some constraints are: -- The controlled input sequence can be not readable. -- The controlled output sequence can be not writable. -- The controlled sequences can be associated with the contents of other representations for 'character' sequences, such as external files. -- The controlled sequences can support operations directly to or from associated sequences. -- The controlled sequences can impose limitations on how the program can read 'character's from a sequence, write 'character's to a sequence, put 'character's back into an input sequence, or alter the stream position. Each sequence is characterized by three pointers which, if non-null, all point into the same charT type array object. The array object represents, at any moment, a (sub)sequence of 'character's from the sequence. Operations performed on a sequence alter the values stored in these pointers, perform reads and writes directoly to or from associated sequences, and alter "the stream position" as needed to maintain thes subsequence relationship. The three pointers are: -- the beginning pointer, or lowest element address in the array (called xbeg here); -- the next pointer, or next element address that is a current candidate for reading or writing (called xnext here); -- the end pointer, or the first element address beyond the end of the array(called xend command). The following semantic constraints shall always apply for any set of three pointers, using the pointer names given immediately above: -- If xnext is not a null pointer, then xbeg and xend shall also be non-null pointers into the same array, as described above. -- If xnext is not a null pointers and xnext < xend for an output sequence, then a write position is available. IN ths case, *xnext shall be assignable as the next element to write (to put, or to store a character value, into the sequence). -- If xnext is not a null pointer and xbeg < xnext for an input sequence, then a read position is available. In this case, *xnext shall have a defined value and is the next element to read (to get, or to obtain a character value, from the sequence). For the sake of exposition, the maintained data is presented here as: -- char* gbeg, the beginning pointer for the input sequence; -- char* gnext, the next pointer for the input sequence; -- char* gend, then end pointer for the input sequence; -- char* pbeg, the beginning pointer for the output sequence; -- char* pnext, the next pointer for the output sequence; -- char* pend, the end pointer for the output sequence. 17.4.2.1.1 ... [Almost same as in WP:17.4.2.3.1] 17.4.2.1.2 ... [Almost same as in WP:17.4.2.3.2] 17.4.2.1.3 ... [Almost same as in WP:17.4.2.3.3] 17.4.2.1.4 ... [Almost same as in WP:17.4.2.3.4] 17.4.2.1.5 ... [Almost same as in WP:17.4.2.3.5] 17.4.2.1.6 ... [Almost same as in WP:17.4.2.3.6] 17.4.2.1.7 ... [Almost same as in WP:17.4.2.3.7] 17.4.2.1.8 basic_streambuf::sbumpc() int_type sbumpc(); If the input sequence does not have a read position available, return uflow(). Otherwise, the function returns (char_type)*gnext++. 17.4.2.1.9 basic_streambuf::sgetc() int_type sgetc(); If the input sequence does not have a read position available, return underflow(). Otherwise, the function returns (char_type)*gnext. 17.4.2.1.10 basic_streambuf::sgetn(char_type*, streamsize) int sgetn(char_type* s, streamsize n); Returns xsgetn(s, n). 17.4.2.1.11 basic_streambuf::snextc() int_type snextc(); Calls sbumpc() and, if that function returns baggage::char_bag::eof(), returns baggage::char_bag::eof(). Otherwise, the function returns sgetc(). ### Note: baggage::eod() ... the definition of EOF 17.4.2.1.12 basic_streambuf::sputbackc(char_type) int_type sputbackc(char_type c); If the input sequence does not have a putback position available, or if c != gnext[-1], returns pbackfail(c). Otherwise, the function returns (char_type)*--gnext. 17.4.2.1.13 basic_streambuf::sungetc() int_type sungetc(); If the input sequence does not have a putback position available, returns pbackfail(). Otherwise, the function returns (char_type)*--gnext. 17.4.2.1.15 basic_streambuf::sputn(const char_type*, streamsize) int sputn(const char_type* s, streamsize n); Returns xsputn(s, n). 17.4.2.1.16 basic_streambuf::basic_streambuf() basic_streambuf(); Constructs an object of class basic_streambuf() and initialize; -- all its pointer member objects to null pointers, -- the local member object to the return value of locale::global(). ###################################################################### ## Once the local member is initialized its locale-dependent behavior ## does not change until the next imbueing of the locale. ###################################################################### 17.4.2.1.17 .... 17.4.2.1.18 .... 17.4.2.1.19 .... 17.4.2.1.20 .... 17.4.2.1.21 .... 17.4.2.1.22 .... 17.4.2.1.23 .... 17.4.2.1.24 .... 17.4.2.1.25 .... 17.4.2.1.26 .... 17.4.2.1.27 basic_streambuf::overflow(int_type) ###################################################################### ## The following is my effort to describe by the teach of Jerry. ###################################################################### virtual int_type overflow(int_type c); Consumes some initial subsequence of the characters on the 'pending sequence'. The pending sequence of characters is defined as the concatenation of a) if pbeg is NULL then the empty sequence otherwise pnext - pbeg characters beginning at pbeg. b) if c == baggage::char_bag::eof() then the empty sequence otherwise the sequence consisting of c. The member functions, sputc, sputn call this function in case that no room can be found in the put buffer enough to accomodate the argument character sequence. Accoring to implementing this virtual function, every implementation shall obey the following constraints; 1) In case of consuming a character, it is unspecified whether appending it to the associated output stream or discarding it. 2) On an implementation in which cousuming means appending characters to the associated output stream, some characters of the pending sequence may not been appended. In such a case, let r be the number of characters in the pending sequence not appended to the output stream. Then pbeg and pnext must be set so that; pnext - pbeg == r and the r characters starting at pbeg are the associated output stream. In case all characters of the pending sequence have been appended to the assocated output stream, then either pbeg is set to NULL, or pbeg and pnext are both set to (the same) non-NULL value. 3) The function may fail if either appending some character to the associated output stream fails or if it is unable to establish pbeg and pnext according to the above rules. If the function fails it may signal that by returning baggage::char_bag::eof() or throwing an exception. Otherwise the function returns some value (other than baggage::char_bag::eof()) to indicate success. The default behavior is to return baggage::char_bag::eof(); 17.4.2.1.28 basic_streambuf::pbackfail(int_type) virtual int_type pbackfail(intT c = baggage::char_bag::eof()); Puts back the character designated by c to the input sequence, if possible, in one of five ways: -- If c != baggage::char_bag::eof(), if either the input sequence has a putback position available or the function makes a putback position available, and if (charT)c == (charT)gnext[-1], the function assigns gnext - 1 to gnext. The function signals success by returning (charT)c. -- If c != baggage::char_bag::eof(), if either the input sequence has a putback position available or the function makes a putback position available, and if the function is permitted to assign to the putback position, the function assigns c to *--gnext. The function signals success by returning (char_type)c. -- If c != baggage::char_bag::eof(), if no putback position is available, and if the function can put back a character directly to the associated input sequence, the function puts back c directly to the associate input sequence. The function signals success by returning (char_type)c. -- If c == baggage::char_bag::eof() and if either the input sequence has a putback position available or the function makes a putback posotion available, the function assigns gnext - 1 to gnext. The function signals success by returning (char_type)c. -- If c == baggage::char_bag::eof(), if no putback position is available, if the function can put back a character directly to the associated input sequence, and if the function can determine the character x immediately before the current position in the associaged input sequence, the function put back x directly to the associated input sequence. The function signals success by returning a value other than baggage::char_bag::eof(). If the function can succeed in more than one of these ways, it is unspecified which way is chosen. The function can alter the number of putback positions available as a result of any call. How (or whether) the function makes a putback position available, puts back a character directly to the input sequence, or determines the character immediately before the current position in the associated input sequence is defined separately for each class derived from basic_streambuf in this clause. The function return baggage::char_pos::eof() to signal the failure. The default behavior is to return baggage::eof(). 17.4.2.1.29 basic_streambuf::underflow() ###################################################################### ## Adopt the Jerry's comment ###################################################################### virtual int_type underflow(); Returns the first character of the 'pending sequence', if possible, without moving the stream position past it. If the pending sequence is null then the function fails. The pending sequence of characters is defined as the concatenation of; a) If gnext is non-NULL, then the gend - gnext characters starting at gnext, otherwise the empty sequence. b) Some sequence (possibly empty) of characters read from the input stream. The result character is the first character of the 'pending sequence', if any. The backup sequence is defined as the concatenation of; a) If gbeg is non-NULL then empty, otherwise the gnext - gbeg characters beginning at gbeg. b) the result character. The function sets up the gnext and gend satisfying; a) In case the pending sequence has more than one character the gend - gnext characters starting at gnext are the characters in the pending sequence after the result character. b) If the pending sequence has exactly one character, then gnext and gend may be NULL or may both be set to the same non-NULL pointer. If gbeg and gnext are non-NULL then the function is not constrained as to their contents, but the "unusual backup condition" is that either; a) If the backup sequence contains at least gnext - gbeg characters then the gnext - gbeg characters starting at gbeg agree with the last gnext - gbeg characters of the backup sequence. b) Or the n characters starting a gnext - n agree with the backup sequence (where n is the length of the backup sequence) The function returns baggage::char_bag::eof() to indicate failure. The default behavior is to return baggage::char_bag::eof(). 17.4.2.1.30 basic_streambuf::uflow() ###################################################################### ## Adopt the jss comment ###################################################################### virtual intT uflow(); Call underflow(baggage::char_bag::eof()). If underflow returns baggage::char_bag::eof(), return baggage::char_bag::eof(). If there is a read position available then do gbump(-1) and return (char_type)*gnext. 17.4.2.1.31 basic_streambuf::xsgetn(char_type*, streamsize) virtual streamsize xsgetn(char_type* s, streamsize n); Assigns up to n characters to successive elements of the array whose first element is designated by s. The characters assigned are read from the input sequence as if by repeated calls to sbumpc(). Assigning stops when either n characters have been assigned or a call to sbumpc() would return baggage::char_bag::eof(). The function returns the number of character assigned. 17.4.2.1.32 basic_streambuf::xsputn(const charT*, streamsize) virtual streamsize xsputn (const charT* s, streamsize); Writes up to n characters to the output sequence as if by repeated calls to sputc(c). The characters written are obtained from successive elements of the array whose first element is designated by s. Writing stops when either n characters have been written or a call to sputc(c) would return baggage::char_bag::eof(). The function returns the number of characters written. 17.4.2.1.33 basic_streambuf::seekoff(off_type, ios::seekdir, ios::openmode) virtual pos_type seekoff (off_type off, ios::seekdir way, ios::openmode which = ios::in | ios::out); Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived from basic_streambuf in this clause. The default behavior is to return an object of class pos_type that stores an invalid stream position. 17.4.2.1.34 basic_streambuf::seekpos(pos_type, ios::openmode) virtual pos_type seekpos (pos_type pos, ios::openmode which = ios::in | ios::out); Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived from basic_streambuf in this clause. The default behavior is to return an object of class posT that stores an invalid stream position. 17.4.2.1.35 .... 17.4.2.1.36 basic_streambuf::sync() virtual int sync(); Synchronizes the controlled sequences with any associated external sources and sinks of characters in a way that is defined separately for each class derived from basic_streambuf in this clause. The function returns -1 if it fails. The default behavior is to return zero. 17.4.2.1.37 basic_streambuf::read_byte (char*, streamsize) streamsize basic_streambuf::read_byte (char* s, streamsize n); Assigns up to n bytes to successive elements of an array whose first element is designated by s. How the characters written are obtained is the implementation-defined. Assigning stops when either n characters have been assigned or end-of-file occurs on the input sequence. The function returns the number of characters assigned. ###################################################################### ## The reason that the behavior of read_byte is unspecified(or ## implementation-defined) is because we cannot assume the nature of ## the external source/sink stream. If the external source/sink ## stream is a byte stream, we have a chance to specify more clear ## description about the behavior. In really, there is no insurance ## that the external stream be a byte sequence. In case the stream is ## a wide character stream. How we should convert it to a byte ## sequence, use 'narrow' functions, every wide character breaks an ## element of bytes, or converted into a multibyte character sequence? ## because even library users can customize the C++ iostream, any kind ## of external source/sink stream may be applied and any kind of ## conversion will be challenged. So I decide the Standard should ## provide any specification about the nature of the conversion. ###################################################################### 17.4.2.1.38 basic_streambuf::write_byte (const char*, streamsize) streamsize basic_streambuf::write_byte (const char* s, streamsize n); Writes up to n bytes to the output sequences. The bytes written are obtained from successive elements of the array whose first element is designated by s. How the bytes written are converted to the external source/sink stream is implementation-defined. Writing stops when either n characters have been written or a writing fails. The function returns the number of characters 17.4.2.2 Class streambuf class streambuf : public basic_streambuf {}; The class streambuf is a version of the template class, basic_streambuf, specialized by the type 'char'. 17.4.2.3 Class wstreambuf class wstreambuf : public basic_streambuf {}; The class wstreambuf is a version of the template class, basic_streambuf, specialized by the type 'wchar_t'. 17.4.3 Header The header defines two template types, two type and several function signatures that control input from a stream buffer. 17.4.3.1 Template class istream_iterator ###################################################################### ## According to one of Nathan's request[X3J16/94-0092,WG21/N0479], I ## introduce the following definition of 'istream_iterator'. ###################################################################### template > class istreambuf_iterator { public: typedef charT char_type; typedef baggage baggage_type; typedef baggage::int_type int_type; typedef basic_streambuf streambuf; typedef basic_istream istream; class proxy { charT keep_; streambuf* sbuf_; proxy (charT c, streambuf* sbuf) : keep_(c), sbuf_(sbuf) {} public: charT operator*() { return keep_; } friend class istreambuf_iterator; }; public: istreambuf_iterator (); istreambuf_iterator (istream& s); istreambuf_iterator (streambuf* s); istreambuf_iterator (const proxy& p); charT operator*(); istreambuf_iterator& operator++(); proxy operator++(int); bool equal (istreambuf_iterator& b); private: // streambuf* sbuf_; exposition only }; The template class, 'istreambuf_iterator', reads successive 'character's from the streambuf for which it was constructed. After it is constructed, and every time the 'operator++' is used, the iterator reads and stores a value of 'character'. If the end of stream is reached (streambuf::sgetc() returns baggage::char_bag::eof()), the iterator becomes equal to the 'end of stream' iterator value. The default constructor 'istreambuf_iterator()' and the constructor 'istreambuf_iterator(0)' always construct an end of stream iterator object, which is the only legitimate iterator to be used for the end condition. The result of operator*() on an end of stream is undefined. For any other iterator value a 'const char_type&' is returned. It is impossible to store things into input iterators. Note that in the input iterators, ++ operators are not equality preserving, that is, i == j does not guarantee at all that ++i == ++j. Every time ++ is used a new value is used. The practical consequence of this fact is that an 'istreambuf_iterator' object can be used only for one-pass algorithms, which actually makes perfect sense, since for multi-pass algorithms it is always more appropriate to use in-memory data structures. Two end of stream iterators are always equal. An end of stream iterator is not equal to a non-end of stream iterator. Two non-end of stream iterators are equal when they are constructed from the same stream. 17.4.3.1.1 Template class istreambuf_iterator::proxy template > class istream_iterator::proxy { charT keep_; streambuf* sbuf_; proxy (charT c, streambuf* sbuf) : keep_(c), sbuf_(sbuf) {} public: charT operator*() { return keep_; } friend class istreambuf_iterator; }; Class 'istream_iterator::proxy' provides a temporal placeholder as the return value of the post-increment operator (operator++). It keeps the character pointed to by the previous value of the iterator for some possible future access to get the character. 17.4.3.1.2 istreambuf_iterator::istreambuf_iterator () istreambuf_iterator (); Constracts the end-of-stream iterator. 17.4.3.1.3 istreambuf_iterator::istreambuf_iterator (basic_istream&) istreambuf_iterator (basic_istream& s); Constracts the istream_iterator pointing to the basic_streambuf object; *(s.rdbuf()). 17.4.3.1.4 istreambuf_iterator::istreambuf_iterator (const proxy&) istreambuf_iterator (const proxy& p); Constracts the istreambuf_iterator pointing to the basic_streambuf object related to the proxy object, p. 17.4.3.1.5 istreambuf_iterator::operator*() charT istreambuf_iterator::operator*() Extract one 'character' pointed to by the streambuf, (*sbuf_). 17.4.3.1.6 istreambuf_iterator::operator++() istreambuf_iterator& istreambuf_iterator::operator++(); Advances the iterator and returns the result 17.4.3.1.7 istreambuf_iterator::operator++(int) proxy istreambuf_iterator::operator++(int); Advances the iterator and returns the 'proxy' object keeping the character pointed to by the previous iterator.. 17.4.3.1.8 istreambuf_iterator::equal(istreambuf_iterator&) bool istreambuf_iterator::equal(istreambuf_iterator& b); Determines whether the two of the iterator is equal. The equality between two iterator, a and b,is defined as follows; -- If both a and b are end-of-stream iterators, a == b. -- If either one of the two(the iterator, a) is an end-of-stream iterators, if b points end-of-file, a == b, otherwise a != b. -- If both a and b are not end-of-stream, the two streambuf pointed to by the both iterators are compared. 17.4.3.1.9 Function iterator_category (const istreambuf_iterator&); input_iterator iterator_category (const istreambuf_iterator& s); Returns the category of the iterator, s. 17.4.3.1.10 Template function operator==(istreambuf_iterator&, istreambuf_iterator&) template > bool operator==(istreambuf_iterator& a, istreambuf_iterator& b); Returns a.equal (b). 17.4.3.1.11 Template function operator!=(istreambuf_iterator&, istreambuf_iterator&) template > bool operator!=(istreambuf_iterator& a, istreambuf_iterator& b); Returns !a.equal (b). 17.4.3.2 Class basic_istream template > class basic_istream : virtual public basic_ios { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } private: // for abbrebiation. typedef basic_istream istream_type; typedef basic_ios ios_type; public: basic_istream(basic_streambuf* sb); virtual ~basic_istream(); int ipfx(int noskipws = 0); void isfx(); istream_type& operator>>(istream_type& (*pf)(istream_type&)); istream_type& operator>>(ios_type& (*pf)(ios_type&)); istream_type& operator>>(char_type* s); istream_type& operator>>(char_type& c); istream_type& operator>>(short& n); .... istream_type& operator>>(basic_streambuf& sb); int_type get(); istream_type& get(char_type* s, streamsize n, char_type delim = baggage::char_bag::newline()); istream_type& get(char_type& c); istream_type& get(basic_streambuf& sb, char_type baggage::char_bag::delim = newline()); istream_type& getline(char_type* s, streamsize len, char_type delim = baggage::char_bag::newline()); istream_type& ignore (streamsize n = 1, int_type delim = baggage::char_bag::eof()); istream_type& read(char_type* s, streamsize n); ###################################################################### ## A new member function for supporting the raw byte I/O in which it ## performs 'rdbuf().read_byte (s, n);' ###################################################################### istream_type& read_byte (char* s, streamsize n); int_type peek(); istream_type& putback(char_type c); istream_type& unget(); streamsize gcount() const; int sync(); private: // streamsize chcount; exposition only }; The class basic_istream defines a number of member function signatures that assist in reading and interpreting input from sequences controlled by a stream buffer. Two groups of member function signatures share common properties: the formatted input functions (or extractors) and the unformatted input functions. Both groups of input functions obtain (or extract) input characters by calling the function signatures sb.sbumpc(), sb.sgetc(), and sb.sputbackc(char_type). If one of these called functions throws an exception, the input function calls setstate(badbit) and rethrows the exception. -- The formatted input functions are: ....[same as in WP:17.4.3.1] -- The unformatted input functions are: ....[Same as in WP:17.4.3.1] Each formatted input function begins execution by calling ipfx(). If that function returns nonzero, the function endeavors to obtain the requested input. In any case, the formatted input function ends by calling isfx(), then returning the value specified for the formatted input function. Some formatted input functions endeavor to obtain the requested input by parsing 'character's extracted from the input sequence, converting the result to a value of some scalar data type, and storing the converted value in an object of that scalar data type. ###################################################################### ## The numeric conversion behaviors of the following extractors are ## locale-dependent. ## ## basic_istream::operator>>(short& val); ## basic_istream::operator>>(unsigned short& val); ## basic_istream::operator>>(int& val); ## basic_istream::operator>>(unsigned int& val); ## basic_istream::operator>>(long& val); ## basic_istream::operator>>(unsigned long& val); ## basic_istream::operator>>(float& val); ## basic_istream::operator>>(double& val); ## basic_istream::operator>>(long double& val); ## ## As in the case of the inserters, these extractors depend on the ## Nathan Myers's locale::num_get<> object to perform parsing the input ## stream data. The conversion occurs as if it performed the following ## code fragment; ## ## HOLDERTYPE tmp; ## locale::num_get& fmt = loc.use< locale::num_get >(); ## fmt.get (iter, *this, loc, tmp); ## if ((val = (TYPE)tmp) != tmp) ## // set fail bit... ## ## In the above fragment, 'loc' stands for the private member of the ## 'basic_ios' class, TYPE stands for the type of the argument of the ## extractor, and HOLDTYPE is as follows; ## ## * for 'short', 'int' and 'long', the HOLDTYPE is 'long'; ## ## * for 'unsigned short', 'unsigned int' and 'unsigned long', the ## HOLDTYPE is 'unsigned long'. ## ## * for 'float', 'double', the HOLDTYPE is 'double'. ## ## * for 'long double', the HOLDTYPE is 'long double'. ## ## The first argument provides an object of the 'istream_iterator' ## class which is an iterator pointed to an input stream. It bypasses ## istreams and uses streambufs directly. Class locale relies on this ## type as its interface to istream, since the flexibility it has been ## abstracted away from direct dependence on istream. ###################################################################### In case the converting result is a value of either an integral type(short, unsigned short, int , unsigned int, long, unsigned long) or a float type(float, double, long double), performing to parse and convert the result depend on the imbued locale object. So the behavior of the above type extractors are locale-dependent. The imbued locale object uses an istreambuf_iterator to access the input character sequence. The behavior of other extractor functions is described in terms of the conversion specification for an equivalent call to the function signature fscanf (FILE*, const char*, ...), declared in with the following alternations: -- The formatted input function extracts 'character's from a stream buffer, rather than reading them from an input file. -- If flags() & skipws is zero, the function does not skip any leading white space. In that case, if the next input character is white space, the scan fails. -- If the converted data value cannot be represented as a value of the specified scalar data type, a scan failure occurs. ###################################################################### ## I wonder tue current locale::num_put/num_get facet cannot handle ## basefield specification. Need more discussion. ###################################################################### If the scan fails for any reason, the formatted function calls setstate(failbit). For conversion to an integral type other than a character type, the function determines the integral conversion specifier as follows: -- If (flags() & basefield) == oct, the conversion specifier is o. -- If (flags() & basefield) == hex, the conversion specifier is x. -- If (flags() & basefield) == 0, the conversion specifier is i. Otherwise, the integral conversion specifier is d for conversion to a signed integral type, or u for conversion to an unsigned integral type. Each unformatted input function begins execution by calling ipfx(1). If that function returns nonzero, the function endeavors to extract the requested input. It also counts the number of characters extracted. In any case, the unformatted input function ends by storing the count in a member object and calling isfx(), then returning the value specified for the unformatted input function. For the sake of exposition, the data maintained by an object of class istream is presented here as: -- int chcount, stores the number of characters extracted by the last unformatted input function called for the object. 17.4.3.2.1 basic_istream::basic_istream() basic_istream(basic_streambuf* sb); Constructs an object of class basic_istream, assigning initial values to the base class by calling ios::init(sb), then assigning zero to chcount. 17.4.3.2.2 .... 17.4.3.2.3 basic_istream::ipfx(int) int ipfx(int noskipws = 0); If good() is nonzero, prepares for formatted or unformatted input. First, if tie() is not a null pointer, the function calls tie()->flush() to synchronize the output sequence with any associated external C stream. (The call tie()->flush() does not necessarily occur if the function can determine that no synchronization is necessary.) If noskipws is zero and flags() & skipws is nonzero, the function extracts and discards each character as long as it is one of the whitespace characters for the next available input character, c. The decision if the character, c, is one of the whitespace character performs as if the following code fragment is performed; locale::ctype ctype = getloc().use >(); if (baggage::char_bag::is_whitespace (c, ctype)!=0) // c is a whitespace character. If after any preparation is completed, good() is nonzero, the function returns a nonzero value. Otherwise, it calls setstate(failbit) and returns zero. ###################################################################### ## The proposal will say as follows; ## ## The function 'basic_istream::ipfx()' uses the function, ## 'bool baggage::char_bag::is_whitespace(const locale*, charT)' in the ## baggage structure to determine whether the next input character is ## whitespace or not; ## ## A typical implementation of the ipfx function may be as follows; ## ## template > ## int basic_istream::ipfx() { ## ... ## // skipping whitespace according to a constraint function, ## // is_whitespace ## intT c; ## typedef locale::ctype ctype_type; ## ctype_type& ctype = getloc().use(); ## while ((c = rdbuf()->snextc()) != eof()) { ## if (!baggage::char_bag::is_whitespace (ctype, c)==0) { ## rdbuf()->sputbackc (c); ## break; ## } ## } ## ... ## } ## ## In case we use 'ios_baggage' or 'ios_baggage', the ## behavior of the constraint function, baggage::char_bag::is_whitespace() ## is as if it invokes, ## ## locale::ctype& ctype = getloc().use >(); ## ctype.is(locale::ctype::SPACE, c); ## ## otherwise, the behavior of the function, ## baggage::char_bag::is_whitespace() is unspecified. ## ## Those who want to use locale-independent whitespace predicate can ## specify their definition of is_whitespace in their new ## ios_char_baggage as follows; ## ## struct my_baggage : public ios_baggage { ## typedef my_char_baggage char_bag; ## }; ## ## struct my_char_baggage : public ios_char_baggage { ## static bool is_whitespace (const locale::ctype& ctype, char c) { ## ....(my own implementation)... ## } ## }; ###################################################################### 17.4.3.2.4 ... 17.4.3.2.5 ... 17.4.3.2.6 ... 17.4.3.2.7 basic_istream::operator>>(charT*) istream& operator>>(charT* s); A formatted input function, extracts character and stores them into successive locations of an array whose first element is pointed to by s. If width() is greater than zero, the maximum number of characters stored n is width(); otherwise it is INT_MAX, defined in . Characters are extracted and stored until any of the following occurs: -- n - 1 characters are stored; -- end-of-file occurs on the input sequence; -- baggage::char_bag::is_whitespace(c,ctype) is nonzero for the next available input character c. In the above code fragment, the argument, ctype, is acquinted by getloc().use >();. If the function stores no characters, it calls setstate(failbit). In any case, it then stores a null character into the next successive loction of the array and calls width(0). The function returns *this. 17.4.3.2.8 ... 17.4.3.2.9 ... 17.4.3.2.10 ... 17.4.3.2.11 ... 17.4.3.2.12 ... 17.4.3.2.13 ... 17.4.3.2.14 ... 17.4.3.2.15 ... 17.4.3.2.16 ... 17.4.3.2.17 ... 17.4.3.2.18 ... 17.4.3.2.19 ... 17.4.3.2.20 ... 17.4.3.2.21 ... 17.4.3.2.22 ... 17.4.3.2.23 basic_istream::operator>>(basic_streambuf&) basic_istream& operator>>(basic_streambuf& sb); A formatted input function, extracts 'character's from *this and inserts them in the output sequence controlled by sb. 'Character's are extracted and inserted until any of the following occurs: -- end-of-file occurs on the input sequence; -- inserting in the output sequence fails (in which case the character to be inserted is not extracted); -- an exception occurs (in which case the exception is caught but not rethrown). If the function inserts no characters, it calls setstate(failbit). The function returns *this. 17.4.3.2.24 ... 17.4.3.2.25 ... 17.4.3.2.26 ... 17.4.3.2.27 ... 17.4.3.2.28 ... 17.4.3.2.29 ... 17.4.3.2.30 ... 17.4.3.2.31 ... 17.4.3.2.32 ... 17.4.3.2.33 ... 17.4.3.2.34 ... 17.4.3.2.35 ... 17.4.3.2.36 ... 17.4.3.2.37 ... 17.4.3.2.38 ... 17.4.3.2.39 ... 17.4.3.2.40 ... 17.4.3.2.41 ... 17.4.3.2.42 ... 17.4.3.2.43 ... 17.4.3.2.44 basic_istream::read_byte (char*, streamsize) basic_istream& basic_istream::read_byte (char* s, streamsize n); An unformatted input function, extracts bytes by invoking; rdbuf()->read_byte (s, n); In case end-of-file occurs on the input character sequence, the function calls setstate(failbit). 17.4.3.3 ws(basic_istream&) ... 17.4.3.4 Class istream class istream : public basic_istream {}; [To Be Filled] 17.4.3.5 Class wistream class wistream : public basic_istream {}; [To Be Filled] 17.4.4 Header The header defines a type and several function signatures that control output to a stream buffer. 17.4.4.1 Template class ostream_iterator template > class ostreambuf_iterator { public: typedef charT char_type; typedef baggage baggage_type; typedef basic_streambuf streambuf; typedef basic_ostream ostream; private: streambuf* sbuf_; public: ostreambuf_iterator () : sbuf_(0) {} ostreambuf_iterator (ostream& s) : sbuf_(s.rdbuf()) {} ostreambuf_iterator (streambuf* s) : sbuf_(s) {} ostreambuf_iterator& operator*() { return *this; } ostreambuf_iterator& operator++() { return *this; } ostreambuf_iterator& operator++(int) { return *this; } ostreambuf_iterator& operator= (charT c) { sbuf_->sputc(baggage::to_int_type(c)); } bool equal (ostreambuf_iterator& b) { return sbuf_ == b.sbuf_; } }; output_iterator iterator_category (const ostreambuf_iterator&) { return output_iterator(); } template > bool operator==(ostreambuf_iterator& a, ostreambuf_iterator& b) { return a.equal (b); } template > bool operator!=(ostreambuf_iterator& a, ostreambuf_iterator& b) { return !a.equal (b); } ###################################################################### ## Because the class, locale::num_put<> depend on the class, ## 'ostreambuf_iterator' as the fundamental access way to the output ## stream with some efficiency, the class, 'ostreambuf_iterator' is ## defined in the header. ## ## The template class, 'ostreambuf_iterator' writes successive ## 'character's onto the output stream from which it was constructed. ## It is not possible to get a value out of the output iterator. ## ## Two output iterators are equal if they are constructed with the same ## output streambuf. ## ## The following is the definition of the class, 'ostreambuf_iterator'; ###################################################################### [To Be Filled] 17.4.4.2 Template class basic_ostream template > class basic_ostream : virtual public basic_ios { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } private: typedef basic_ostream ostream_type; public: basic_ostream (basic_streambuf* sb); virtual ~basic_ostream(); int opfx(); void osfx(); ostream_type& operator<<(ostream_type& (*pf)(ostream_type&)); ostream_type& operator<<(ios_type& (*pf)(ios_type&)); ostream_type& operator<<(const char_type* s); ostream_type& operator<<(charT c); ostream_type& operator<<(short n); .... ostream_type& operator<<(basic_streambuf& sb); ostream_type& put (); ostream_type& write (const char_type* s, streamsize n); ostream_type& write_byte (const char* s, streamsize n); ostream_type& flush(); }; The class ostream defines a number fof member function signatures that assist in formatting and writing output to output sequences controlled by a stream buffer. Two groups of member function signatures share common properties: the formatted output functions (or inserters) and the unformatted output functions. Both groups of output functions generate (or insert) output 'character's by calling the function signature sb.sputc(int). If the called function throws an exception, the output function calls setstate(badbit) and rethrows the exception. -- The formatted output functions are: ... -- The unformatted output functions are: ... Each formatted output function begins execution by calling osfx(). If that function returns nonzero, the function endeavors to generate the requested output. In any case, the formatted output function ends by calling osfx(), then returning the value specified for the formatted output function. ###################################################################### ## The following specification description has not reflected ## locale-dependency of the behavior of the integral type/float type ## inserters. ###################################################################### ###################################################################### ## The numeric conversion behaviors of the following inserters are ## locale-dependent. ## ## basic_ostream::operator<<(short val); ## basic_ostream::operator<<(unsigned short val); ## basic_ostream::operator<<(int val); ## basic_ostream::operator<<(unsigned int val); ## basic_ostream::operator<<(long val); ## basic_ostream::operator<<(unsigned long val); ## basic_ostream::operator<<(float val); ## basic_ostream::operator<<(double val); ## basic_ostream::operator<<(long double val); ## ## According to the Nathan Myers's locale object draft ## [X3J16/94-0064R1,WG21/N0451R1], the class locale::num_get<> and ## locale::num_put<> handle locale-dependent numeric formatting and ## parsing. The above inserter functions refers the imbued locale ## value to utilize these numeric formatting functionality. ## The formatting conversion occurs as if it performed the following ## code fragment; ## locale::num_put& fmt = loc.use< locale::num_put >(); ## fmt.put (ostreambuf_iterator(*this), *this, loc, val); ## In the above fragment, 'loc' stands for the private member of the ## 'basic_ios' class which maintains the imbued locale object. The ## first argument provides an object of the 'ostreambuf_iterator' class ## which is an iterator for ostream class. It bypasses ostreams and ## uses streambufs directly. Class locale relies on these types as its ## interface to iostream, since for flexibility it has been abstracted ## away from direct dependence on ostream. ###################################################################### Some formatted output functions endeavor to generate the requested output by convertion a value from some scalar or null-terminated byte string(NTBS) type to text form and inserting the converted text in the output sequence. The behavior of such functions is described in terms of the conversion specification for an equivalent call to thee function signature fprintf (FILE*, const char*, ...), declared in , with the following alterations: -- The formatted output function inserts characters in a stream buffer, rather than writing them to an output file. -- The formatted output function uses the fill character returned by fill() as the padding character(rather than the space character for left or right padding, or 0 for internal padding). If the operation fails for any reason, the formatted output function calls setstate(badbit). For conversion from an integral type other than a 'character' type, the function determines the integral conversion specifier as follows: -- If (flags() & basefield) == oct, ... -- If (flags() & basefield) == hex, ... Otherwise, the integral conversion specifier is d for conversion from a signed integral type, or u for conversion from an unsigned integral type. For conversion from a floating-point type, ... ###################################################################### ## I wonder tue current locale::num_put/num_get facet cannot handle ## basefield specification. Need more discussion. ###################################################################### -- If ... -- If ... Otherwise, the floating-point ... The conversion specifier has the following additional qualifiers ... -- ... -- ... -- ... -- ... Moreover, for any conversion, padding with the fill 'character' returned by fill() behaves as follows: -- ... -- ... Otherwise, the flag - is prepended ... Each unformatted output function begins execution by calling opfx(). If that function returns nonzero, the function endeavors to generate the requested output. In any case, the unformatted output function ends by calling osfx(), then returning the value specified for the unformatted output function. 17.4.4.2.1. basic_ostream::basic_ostream(basic_streambuf*) basic_ostream(basic_streambuf* sb); Constructs an object of class basic_ostream, assigning initial values to the base class by calling ios::init(sb), then assigning zero to chcount. 17.4.4.2.2 ... 17.4.4.2.3 basic_ostream::opfx() int opfx(); If good() is nonzero, prepares for formatted or unformatted output. If tie() is not a null pointer, the functtion calls tie()->flush(). It returns good(). ###################################################################### ## Note: Need to append the locale dependency on arrporiate extractors ###################################################################### 17.4.4.2.4 ... 17.4.4.2.5 ... 17.4.4.2.6 ... 17.4.4.2.7 ... 17.4.4.2.8 ... 17.4.4.2.9 ... 17.4.4.2.10 ... 17.4.4.2.11 ... 17.4.4.2.12 ... 17.4.4.2.13 ... ... 17.4.4.2.21 basic_ostream::operator<<(basic_streambuf&) basic_ostream& operator<<(basic_streambuf& sb); A formatted output function, extracts 'character's from the input sequence controlled by sb and inserts them in *this. Characters are extracted and inserted until any of the following occurs: -- end-of-file occurs on the input sequence; -- inserting in the output sequence fails (in which case the character to be inserted is not extracted); -- an exception occurs (in which case, the exception is rethrown). If the function inserts no characters, it calls setstate(badbit). The function returns *this. 17.4.4.2.22 ... 17.4.4.2.23 ... 17.4.4.2.24 ... 17.4.4.2.25 ... 17.4.4.2.26 ... 17.4.4.2.27 basic_ostream::write_byte (const char*, streamsize) streamsize basic_ostream::write_byte (const char* s, streamsize n); An unformatted output function, inserts bytes by invoking; rdbuf()->write_byte (s, n); In case writing characters fails, the function calls setstate(failbit). 17.4.4.3 endl(basic_ostream&) basic_ostream& endl(basic_ostream&); Calls os.put(baggage::newline()), then os.flush(). The function returns *this. 17.4.4.4 ends (basic_ostream&) [To Be Filled] 17.4.4.5 flush (basic_ostream&) [To Be Filled] 17.4.4.6 Class ostream [To Be Filled] 17.4.4.7 Class wstream [To Be Filled] 17.4.5 Header The header defines three template classes and several related functions that use these template classes to provide extractors and inserters that alter information maintained by class basic_ios and its derived classes. It also defines several instantiatins of these template classes and functions. 17.4.5.1 Template class basic_smanip template > class basic_smanip { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_smanip (ios_type& (*pf_arg)(ios_type&, T), T); // ios_type& (*pf)(ios_type&, T); exposition only // T manarg; exposition only }; The template class basic_smanip describes an object that can store a function pointer and an object of type T. The designated function accepts an argument of this type T. For the sake of exposition, the maintained data is presented here as: -- basic_ios& (*pf)(basic_ios&, T); the function pointer; -- T manarg, the object of type T. 17.4.5.1.1 ... 17.4.5.1.2 ... 17.4.5.1.3 ... 17.4.5.2 Template class basic_imanip template > > class basic_imanip { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_imanip (basic_ios& (*pf_arg)(basic_ios&, T), T); // basic_ios& (*pf)(basic_ios&, T); exposition only // T manarg; exposition only }; The template class basic_imanip ... 17.4.5.2.1 ... 17.4.5.2.2 ... 17.4.5.3 Template class basic_omanip 17.4.5.3.1 ... 17.4.5.3.2 ... 17.4.5.4 Instantiations of manipulators 17.4.5.4.1 basic_resetiosflag(ios::fmtflags) ... 17.4.5.4.2 basic_setiosflag(ios::fmtflags) ... 17.4.5.4.3 basic_setbase(int) ... 17.4.5.4.4 basic_setfill(int) ... 17.4.5.4.5 basic_setprecision(int) ... 17.4.5.4.6 basic_setw(int) ... 17.5.4.5 Template class smanip template class smanip : public basic_smanip {}; [To Be Filled] 17.5.5.6 Template class imanip template class imanip : public basic_imanip {}; [To Be Filled] 17.5.5.7 Template class omanip template class omanip : public basic_omanip {}; [To Be Filled] 17.5.5.8 Template class wsmanip template class wsmanip : public basic_smanip {}; [To Be Filled] 17.5.5.9 Template class wimanip template class wimanip : public basic_imanip {}; [To Be Filled] 17.5.5.10 Template class womanip template class womanip : public basic_omanip {}; [To Be Filled] 17.4.6 Header The header defines ... 17.4.6.1 Template class basic_strstreambuf template > class basic_strstreambuf : public basic_streambuf { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_strstreambuf (streamsize alsize_arg = 0); basic_strstreambuf (void* (*palloc_arg)(size_t), void* (*pfree_arg)(void*)); basic_strstreambuf (char_type* gnext_arg, streamsize n, char_type* pbeg_arg = 0); basic_strstreambuf (const char_type* gnext_arg, streamsize n); //## Note: null character constraint is needed in ios_baggage. virtual ~basic_strstreambuf(); void freeze (int = 1); char_type* str(); streamsize pcount(); protected: // virtual int_type overflow(int_type c = eof()); inherited // virtual int_type pbackfail(int_type c = eof()); inherited // virtual int_type underflow(); inherited // virtual int_type uflow(); inherited // virtual streamsize xsgetn(char_type* s, streamsize n); inherited // virtual streamsize xsputn(const char_type* s, streamsize n); inherited // virtual pos_type seekoff(off_type off, ios::seekdir way, inherited // ios::openmode which = ios::in | ios::out); // virtual pos_type seekpos(pos_type pos, inherited // ios::openmode which = ios::in | ios::out); // virtual basic_streambuf* setbuf(char_type* s, streamsize n); inherited // virtual int sync(); inherited private: // typedef T1 strstate; exposition only // static const strstate allocated; exposition only // static const strstate constant; exposition only // static const strstate dynamic; exposition only // static const strstate frozen; exposition only // strstate strmode; exposition only // streamsize alsize; exposition only // void* (*palloc)(size_t); exposition only // void (*pfree)(void*); exposition only }; The template class basic_strstreambuf is derived from basic_streambuf to associate the input sequence and possibly the output sequence with an object of some 'character' array type, whose elements store arbitrary values. The array object has several attributes. For the sake of exposition, these are represented as elements of a bitmask type (indicated here as T1) called strstate. The elements are: -- ... -- ... -- ... -- ... For the sake of exposition, the maintained data is presented here as: -- ... -- ... -- ... -- ... Each object of template class basic_streambuf has a seekable area, delimited by the pointers seeklow and seekhigh. If gnext is a null pointer, the seekable area is undefined. Otherwise, seeklow equals gbeg and seekhigh is either pend, if pend is not a null pointer, or gend. 17.4.6.1.1 ... 17.4.6.1.2 ... 17.4.6.1.3 ... 17.4.6.1.4 ... 17.4.6.1.5 ... 17.4.6.1.6 ... 17.4.6.1.7 ... 17.4.6.1.8 ... 17.4.6.1.9 ... 17.4.6.1.10 ... 17.4.6.1.11 basic_strstreambuf::str() charT* str(); Calls freeze(), then returns the beginning pointer for the input sequence, gbeg. 17.4.6.1.12 ... 17.4.6.1.13 basic_strstreambuf::overflow(intT) // virtual intT overflow(intT c = baggage::char_bag::eof()); inherted Appends the character designated by c to the output sequence, if possible, in one of two ways: -- IF c != baggage::char_bag::eof() and if either the output sequence has a write position available or the function makes a write position available (as described below), the function assigns c to *pnext++. The function signals success by returning (charT)c. -- If c == baggage::char_bag::eof(), there is no character to append. The function signals success by returning a value other than baggage::char_bag::eof(). The function can alter the number of write positions available as a result of any call. The function returns baggage::char_bag::eof() to indicate failure. To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements n to hold the current array object (if any), plus at least one additional write position. How many additional write positions are made available is otherwise unspecified. If palloc is not a null pointer, the function calls (* palloc)(n) to allocate the new dynamic array object. Otherwise, it evaluates the expression new charT[n]. In either case, if the allocation fails, the function returns baggage::char_bag::eof(). Otherwise, it sets allocated in strmode. To free a previously existing dynamic array object whose first element address is p: If pfree is not a null pointer, the function calls (*pfree)(p). Otherwise, it evaluates the expression delete[] p. If strmode & dynamic is zero, or if strmode & frozen is nonzero, the function cannot extend the array (reallocate it with greater length) to make a write position available. 17.4.6.1.14 basic_strstreambuf::pbackfail(intT) // virtual intT pbackfail(intT c = baggage::char_bag::eof()); inherited Puts back the character designated by c to the input sequence, if possible, in one of three ways: -- If c != baggage::char_bag::eof(), if the input sequence has a putback position available, and if (charT)c == gnext[-1], the function assigns gnext - 1 to gnext. The function signals success by returning (charT)c. -- If c != baggage::char_bag::eof(), if the input sequence has a putback position available, and if strmode & constant is zero, the function assigns c to *--gnext. The function signals success by returning (charT)c. -- If c == baggage::char_bag::eof() and if the input sequence has a putback position available, the function assigns gnext - 1 to gnext. The function signals success by returning (charT)c. ###################################################################### ## Note: cannot distinguish success and failure if c == EOF. ###################################################################### If the function can succeed in more than one of these ways, it is unspecified which way is chosen. The function can alter the number of putback positions available as a result of any call. The function returns baggage::char_bag::eof() to indicate failure. 17.4.6.1.15 basic_strstreambuf::underflow() //virtual intT underflow(); inherited Reads a character from the input sequence, if possible, without moving the stream position past it, as follows: -- If the input sequence has a read position available the function signals success by returning (charT)*gnext. -- Otherwise, if the current write next pointer pnext is not a null pointer and is greater than the current read end pointer gend, the function makes a read position available by assigning to gend a vaule greater than gnext and no greater than pnext. The function signals success by returning (charT)*gnext. The function can alter the number of read positions available as a result of any call. The fuction returns baggage::char_bag::eof() to indicate failure. 17.4.6.1.16 ... 17.4.6.1.17 ... 17.4.6.1.18 ... 17.4.6.1.19 basic_strstreambuf::seekoff(offT,ios:seekdir,ios::openmode) // virtual posT seekoff(offT off, ios::seekdir way, ios::openmode which = ios::in | ios::out); inherited Alters the stream position within one of the controlled sequences, if possible, as described below. The function returns posT(newoff), constructed from the resultant offset newoff (of type offT), that stores the resultant stream position, if possible. If the positioning operation fails, or if the constructed object cannot represent the resultant stream position, the object stores an invalid stream position. ###################################################################### ### Note: Need 'posT' object which stores an invalid stream position. ### Comment: Not clear if the constructed object cannot represent the ### resultant stream position ###################################################################### If which & ios::in is nonzero, the function positions the input sequence. Otherwise, if which & (ios::in | ios::out) equals ios::in | ios::out and if way equals either ios::beg or ios::end, the function positions both the input and the output sequences. Otherwise, the positioning operation fails. ###################################################################### ## Comment: I cannot understant this condition. If the 2nd condition ## is true, is the 1st condition always true? If so, the 2nd operation ## may occur, mayn't it? Would someone(possbly Bill) kindly tell me ## the situation? ###################################################################### For a sequence to be positioned, if its next pointer is a null pointer, the positioning operation fails. Otherwise, the function determines newoff in one of three ways: -- If way == ios::beg, newoff is zero. -- If way == ios::cur, newoff is the next pointer minus the beginning pointer(xnext - xbeg). -- If way == ios::end, newoff is the end pointer munus the beginning pointer(xend - xbeg). If newoff + off is less than seeklow - xbeg, or if seekhigh - xbeg is less than newoff + off, the positioning operation fails. Otherwise, the function assigns xbeg + newoff + off to the next pointer xnext. 17.4.6.1.20 basic_strstreambuf::seekpos(posT,ios::openmode) //virtual posT seekpos(posT sp, ios::openmode which = ios::in | ios::out); inherited Alters the stream position within one of the controlled sequences, if possible, to correspond to the stream position stored in sp (as described below). The function returns posT(newoff), constructed from the resultant offset newoff (of type offT), that stores the resultant stream position, if possible. If the positioning operation fails, or if the constructed object cannot represent the resultant stream position, the object stores an invalid stream position. If which & ios::in is nonzero, the function positions the input sequence. If which & ios::out is nonzero, the function positions the output sequence. If the function positions neither sequence, the positioning operation fails. For a sequence to be positioned, if its next pointer is a null pointer, the positioning operation fails. Otherwise, the function determines newoff from sp.offset(). If newoff is ann invalid stream position, has a negative value, or has a value greater than seekhigh - seeklow, the positioning operation fails. Otherwise, the function adds newoff to the beginning pointer xbeg and stores the result in the next pointer xnext. 17.4.6.1.21 ... 17.4.6.1.22 ... 17.4.6.2 Template class basic_istrstream template > class basic_istrstream : public basic_istream { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_istrstream(); basic_istrstream(const char_type* s); basic_istrstream(const char_type* s, streamsize n); basic_istrstream(char_type* s); basic_istrstream(char_type* s, streamsize n); virtual ~basic_istrstream(); basic_strstreambuf* rdbuf() const; private: // basic_strstreambuf sb; exposition only }; The class basic_istrstream is a derived of basic_istream ... 17.4.6.2.1 ... 17.4.6.2.2 ... 17.4.6.2.3 ... 17.4.6.2.4 ... 17.4.6.2.5 ... 17.4.6.2.6 ... 17.4.6.3 Template class basic_ostrstream template > class basic_ostrstream : public ostream { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_ostrstream(); basic_ostrstream(char_type* s, int n, openmode mode = out); ###################################################################### ## Comment: Is 'openmode' really 'ios::openmode'? ###################################################################### virtual ~basic_ostrstream(); basic_strstreambuf* rdbuf() const; void freeze(int freezefl); char_type* str(); int pcount() const; private: // basic_strstreambuf sb; exposition only }; The template class basic_ostrstreambuf is a derivative of basic_ostream ... 17.4.6.3.1 ... 17.4.6.3.2 ... 17.4.6.3.3 ... 17.4.6.3.4 ... 17.4.6.3.5 ... 17.4.6.3.6 ... 17.4.6.3.7 ... 17.4.7 Header The header defines three types that associate stream buffers with objects of class string, as described in subclase _string_. 17.4.7.1 Template class basic_stringbuf template > class basic_stringbuf : public basic_streambuf { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_stringbuf(ios::openmode which = ios::in | ios::out); basic_stringbuf(const basic_string& str, ios::openmode which = ios::in | ios::out); basic_string str() const; void str(const basic_string& str_arg); protected: // virtual int_type overflow(int_type c = eof()); inherited // virtual int_type pbackfail(int_type c = eof()); inherited // virtual int_type underflow(); inherited // virtual int_type uflow(); inherited // virtual streamsize xsgetn(char_type* s, streamsize n); inherited // virtual streamsize xsputn(const char_type* s, streamsize n); inherited // virtual pos_type seekoff(off_type off, ios::seekdir way, inherited // ios::openmode which = ios::in | ios::out); // virtual pos_type seekpos(pos_type pos, inherited // ios::openmode which = ios::in | ios::out); // virtual basic_streambuf* setbuf(char_type* s, int n); inherited // virtual int sync(); inherited private: // ios::openmode mode; exposition only. }; ###################################################################### ## Note: same 'charT' type string can be fed. ###################################################################### The template class basic_stringbuf is derived from basic_streambuf to associate possibly the input sequence and possibly the output sequence with a sequence of arbitrary 'character's. The sequence can be initialized from, or made available as, an object of template class basic_string. For the sake of ... -- ios::openmode mode, has ... For the sake of ... 17.4.7.1.1 ... ... 17.4.7.1.15 ... 17.4.7.2 Template class basic_istringstream template > class basic_istringstream : public basic_istream { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_istringstream(ios::openmode which = ios::in); basic_istringstream(const basic_string& str, ios::openmode which = ios::in); virtual ~basic_istringstream(); basic_stringbuf* rdbuf() const; basic_string str() const; void str(const basic_string& str); private: // basic_stringbuf sb; exposition only }; The class basic_istringstream is a derivative of istream ... 17.4.7.2.1 ... ... 17.4.7.2.6 ... 17.4.7.3 Template class basic_ostringstream template > class basic_ostringstream : public basic_ostream { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_ostringstream(ios::openmode which = ios::out); basic_ostringstream(const basic_string& str, ios::openmode which = ios::out); virtual ~basic_ostringstream(); basic_stringbuf* rdbuf() const; basic_string str() const; void str(const basic_string& str); private: // basic_stringbuf sb; }; The class basic_ostringstream is a derived of basic_ostream ... 17.4.7.3.1 ... ... 17.4.7.3.6 ... 17.4.7.4 Class stringbuf class stringbuf : public basic_stringbuf {}; [To Be Filled] 17.4.7.5 Class istringstream class istringstream : public basic_istringstream {}; [To Be Filled] 17.4.7.6 Class ostringstream class ostringstream : public basic_ostringstream {}; [To Be Filled] 17.4.7.7 Class wstringbuf class wstringbuf : public basic_stringbuf {}; [To Be Filled] 17.4.7.8 Class wistringstream class wistringstream : public basic_istringstream {}; [To Be Filled] 17.4.7.9 Class wostringstream class wostringstream : public basic_ostringstream {}; [To Be Filled] 17.4.8 Header The header defines one type, 'basic_convbuf'(forward reference: 18.4.8.2) that associate its internal stream buffers holding a sequence of 'character's with the external source/sink stream representing a sequence of another type of 'characters. [Conversion] There is a bidirectional conversion between the external source/sink stream and 'character' sequences held in the 'basic_convbuf' class object. [uchar_type: underlaid character container type] The external source/sink stream can be regarded as a sequence of a character container type, which may be different to 'charT'. The character container type on the external source/sink stream is called the 'underlaid character container type', or 'uchar_type'. [Encoding rule] Performing the conversion from a 'uchar_type' character sequences to the corresponding 'character' sequence, the 'basic_convbuf' may parse the 'uchar_type' sequence to extract the corresponding 'character' represented on the 'uchar_type' sequence. The rule how a certain 'character' be represented on a sequence of 'uchar_type' characters is called the 'encoding rule'. The 'basic_convbuf' can be regarded to have a (virtual) conversion machine which obeys the encoding rule to parse 'uchar_type' sequences. [Conversion state] The conversion machine has its internal state corresponding to a certain position of the external source/sink stream. If the 'basic_convbuf' stops the conversion to resume later, it has to save its internal state, so a class or a type is prepared for saving the state onto it so that an user of the 'basic_convbuf' class object can handle it. The class (or the type) is called the conversion state. ###################################################################### ## [Multibyte character I/O support] The 'basic_convbuf' can support ## multibyte character file I/O operations. Provided that the code ## conversion functions between multibyte characters and wide ## characters are prepared, we may specify the conversion state, and ## the conversion functions in the 'ios_conv_baggage' so that the ## 'basic_convbuf' can handle this multibyte characters. ###################################################################### 17.4.8.1 Template class conv_baggage template struct conv_baggage {} struct conv_baggage { typedef ios_char_baggage char_bag; typedef ios_pos_baggage pos_bag; typedef ios_conv_baggage conv_bag; }; The template struct conv_baggage is an baggage class which maintains the definitions of the types and functions necessary to implement the template class 'basic_convbuf'. The template parameter charT reprsents the character container type and each specialized version of 'conv_baggage' provides the default definitions corresponding to the specialized character container type. The 'conv_baggage' declaration has three buggages, ios_char_baggage, ios_pos_baggage, and ios_conv_baggage. Although the former two of them are same as in the ios_baggage, the last baggage, ios_conv_baggage provides all the definitions about types and functions necessary to perform conversion. 17.4.8.2 Template class ios_conv_baggage template struct ios_conv_baggage {}; As is the other baggage structs, there is no definition in the declaration of the template struct, 'ios_conv_baggage'. All of the definitions related to the conversion and necessary to implement 'basic_convbuf' class shall be provided in a template version, ios_conv_baggage specialized for a conversion state 'STATE_T'. 17.4.8.2.1 Specialized struct ios_conv_baggage struct ios_conv_baggage { typedef CHAR_T char_type; typedef STATE_T conv_state; typedef UPOS_T conv_upos; typedef UCHAR_T uchar_type; typedef POS_T pos_type; typedef OFF_T off_type; typedef locale::codecnv codecvt_in; typedef locale::codecnv codecvt_out; locale::result convin(codecvt_in*, conv_state&, const uchar_type*, const uchar_type*, const uchar_type*&, char_type*, char_typeT*, char_type*&); locale::result convout(codecvt_out*, conv_state&, const char_type*, const char_type*, const char_type*&, uchar_type*, uchar_type*, uchar_type*&); pos_type get_pos (conv_state&, conv_upos&); off_type get_off (conv_state&, conv_upos&); conv_state get_posstate (pos_type&); conv_state get_offstate (off_type&); conv_upos get_posupos (pos_type&); conv_upos get_offupos (off_type&); }; A specialized version of the struct ios_conv_baggage is necessary to use the 'basic_convbuf' class. In order to construct a specialized version of the struct, the following set of types and functions shall be provided. CHAR_T: is the character container type which shall be same as the template parameter of the class, 'conv_baggage'. STATE_T: is the conversion state type which also the template parameter type of this baggage. It is the parsing/tracing state which the function, convin and convout are taken. Every type of conversion states have a state, called 'initial state', which corresponds to the state beginning to parse a new sequence. The constructor, STATE_T::STATE_T() or STATE_T::STATE_T(0) constructs the initial state. UCHAR_T: is the underlaid character container type for the external source/sink stream handled by the 'basic_convbuf'. UPOS_T: is the repositional information type for the external source/sink stream. It is used to implement the seekpos/seekoff member functions in the 'basic_convbuf'. POS_T: is the repositional information which the 'basic_convbuf' supports for the client of the object. It shall be the same as the template parameter type of the struct 'ios_pos_baggage' in the same 'conv_baggage'. OFF_T: is an integral type which is used as the repositional information which the 'basic_convbuf' supports. The function, convin: The function, locale::result convin(codecvt_in* ccvt, conv_state& stat, const uchar_type* from, const uchar_type* from_end, const uchar_type*& from_next, char_type* to, char_typeT* to_limit, char_type*& to_next); is the code-conversion functions. The conversion state designated by 'stat' represents the parsing state on the underlaid source sequence. According to the conversion state designated by 'stat', it begins to parse the source character sequence whose begining and end position designated by 'from' and 'from_end' to convert them. It stores the result sequence (if any) into the successive location of an array pointed to by 'to' and 'to_limit'. The conversion stops when either of the following occurs; 1) parses all of the underlaid character sequences and stores the last 'character' into the destination array. 2) fills all of the destination array and no more room to store. 3) encounters an invalid underlaid character in the source sequence. In case (1), it returns ok, in case (2), it returns partial, or in case (3), it returns error. In all cases it leaves the 'from_next' and 'to_next' pointers pointing one beyond the last character successfully converted and leaves the conversion state onto the 'stat' for the next time conversion. If case (3) occurs, the conversion state on the 'stat' becomes undefined value. No more conversion with the value is available. If the locale-dependent conversion functions are needed, the nconversion function which the locale::codecnv facet object, ccnv provides is available as the following invokation; ccnv.convert (stat, from, from_end, from_next, to, to_limit, to_next); and the default conversion function is depends on the locale_codecvt facets. Users can customize the encoding scheme by specifying their own conversion functions in a new conv_baggage class. The function, convout: locale::result convout(codecvt_out* ccvt, conv_state&, const char_type from*, const char_type* from_end, const char_type*& from_next., uchar_type*, uchar_type*, uchar_type*&); is the code-conversion functions. The conversion state designated by 'stat' represents the parsing state on the underlaid destinate sequence. It begins to convert the source character sequence whose begining and end position designated by 'from' and 'from_end'. According to the conversion state designated by 'stat', it stores the result destination underlaid chracter sequence (if any) into the successive location of an array pointed to by 'to' and 'to_limit'. The conversion stops when either of the following occurs; 1) consumes all of the source character sequences and stores the last underlaid 'character' into the destination array. 2) fills all of the destination array and no more room to store. 3) encounters an invalid character in the source sequence. In case (1), it returns ok, in case (2), it returns partial, or in case (3), it returns error. In all cases it leaves the 'from_next' and 'to_next' pointers pointing one beyond the last character successfully converted and leaves the conversion state onto the 'stat' for the next time conversion. If case (3) occurs, the conversion state on the 'stat' becomes undefined value. No more conversion with the value is available. If the locale-dependent conversion functions are needed, the conversion function which the locale::codecnv facet object, ccnv provides is available as the following invokation; ccnv.convert (stat, from, from_end, from_next, to, to_limit, to_next); and the default conversion function is depends on the locale_codecvt facets. Users can customize the encoding scheme by specifying their own conversion functions in a new conv_baggage class. The functions, get_pos, get_off: pos_type get_pos (conv_state& stat, conv_upos& upos); off_type get_off (conv_state&, conv_upos&); Construct the pos_type object or off_type object from the conversion state, 'stat' and the repositional information for the underlaid stream, 'upos' and returns it. These are used to make the return value of the 'basic_convbuf::seekpos/seekoff' protected member function. The functions, get_posstate, get_offstate: conv_state get_posstate (pos_type& pos); conv_state get_offstate (off_type& off); Extract the conversion state held by the repositional information, pos or off. These are used to reset the conversion state maintained in the basic_convbuf class object when the 'basic_convbuf::seetpos/ seekoff' functions are performed. The functions, get_posupos, get_offupos: conv_upos get_posupos (pos_type&); conv_upos get_offupos (off_type&); Extract the repositioning information for the underlaid stream from the repositioning information on the 'basic_convbuf' stream. These are used in the 'basic_convbuf::seekpos/seekoff' protected member functions to reposition the external source/sink stream. 17.4.8.2.2 Specialized struct ios_conv_baggage struct ios_conv_baggage { typedef wchar_t char_type; typedef STATE_T conv_state; typedef UPOS_T conv_upos; typedef char uchar_type; typedef wstreampos pos_type; typedef wstreamoff off_type; typedef locale::codecnv codecnv_in; typedef locale::codecnv codecnv_out; locale::result convin (codecvt_in* ccvt, conv_state& stat, const char *from, const char* from_end, const char*& from_next, wchar_t* to, wchar_t* to_limit, wchar_t*& to_next) { return ccvt->convert (stat, from, from_end, from_next, to, to_limit, to_next); } locale::resutl convout (codecvt_out* ccvt, conv_state& stat, const wchar_t* from, const wchar_t* from_end, const wchar_t*& from_next, char* to, char* to_limit, char* to_next) { return ccvt->convert (stat, from, from_end, from_next, to, to_limit, to_next); } pos_type get_pos (conv_state&, conv_upos&); off_type get_off (conv_state&, conv_upos&); conv_state get_posstate (pos_type&); conv_state get_offstate (off_type&); conv_upos get_posupos (pos_type&); conv_upos get_offupos (off_type&); }; The specialized version of the struct, 'ios_conv_baggage' supports the wide-oriented 'basic_convbuf' class and the conversion between wide characters and multibyte characters as the underlaid character sequence. The types, STATE_T and UPOS_T are implementation- defined types. The behavior of the conversion functions depend on those of the locale object. The encoding rule of the multibyte characters is implementation- defined. 17.4.8.3 Template class basic_convbuf template > class basic_convbuf : public basic_streambuf { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } private: typedef baggage::conv_bag::conv_state state_type; typedef baggage::conv_bag::conv_upos upos_type ; public: basic_convbuf(); virtual ~basic_convbuf(); protected: // virtual int_type overflow(int_type c = eof()); inherited // virtual int_type pbackfail(int_type c = eof()); inherited // virtual int underflow(); inherited // virtual int uflow(); inherited // virtual streamsize xsgetn(charT* s, streamsize n); inherited // virtual streamsize xsputn(const charT* s, streamsize n); inherited // virtual pos_type seekoff(off_type, ios::seekdir way, // ios_openmode:: which = ios::in | ios::out); inherited // virtual pos_type seekpos(pos_type sp, ios_openmode:: which = ios::in | ios::out); inherited // virtual basic_streambuf* setbuf(charT* s, streamsize n); inherited // virtual int sync(); inherited private: // state_type state; exposition only }; The template class basic_convbuf is derived from basic_streambuf to associate the 'character' sequences and the underlaid character sequences. It performs the conversion between these two types of chracter sequences. For the sake of exposition, the basic_convbuf maintains the conversion state to restart the conversion to read/write the 'character' sequence from/to the underlaid stream. 17.4.8.3.1 basic_convbuf::basic_convbuf() basic_convbuf(); Constructs an object of template class basic_convbuf(), initializing the base class with basic_streambuf(), and initializing; -- state with state(0) as to specify initial state. 17.4.8.3.2 virtual ~basic_convbuf() Destroys an object of class 'basic_convbuf'. 17.4.8.3.6 basic_convbuf::overflow(int_type) virtual int_type overflow (int_type c = baggage::char_bag::eof()); Its behavior is the same as that of the member function, basic_streambuf::overflow(c), except that; -- The behavior of 'consuming a character' is as follows (1) Converting the characters to be consumed into the underlaid character sequence with the function, baggage::conv_bag::convout(). (2) The result underlaid character sequence is appended to the associated output stream. 17.4.8.3.7 basic_convbuf::pbackfail(int_type) virtual int_type pbackfail (int_type c); Puts back the character designated by c to the input sequence, if possible, in one of three ways: ###################################################################### ## Because the parsing on the underlaid character sequence generally ## can only go advance or most of parsing machined cannot go back, ## some of the basic_convbuf implementations cannot 'put back ## characters directly to the associated input sequence'. So the ## behaviors related to putting back the associated input stream are ## removed. ###################################################################### -- If c != baggage::char_bag::eof(), if either the input sequence has a putback position available or the function makes a putback position available, and if (charT)c == (charT)gnext[-1], the function assigns gnext - 1 to gnext. The function signals success by returning (charT)c. -- If c != baggage::char_bag::eof(), if either the input sequence has a putback position available or the function makes a putback position available, and if the function is permitted to assign to the putback position, the function assigns c to *--gnext. The function signals success by returning (char_type)c. -- If c == baggage::char_bag::eof() and if either the input sequence has a putback position available or the function makes a putback posotion available, the function assigns gnext - 1 to gnext. The function signals success by returning (char_type)c. The function does not put back a character direcltly to the input sequence. If the function can succeed in more than one of these ways, it is unspecified which way is chosen. The function can alter the number of putback positions available as a result of any call. The function return baggage::char_bag::eof() to signal the failure. The default behavior is to return baggage::char_bag::eof(). 17.4.8.3.8 basic_convbuf::underflow() // virtual int_type underflow(); inherited Returns the first character of the 'pending sequence', if possible, without moving the stream position past it. If the pending sequence is null then the function fails. The pending sequence of characters is defined as the concatenation of; a) If gnext is non-NULL, then the gend - gnext characters starting at gnext, otherwise the empty sequence. b) Some sequence (possibly empty) of characters read from the input stream. These underlaid character sequence shall be converted by the function 'baggage::conv_bag::convin()' before concatinating to construct the pending sequence. In case that there remains some underlaid characters which cannot be converted to any more 'character's, we treat it empty as the subsequence (b). The result character is the first character of the 'pending sequence', if any. The backup sequence is defined as the concatenation of; a) If gbeg is non-NULL then empty, otherwise the gnext - gbeg characters beginning at gbeg. b) the result character. The function sets up the gnext and gend satisfying; a) In case the pending sequence has more than one character the gend - gnext characters starting at gnext are the characters in the pending sequence after the result character. b) If the pending sequence has exactly one character, then gnext and gend may be NULL or may both be set to the same non-NULL pointer. If gbeg and gnext are non-NULL then the function is not constrained as to their contents, but the "unusual backup condition" is that either; a) If the backup sequence contains at least gnext - gbeg characters then the gnext - gbeg characters starting at gbeg agree with the last gnext - gbeg characters of the backup sequence. b) Or the n characters starting a gnext - n agree with the backup sequence (where n is the length of the backup sequence) The function returns baggage::char_bag::eof() to indicate failure. The default behavior is to return baggage::char_bag::eof(). 17.4.8.3.9 basic_convbuf::uflow() Behaves the same as basic_streambuf::uflow(int). 17.4.8.3.10 basic_convbuf::xsgetn(charT*, streamsize) Behaves the same as basic_streambuf::xsgetn(charT*,streamsize). 17.4.8.3.11 xsputn(const charT*, streamsize) Behaves the same as basic_streambuf::xsputn(const charT*,streamsize). 17.4.8.3.12 seekoff(offT, ios::seekdir, ios::openmode) Behaves the same as basic_streambuf::seekoff(offT,ios::seekdir,ios::openmode), except that the behavior 'Alters the stream position' means that, (a) altering the underlaid character stream position which they get with the return value of the baggage::conv_bag::get_posupos(off_type&); and, (b) restoring the current conversion state by resetting the member, 'state' with the return value of the 'baggage::conv_bag::get_offstate(off_type&). 17.4.8.3.13 basic_convbuf::seekpos(posT , ios::openmode) virtual pos_type seekpos (pos_type pos, ios::openmode which = ios::in | ios::out); At first do 'sync()' to clear up the get buffer, and alters the stream position, as follows; (a) altering the underlaid character stream position by which the function, baggage::conv_bag::get_posupos(pos), returns. and, (b) restoring the member, 'state' with the return value of the 'baggage::conv_bag::get_posstate(pos). The function returns pos_type, newpos, constructed from the resultant upos and state if both (a) and (b) are successfully terminated. If either or both (a) or/and (b) fail, or if the constructed object cannot represent the resultant stream position, the object stores an invalid stream position. Whiciever value is specified in the 'which' parameters, the basic_convbuf handle only one external source/sink stream. If (a) success, the function returns a newly constructed streampos object returned by the 'baggage::conv_bag::get_pos (state, upos)'; where upos is a UPOS_T type object which represent the current position of the underlaid stream. Otherwise, the object stores an invalid stream position. 17.4.8.3.14 setbuf(charT*, streamsize) virtual basic_convbuf* setbuf(charT* s, streamsize n); Makes the array of n (charT type) characters, whose first element is designated by s, available for use as a buffer area for the controlled sequences, if possible. ###################################################################### ## The basic_convbuf does not fix the buffer management strateegy. ## It remains alternatives for the derived class designders. ###################################################################### 17.4.8.3.15 sync() virtual int sync(); Reflects the pending sequence to the external sink sequence and reset the get/put buffer pointers. It means that if there are some unread sequence on the get buffer and the external source sequense is not seekable, the unread sequence is perfectly lost. The detailed behavior is as follows; a) Consumes all of the pending sequence of characters, (as 'pending sequence' and 'consumes the sequence', see the description in the basic_streambuf::overflow()) In case that consuming means appending characters to the associated output stream, the 'character' sequense shall be converted to the corresponding underlaid character sequence by the 'baggage::conv_bag::convout()'. b) Clears all of the following pointers, pbeg, pnext, pend, gbeg, gnext, gend. If (a) fails, the function returns -1, otherwise it return zero. 17.4.9 header ###################################################################### ## Note: Although filebuf object is templated, it accepts only type ## char as charT parameter and it continues to provide narrow-oriented ## fileI/O operations. So this subclause remains unchanged. ###################################################################### The header defines six types that associate stream buffers with files and assist reading and writing files. In this subclause, the type name file is a synonym for the type file defined in . [File] A File provides an external source/sink stream whose underlaid character type is char(byte). [Multibyte characters and Files] Why basic_filebuf is derived from the basic_convbuf? The reason is to support multibyte character I/O. A File is a sequence of multibyte characters. In order to provide the contents as wide character sequence, wfilebuf should convert between wide character sequences and multibyte character sequences. [basic_filebuf] Derived from basic_convbuf. Even the single byte character version because single byte code conversion may be necessary... A basic_filebuf provide... file I/O, char/wchar_t parity. fstate_t ... template parameter for ios_conv_baggage [Customize Mechanizm] Change name (conv_bag -> file_bag), customize ios_conv_baggage. Modify the definition of ios_conv_baggage. 17.4.9.1 template class basic_filebuf template > class basic_filebuf : public basic_convbuf { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_filebuf (); virtual ~basic_filebuf(); int is_open() const; basic_filebuf* open(const char* s, ios::openmode mode); // basic_filebuf* open(const char* s, ios::open_mode mode); basic_filebuf* close(); protected: // virtual int_type overflow(int_type c = baggage::char_bag::eof()); inherited // virtual int_type pbackfail(int_type c = baggage::char_bag::eof()); inherited // virtual int_type underflow(); inherited // virtual int_type uflow(); inherited // virtual streamsize xsgetn(char_type* s, streamsize n); inherited // virtual streamsize xsputn(char_type* s, streamsize n); inherited // virtual pos_type seekoff(off_type off, ios::seekdir way, // ios::openmode which = ios::in | ios::out); inherited // virtual pos_type seekpos(pos_type sp, ios::openmode which = ios::in | ios::out); inherited // virtual basic_streambuf* setbuf(char_type* s, streamsize n); inherited // virtual int sync(); inherited private: // .... exposition only }; The template class, basic_filebuf is derived from basic_convbuf to associate both the input sequence and the output sequence with an object of type FILE through the underlaid narrow-oriented character sequence held in a file. Type FILE is defined in . For the sake of exposition, the maintained data is presented here as: -- FILE *file, points to the FILE associated with the object of class basic_filebuf. The restriction on reading and writing a sequence controlled by an object of class basic_filebuf are the same as for reading and writing its associdated file. In particular: -- If the file is not open for reading or for update, the input sequence cannot be read. -- If the file is not open for writing or for update, the output sequence cannot be written. -- A joint file position is maintained for both the input sequence and the output sequence. [Multibyte character and Files] A File provides byte sequences. So the streambuf (or its derived classes) treats a file as the external source/sink byte sequence. In a large character set environment, multibyte character sequences are held in files. In order to provide the contents of a file as wide character sequences, wide-oriented filebuf, namely wfilebuf should convert wide character sequences. Because of necessity of the conversion between the external source/sink streams and wide character sequences. In order to support file I/O and multibyte/wide character conversion, the following arrangement is applied to the baggage structures; -- Specify 'char' as the underlaid character type, uchar_type defined in the ios_conv_baggage<>. -- Define state_t, the template parameter of the ios_conv_baggage<>, so that it can apply to the conversion function. In case the conversion function provided by the locale::codecnv facet uses, we adopt a specialized template parameter 'stateT' for the locale-oriented conversion function suitable for the multibyte/wide character conversion. Now we assume the name of the conversion state object is 'fstate_t'. -- Define streamoff (or streampos) as the repositional information for the underlaid byte sequence. -- Define streamoff, wstreampos for the wide-oriented streambuf(or filebuf)s so that some composite function in the ios_conv_baggage(), for example; wstreampos get_pos (fstate_t fs, streampos s); wstreamoff get_off (fstate_t fs, streampos s); 17.4.9.1.1 Example of filebuf, wfilebuf class fstate_t { ... }; // Implementation-defined conversion state // object which is for file I/O. class wfstate_t { ... }; template struct file_baggage {}; struct file_baggage { typedef ios_char_baggage char_bag; typedef ios_pos_baggage char_pos; typedef ios_conv_baggage conv_pos; }; struct file_baggage{ typedef ios_char_baggage char_bag; typedef ios_pos_baggage char_pos; typedef ios_conv_baggage conv_pos; }; template struct ios_file_baggage {}; // // Specialized for the single-byte filebuf // struct ios_conv_baggage { typedef char char_type; // char/wchar_t... typedef fstate_t conv_state; // key parameter(mainly depend on uchar_type) typedef streamoff conv_upos; // Physical file offset typedef char uchar_type; // Physical file I/O typedef streampos pos_type; // Enough to large typedef streamoff off_type; // Enough to large typedef locale::codecnv codecnv_in; typedef locale::codecnv codecnv_out; locale::result convin (codecvt_in* ccvt, conv_state& stat, const char *from, const char* from_end, const char*& from_next, char* to, char* to_limit, char*& to_next) { return ccvt->convert (stat, from, from_end, from_next, to, to_limit, to_next); } locale::result convout (codecvt_out* ccvt, conv_state& stat, const char* from, const char* from_end, const char*& from_next, char* to, char* to_limit, char* to_next) { return ccvt->convert (stat, from, from_end, from_next, to, to_limit, to_next); } pos_type get_pos (conv_state&, conv_upos&); off_type get_off (conv_state&, conv_upos&); conv_state get_posstate (pos_type&); conv_state get_offstate (off_type&); conv_upos get_posupos (pos_type&); conv_upos get_offupos (off_type&); }; // // Specialized for the wfilebuf // struct ios_conv_baggage { typedef wchar_t char_type; // char/wchar_t... typedef wfstate_t conv_state; // key parameter(mainly depend on uchar_type) typedef streamoff conv_upos; // Physical file offset typedef char uchar_type; // Physical file I/O typedef wstreampos pos_type; // Enough to large typedef wstreamoff off_type; // Enough to large typedef locale::codecnv codecnv_in; typedef locale::codecnv codecnv_out; locale::result convin (codecvt_in* ccvt, conv_state& stat, const char *from, const char* from_end, const char*& from_next, wchar_t* to, wchar_t* to_limit, wchar_t*& to_next) { return ccvt->convert (stat, from, from_end, from_next, to, to_limit, to_next); } locale::result convout (codecvt_out* ccvt, conv_state& stat, const wchar_t* from, const wchar_t* from_end, const wchar_t*& from_next, char* to, char* to_limit, char* to_next) { return ccvt->convert (stat, from, from_end, from_next, to, to_limit, to_next); } pos_type get_pos (conv_state&, conv_upos&); // wstreampos get_pos (wfstate_t&, streampos); off_type get_off (conv_state&, conv_upos&); // wstreamoff get_off (wfstate_t&, streampos); conv_state get_posstate (pos_type&); // wfstate_t get_posstate (wstreampos&); conv_state get_offstate (off_type&); // wfstate_t get_offstate (wstreamoff&); conv_upos get_posupos (pos_type&); // conv_upos get_offupos (off_type&); }; ###################################################################### ## Need more description about there definitions ###################################################################### 18.4.9.1.2 basic_filebuf::basic_filebuf(). basic_filebuf(); Constructs an object of class basic_filebuf, initializing the base class with basic_streambuf(), and initializing 'file' to a null pointer. 17.4.9.1.3 basic_filebuf::~basic_filebuf () virtual ~basic_filebuf (); Destroys asn object of class basic_filebuf. The function calls close(); 17.4.9.1.4 basic_filebuf::is_open (); bool is_open () const; Returns a nonzero value if 'file' is not a null pointer. 17.4.9.1.5 basic_filebuf::open(const char* s, ios::openmode mode) basic_filebuf* open (const char* s, ios::openmode mode); If 'file' is not a null pointer, returns a null pointer. Otherwise, the function calls basic_streambuf::basic_streambuf(). It then opens a file, if possible, whose name is the null terminated byte string, s, by calling fopen (s, modstr) and assigning the return value to 'file'. The null terminated byte string, modstr is determined from (mode & ~ios::ate) as follows: -- ios::in becomes "r"; -- ios::out | ios::trunc becomes "w"; -- ios::out | ios::app becomes "a"; -- ios::in | ios::out becomes "r+"; -- ios::in | ios::out | ios::trunc becomes "w+"; -- ios::in | ios::out | ios::app becomes "a+"; ....[Same as in the WP:17.4.8.1.4] If the resulting 'file' is not a null pointer and (mode & ~ios::ate) is nonzero, the function calls fseek (file, 0, SEEK_END); If the fuction returns a null pointer, the function cals close () and returns a null pointer. Otherwise, the function returns this. 17.4.9.1.6 basic_filebuf::open (const char*, ios::open_mode); // filebuf* open (const char*s, ios::open_mode mode); optional Returns open (s, (ios::openmode)mode); 17.4.9.1.7 basic_filebuf::close (); basic_filebuf* close (); If 'file' is a null pointer, returns a null pointer. Otherwise, if the call fclose (file) returns zero, the function stores a null character in 'file' and return 'this'. Otherwise, it returns a null pointer. The function signature fclose (FILE*) is declared, in . 17.4.9.1.8 basic_filebuf::overflow (int) // virtual int overflow (int c = baggage::char_bag::eof()); inherited Its behavior is the same as that of the member function, basic_streambuf::overflow(c), except that; -- The behavior of 'consuming a character' is as follows; (1) Converting the characters to be consumed into the underlaid character sequence with the function, baggage::conv_bag::convout(). During the conversion, the function 'convout' maintains the conversion state on the member 'state'. At the end of execution of the conversion, the conversion state is saved on it. (2) The result underlaid character sequence is written to the file specified by 'file'. At the consumption of the pending characters, none of them are discarded. All of the characters are converted to be writted to the file. The function returns baggage::char_bag::eof() to indicate failure. If 'file' is a null pointer, the function always fail. 17.4.9.1.9 basic_filebuf::pbackfail(int) // virtual int_type pbackfail (int c = baggage::char_bag::eof()); Puts back the character designated by c to the input sequence, if possible, in one of three ways: ###################################################################### ## Because the parsing on the underlaid character sequence generally ## can only go advance or most of parsing machined cannot go back, ## some of the basic_convbuf implementations cannot 'put back ## characters directly to the associated input sequence'. So the ## behaviors related to putting back the associated input stream are ## removed. ###################################################################### -- If c != baggage::char_bag::eof(), if the function makes a putback position available, and if (char_type)c == (char_type)gnext[-1], the function assigns gnext - 1 to gnext. The function signals success by returning (char_type)c. -- If c != baggage::char_bag::eof(), if the function makes a putback position available, and if the function is permitted to assign to the putback position, the function assigns c to *--gnext. The function signals success by returning (char_type)c. -- If c == baggage::char_bag::eof() and if the function makes a putback posotion available, the function assigns gnext - 1 to gnext. The function signals success by returning (char_type)c. The function does not put back a character direcltly to the input sequence. If the function can succeed in more than one of these ways, it is unspecified which way is chosen. The function can alter the number of putback positions available as a result of any call. The function return baggage::char_bag::eof() to signal the failure. The default behavior is to return baggage::char_bag::eof(). ###################################################################### ## Shall we impose Library uses onto performing 'sync()'... make ## gbuffer/pbuffer empty every time ## they try to write after read or ## vice versa, as in the current MSE. ###################################################################### 17.4.9.1.10 basic_filebuf::underflow() // virtual int_type underflow (); Shows the same behavior as basic_convbuf::underflow(); except that the underlaid input character sequence is the byte sequence in the file specified by the 'file'. ###################################################################### ## Sorry, Describing the behavior about maintaining the conversion ## state is needed but there is none. ###################################################################### 17.4.9.1.11 basic_filebuf::uflow() // virtual int_type uflow (); Behaves the same as basic_convbuf::uflow(int); 17.4.9.1.12 basic_filebuf::xsgetn (charT*, streamsize) // virtual streamsize xsgetn (charT* s, streamsize n); Behaves the same as basic_convbuf::xsgetn(s, n); 17.4.9.1.13 basic_filebuf::xsputn (const charT*, streamsize) // virtual streamsize basic_filebuf::xsputn (const charT* s, streamsize n); Behaves the same as basic_convbuf::xsputn (s, n); 17.4.9.1.14 basic_filebuf::seekoff (off_type, ios::seekdir, int::openmode) // virtual pos_type seekoff (off_type off, ios::seekdir way, ios::openmode which = ios::in | ios::out); Alters the stream position within the controlled sequence, if possible, as described below. The function returns a newly constructed pos_type object that stores the resultant stream position, if possible. If the positioning operation fails, or if the object cannot represent the resultant stream position, the object stores an invalid stream position. If 'file' is a null pointer, the positioning operation fails. Otherwise, the function determines one of three value for the argument whence, of type int. -- If way == ios::beg, the argument is SEEK_SET, -- If way == ios::cur, the argument is SEEK_CUR, -- If way == ios::end, the argument is SEEK_END. The function then calls fseek (file, off, whence) and, if that function returns nonzero, the positioning operation fails. The function extracts the conversion state from off by means of 'get_offstate()' to reset the 'state' member. 17.4.9.1.15 basic_filebuf::seekpos (pos_type, ios::openmode) [To Be Filled] 17.4.9.1.16 basic_filebuf::setbuf(charT*, streamsize) [To Be Filled] 17.4.9.1.17 basic_filebuf::sync() [To Be Filled] 17.4.9.2 Class filebuf class filebuf : public basic_filebuf {}; 17.4.9.3 Class wfilebuf class wfilebuf : public basic_filebuf {}; 17.4.9.4 Template class basic_ifstream template > class basic_ifstream : public basic_istream { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_ifstream (); basic_ifstream (const char* s, openmode mode = in); virtual ~basic_ifstream (); bool is_open(); void open (const char* s, openmode mode = in); void open (const char* s, open_mode mode = in); optional void close (); private: basic_filebuf fb; }; [Same as in WP:17.4.8.2, Class istream] 17.4.9.5 Class ifstream class ifstream : public basic_ifstream {}; 17.4.9.6 Class wifstream class wifstream : public basic_ifstream {}; 17.4.9.7 Template class basic_ofstream template > class basic_ofstream : public basic_ostream { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_ofstream (); basic_ofstream (const char* s, openmode mode = in); virtual ~basic_ofstream (); bool is_open(); void open (const char* s, openmode mode = in); void open (const char* s, open_mode mode = in); optional void close (); private: basic_filebuf fb; }; [Same as in WP:17.4.8.2, Class ofstream] 17.4.9.8 Class ofstream class ofstream : public basic_ofstream {}; 17.4.9.9 Class wofstream class wofstream : public basic_ofstream {}; 17.4.9.10 Template class basic_stdiobuf template > class basic_stdiobuf : public streambuf { public: typedef charT char_type; typedef baggage::char_bag::int_type int_type; typedef baggage::pos_bag::pos_type pos_type; typedef baggage::pos_bag::off_type off_type; int_type eof() { return baggage::char_bag::eof(); } char_type newline() { return baggage::char_bag::newline(); } public: basic_stdiobuf (FILE*, file_arg = 0); virtual ~stdioflg(); int buffered(); void buffered(int buf_f1); protected: // virtual int_type overflow (int_type c = baggage::char_bag::eof()); // virtual int_type pbackfail (int_type c = baggage::char_bag::eof()); // virtual int_type underflow (); // virtual int_type uflow (); // virtual streamsize xsgetn (charT* s, streamsize n); // virtual streamsize xsputn (const charT* s, streamsize n); // virtual pos_type seekoff (off_type off, ios::seekdir way, ios::openmode which = ios::on | ios::out; // virtual pos_type seekpos (pos_type pos,ios::openmode which); // virtual basic_streambuf* setbuf (charT* s, streamsize); // virtual int sync (); private: // FILE *file; // int is_buffered; [To Be Filled] 17.4.10 Header The header declares four objects that associate objects of class stdiobuf with the standard C streams provided for by the functions declared in . The four objects are constructed, and the associations are established, the first time an object of class ios::Init is constructed. The four objects are not destroyed diring program execution. ### Note: Need to determine whether we tream cin, cout, cerr, ... as ### wide-oriented or not. ### We can allow to change narrow-wide if only no I/O operations occurs. ### So the default is wide-oriented and easily modify narrow-oriented? 17.4.10.1 Object cin istream cin; The object cin controls input from an unbuffered stream buffer associated with the object stdin, declared in . After the object cin is initialized, cin.tie() returns cout. 17.4.10.2 Object cout ostream cout; The object cout controls output to an unbuffered stream buffer associated with the object stdout, declared in . 17.4.10.3 Object cerr [Same as in WP:17.4.9.3] 17.4.10.4 Object clog [Same as in WP:17.4.9.4]