[ новости /+++ | форум | теги | ]

                       Standard C++ Library
             Copyright 1998, Rogue Wave Software, Inc.


NAME
     basic_filebuf

      - Class that associates the input or output sequence with a
     file.



SYNOPSIS
     #include <fstream>
     template<class charT, class traits = char_traits<charT> >
     class basic_filebuf
     : public basic_streambuf<charT, traits>



DESCRIPTION
     The   template   class   basic_filebuf   is   derived   from
     basic_streambuf.  It associates the input or output sequence
     with     a     file.      Each      object      of      type
     basic_filebuf<charT,_traits>    controls    two    character
     sequences:



     o    A character input sequence

     o    A character output sequence


     The restrictions on reading  and  writing  a  sequence  con-
     trolled  by  an  object of class basic_filebuf<charT,traits>
     are the same as for reading and writing with the Standard  C
     library files.

     If the file is not open for reading, the input sequence can-
     not be read. If the file is not open for writing, the output
     sequence cannot be written. A joint file position  is  main-
     tained for both the input and output sequences.

     A file has byte sequences, so the basic_filebuf class treats
     a  file  as  the external source (or sink) byte sequence. In
     order to provide the contents of a file  as  wide  character
     sequences,  a wide-oriented file buffer called wfilebuf con-
     verts  wide  character  sequences  to  multibytes  character
     sequences  (and  vice versa) according to the current locale
     being used in the stream buffer.



INTERFACE
     template<class charT, class traits = char_traits<charT> >
     class basic_filebuf
     : public basic_streambuf<charT, traits> {

     public:

      typedef traits                       traits_type;
      typedef charT                        char_type;
      typedef typename traits::int_type    int_type;
      typedef typename traits::pos_type    pos_type;
      typedef typename traits::off_type    off_type;

      basic_filebuf();
      basic_filebuf(int fd);

      virtual ~basic_filebuf();

      bool is_open() const;
      basic_filebuf<charT, traits>* open(const char *s,
                                        ios_base::openmode,
                                        long protection = 0666);

      basic_filebuf<charT, traits>* open(int fd);
      basic_filebuf<charT, traits>* close();

     protected:

      virtual int      showmanyc();
      virtual int_type underflow();
      virtual int_type overflow(int_type c = traits::eof());
      virtual int_type pbackfail(int_type c = traits::eof());

      virtual basic_streambuf<charT,traits>*
        setbuf(char_type *s,streamsize n);

      virtual pos_type seekoff(off_type off,
                               ios_base::seekdir way,
                               ios_base::openmode which =
                               ios_base::in | ios_base::out);

      virtual pos_type seekpos(pos_type sp,
                               ios_base::openmode which =
                               ios_base::in | ios_base::out);
      virtual int sync();
      virtual streamsize xsputn(const char_type* s,
                                streamsize n);

     };



TYPES
     char_type


        The type char_type is a synonym for the template  parame-
        ter charT.



     filebuf


        The  type  filebuf   is   an   instantiation   of   class
        basic_filebuf on type char:

        typedef basic_filebuf<char> filebuf;



     int_type


        The type int_type is a synonym of type traits::in_type.



     off_type


        The type off_type is a synonym of type traits::off_type.



     pos_type


        The type pos_type is a synonym of type traits::pos_type.



     traits_type


        The type traits_type is a synonym for the template param-
        eter traits.


     wfilebuf


        The  type  wfilebuf  is   an   instantiation   of   class
        basic_filebuf on type wchar_t:

        typedef basic_filebuf<wchar_t> wfilebuf;



CONSTRUCTORS
     basic_filebuf();


        Constructs        an        object        of        class
        basic_filebuf<charT,traits>,  initializing the base class
        with basic_streambuf<charT,traits>().



     basic_filebuf(int fd);


        Constructs        an        object        of        class
        basic_filebuf<charT,traits>,  initializing the base class
        with  basic_streambuf<charT,traits>().  It   then   calls
        open(fd)  with  file  descriptor fd. This function is not
        described in the C++ standard,  and  is  included  as  an
        extension  to  manipulate  pipes,  sockets, or other UNIX
        devices that can be accessed through file descriptor.



DESTRUCTORS
     virtual ~basic_filebuf();


        Calls close() and destroys the object.



MEMBER FUNCTIONS
     basic_filebuf<charT,traits>*
     close();


        If is_open() == false, returns a null pointer. Otherwise,
        closes the file, and returns *this.



     bool
     is_open() const;


        Returns true if the associated file is open.



     basic_filebuf<charT,traits>*
     open(const char* s, ios_base::openmode mode,
       long protection = 0666);


        If is_open() == true, returns a null  pointer.  Otherwise
        opens  the  file,  whose  name  is  stored  in  the null-
        terminated byte-string s. The file open modes  are  given
        by  their  C-equivalent  description  (see the C function
        fopen):

        in                      "w"
        in|binary               "rb"
        out                     "w"
        out|app                 "a"
        out|binary              "wb"
        out|binary|app          "ab"
        out|in                  "r+"
        out|in|app              "a+"
        out|in|binary           "r+b"
        out|in|binary|app       "a+b"
        trunc|out               "w"
        trunc|out|binary        "wb"
        trunc|out|in            "w+"
        trunc|out|in|binary     "w+b"

        The third argument, protection, is used as the file  per-
        mission.  It does not appear in the Standard C++ descrip-
        tion of the function open and is included  as  an  exten-
        sion.  It  determines the file read/write/execute permis-
        sions under UNIX. It is more  limited  under  DOS,  since
        files are always readable and do not have special execute
        permission. If the open function fails, it returns a null
        pointer.



     basic_filebuf<charT,traits>*
     open(int fd);
        Attaches the previously opened file, which is  identified
        by  its  file descriptor fd, to the basic_filebuf object.
        This function is not described in the C++  standard,  and
        is included as an extension in order to manipulate pipes,
        sockets, or other  UNIX  devices  that  can  be  accessed
        through file descriptors.



     int_type
     overflow(int_type c = traits::eof() );


        If the output sequence has a put position available,  and
        c  is  not traits::eof(), then writes c into it. If there
        is no position available, the function outputs  the  con-
        tents  of  the  buffer  to  the  associated file and then
        writes c at the new current put position. If  the  opera-
        tion fails, the function returns traits::eof(). Otherwise
        it returns traits::not_eof(c). In  wide  characters  file
        buffer, overflow converts the internal wide characters to
        their external multibytes  representation  by  using  the
        locale::codecvt facet located in the locale object imbued
        in the stream buffer.



     int_type
     pbackfail(int_type c = traits::eof() );


        Puts back the character designated by c  into  the  input
        sequence. If traits::eq_int_type(c,traits::eof()) returns
        true, moves the input sequence one position backward.  If
        the  operation fails, the function returns traits::eof().
        Otherwise it returns traits::not_eof(c).



     pos_type
     seekoff(off_type off, ios_base::seekdir way,
            ios_base::openmode which = ios_base::in |
            ios_base::out);


        If the open mode is in | out, alters the stream  position
        of  both  the  input and the output sequence. If the open
        mode is in, alters the stream position of only the  input
        sequence, and if it is out, alters the stream position of
        only the output sequence. The new position is  calculated
        by  combining  the  two parameters off (displacement) and
        way (reference point). If the  current  position  of  the
        sequence  is  invalid before repositioning, the operation
        fails and the  return  value  is  pos_type(off_type(-1)).
        Otherwise  the function returns the current new position.
        File buffers using locale::codecvt facet  and  performing
        state  dependent  conversion  support only seeking to the
        beginning of the file, to the current position, or  to  a
        position previously obtained by a call to one of the ios-
        treams seeking functions.



     pos_type
     seekpos(pos_type    sp,ios_base::openmode         which    =
     ios_base::in | ios_base::out);


        If the open mode is in | out, alters the stream  position
        of  both  the  input and the output sequence. If the open
        mode is in, alters the stream position of only the  input
        sequence, and if it is out, alters the stream position of
        only the output sequence. If the current position of  the
        sequence  is  invalid before repositioning, the operation
        fails and the  return  value  is  pos_type(off_type(-1)).
        Otherwise  the function returns the current new position.
        File buffers using locale::codecvt facet performing state
        dependent  conversion, only support seeking to the begin-
        ning of the file, to the current position, or to a  posi-
        tion  previously  obtained  by  a call to one of the ios-
        treams seeking functions.



     basic_filebuf<charT,traits>*
     setbuf(char_type*s, streamsize n);


        If s is not a null pointer, outputs the  content  of  the
        current  buffer  to the associated file, then deletes the
        current buffer and replaces it by  s.  Otherwise  resizes
        the  current  buffer  to size n after outputting its con-
        tents to the associated file, if necessary.



     int
     sync();


        Synchronizes the contents of the external file, with  its
        image  maintained  in  memory  by the file buffer. If the
        function fails, it returns -1; otherwise it returns 0.

     int_type
     underflow();


        If the input sequence  has  a  read  position  available,
        returns the contents of this position. Otherwise fills up
        the buffer by  reading  characters  from  the  associated
        file, and if it succeeds, returns the contents of the new
        current position. The function returns  traits::eof()  to
        indicate  failure. In wide characters file buffer, under-
        flow converts the external multibytes characters to their
        wide    character    representation    by    using    the
        locale::codecvt facet located in the locale object imbued
        in the stream buffer.



     streamsize
     xsputn(const char_type* s, streamsize n);


        Writes up to n characters to  the  output  sequence.  The
        characters  written are obtained from successive elements
        of the array whose first element is designated by s.  The
        function returns the number of characters written.



EXAMPLE
     //
     // stdlib/examples/manual/filebuf.cpp
     //
     #include<iostream>
     #include<fstream>

     void main ( )
     {
      using namespace std;

       // create a read/write file-stream object on tiny char
       // and attach it to the file "filebuf.out"
      ofstream out("filebuf.out",ios_base::in |
                    ios_base::out);

       // tie the istream object to the ofstream object
      istream in(out.rdbuf());

       // output to out
      out << "Il errait comme un ame en peine";

       // seek to the beginning of the file
      in.seekg(0);

       // output in to the standard output
      cout << in.rdbuf() << endl;

       // close the file "filebuf.out"
      out.close();

       // open the existing file "filebuf.out"
       // and truncate it
      out.open("filebuf.out",ios_base::in | ios_base::out |
               ios_base::trunc);

       // set the buffer size
      out.rdbuf()->pubsetbuf(0,4096);

       // open the source code file
      ifstream ins("filebuf.cpp");

       //output it to filebuf.out
      out << ins.rdbuf();

       // seek to the beginning of the file
      out.seekp(0);

       // output the all file to the standard output
      cout << out.rdbuf();
     }



SEE ALSO
     char_traits(3C++),     ios_base(3C++),      basic_ios(3C++),
     basic_streambuf(3C++),                 basic_ifstream(3C++),
     basic_ofstream(3C++), basic_fstream(3C++)

     Working Paper for Draft Proposed International Standard  for
     Information   Systems--Programming   Language  C++,  Section
     27.8.1.1



STANDARDS CONFORMANCE
     ANSI X3J16/ISO WG21 Joint C++ Committee

Партнёры:

Хостинг: