basic_filebuf 類別

發行項
01/10/2024

描述數據流緩衝區，控制類型Char_T的傳輸，其字元特性是由 Tr 類別決定，以及從儲存在外部檔案中的元素序列。

語法

template <class Char_T, class Tr = char_traits<Char_T>>
class basic_filebuf : public basic_streambuf<Char_T, Tr>

參數

Char_T
檔案緩衝區的基本項目。

Tr
檔案緩衝區基本元素的特性（通常是 char_traits<Char_T>）。

備註

類別範本描述數據流緩衝區，控制類型Char_T專案的傳輸，其字元特性是由 Tr 類別決定，以及從儲存在外部檔案中的元素序列來回傳輸。

注意

型別的物件basic_filebuf會以 char* 類型的內部緩衝區建立，而不論char_type類型參數所指定的 Char_T。這表示在寫入內部緩衝區之前，Unicode 字串 (包含 wchar_t 字元) 會轉換為 ANSI 字串 (包含 char 字元)。若要將 Unicode 字串儲存在緩衝區中，請建立類型的 wchar_t 新緩衝區，並使用 basic_streambuf::pubsetbuf() 方法加以設定。若要查看示範此行為的範例，請參閱以下範例。

類別 basic_filebuf<Char_T, Tr> 的物件會儲存檔案指標，指定 FILE 控制與開啟檔案相關聯之數據流的物件。它也會將指標儲存至兩個檔案轉換 Facet，以供受保護成員函式 overflow 和 underflow 使用。如需詳細資訊，請參閱basic_filebuf::open。

範例

下列範例示範如何強制類型 basic_filebuf<wchar_t> 的物件，以藉由呼叫 pubsetbuf() 方法，在其內部緩衝區中儲存 Unicode 字元。

// unicode_basic_filebuf.cpp
// compile with: /EHsc

#include <iostream>
#include <string>
#include <fstream>
#include <iomanip>
#include <memory.h>
#include <string.h>

#define IBUFSIZE 16

using namespace std;

void hexdump(const string& filename);

int main()
{
    wchar_t* wszHello = L"Hello World";
    wchar_t wBuffer[128];

    basic_filebuf<wchar_t> wOutFile;

    // Open a file, wcHello.txt, then write to it, then dump the
    // file's contents in hex
    wOutFile.open("wcHello.txt",
        ios_base::out | ios_base::trunc | ios_base::binary);
    if(!wOutFile.is_open())
    {
        cout << "Error Opening wcHello.txt\n";
        return -1;
    }
    wOutFile.sputn(wszHello, (streamsize)wcslen(wszHello));
    wOutFile.close();
    cout << "Hex Dump of wcHello.txt - note that output is ANSI chars:\n";
    hexdump(string("wcHello.txt"));

    // Open a file, wwHello.txt, then set the internal buffer of
    // the basic_filebuf object to be of type wchar_t, then write
    // to the file and dump the file's contents in hex
    wOutFile.open("wwHello.txt",
        ios_base::out | ios_base::trunc | ios_base::binary);
    if(!wOutFile.is_open())
    {
        cout << "Error Opening wwHello.txt\n";
        return -1;
    }
    wOutFile.pubsetbuf(wBuffer, (streamsize)128);
    wOutFile.sputn(wszHello, (streamsize)wcslen(wszHello));
    wOutFile.close();
    cout << "\nHex Dump of wwHello.txt - note that output is wchar_t chars:\n";
    hexdump(string("wwHello.txt"));

    return 0;
}

// dump contents of filename to stdout in hex
void hexdump(const string& filename)
{
    fstream ifile(filename.c_str(),
        ios_base::in | ios_base::binary);
    char *ibuff = new char[IBUFSIZE];
    char *obuff = new char[(IBUFSIZE*2)+1];
    int i;

    if(!ifile.is_open())
    {
        cout << "Cannot Open " << filename.c_str()
             << " for reading\n";
        return;
    }
    if(!ibuff || !obuff)
    {
        cout << "Cannot Allocate buffers\n";
        ifile.close();
        return;
    }

    while(!ifile.eof())
    {
        memset(obuff,0,(IBUFSIZE*2)+1);
        memset(ibuff,0,IBUFSIZE);
        ifile.read(ibuff,IBUFSIZE);

        // corner case where file is exactly a multiple of
        // 16 bytes in length
        if(ibuff[0] == 0 && ifile.eof())
            break;

        for(i = 0; i < IBUFSIZE; i++)
        {
            if(ibuff[i] >= ' ')
                obuff[i] = ibuff[i];
            else
                obuff[i] = '.';

            cout << setfill('0') << setw(2) << hex
                 << (int)ibuff[i] << ' ';
        }
        cout << "  " << obuff << endl;
    }
    ifile.close();
}

Hex Dump of wcHello.txt - note that output is ANSI chars:
48 65 6c 6c 6f 20 57 6f 72 6c 64 00 00 00 00 00   Hello World.....

Hex Dump of wwHello.txt - note that output is wchar_t chars:
48 00 65 00 6c 00 6c 00 6f 00 20 00 57 00 6f 00   H.e.l.l.o. .W.o.
72 00 6c 00 64 00 00 00 00 00 00 00 00 00 00 00   r.l.d...........

建構函式

建構函式	描述
basic_filebuf	建構類型 `basic_filebuf` 的物件。

Typedefs

類型名稱	描述
char_type	將類型名稱與 `Char_T` 樣板參數產生關聯。
int_type	在 `basic_filebuf` 的範圍中製作此類型，相當於在 `Tr` 範圍中的同名類型。
off_type	在 `basic_filebuf` 的範圍中製作此類型，相當於在 `Tr` 範圍中的同名類型。
pos_type	在 `basic_filebuf` 的範圍中製作此類型，相當於在 `Tr` 範圍中的同名類型。
traits_type	將類型名稱與 `Tr` 樣板參數產生關聯。

成員函式

成員函數	描述
close	關閉檔案。
is_open	指出檔案是否為開啟。
open	開啟檔案。
overflow	受保護的虛擬函式，可在將新字元插入已滿的緩衝區時呼叫。
pbackfail	受保護的虛擬成員函式會嘗試將項目放回輸入資料流，然後將其設成目前的項目 (由下一個指標指向)。
seekoff	受保護的虛擬成員函式會嘗試改變受控制資料流的目前位置。
seekpos	受保護的虛擬成員函式會嘗試改變受控制資料流的目前位置。
setbuf	受保護的虛擬成員函式會執行每個衍生資料流緩衝區的特定作業。
Swap	針對提供之 `basic_filebuf` 參數的內容，交換此 `basic_filebuf` 的內容。
sync	受保護的虛擬函式會嘗試與任何相關聯的外部資料流同步處理控制資料流。
uflow	用於從輸入資料流擷取目前項目之受保護的虛擬函式。
underflow	用於從輸入資料流擷取目前項目之受保護的虛擬函式。

需求

Header：<fstream>

命名空間：std

basic_filebuf：：basic_filebuf

建構類型 basic_filebuf 的物件。

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

備註

第一個建構函式會在控制輸入緩衝區和輸出緩衝區的所有指標中儲存一個 null 指標。它也會將 Null 指標儲存在檔案指標中。

第二個建構函式會使用視為右值參考的 right 內容初始化物件。

basic_filebuf：：char_type

將類型名稱與 Char_T 樣板參數產生關聯。

typedef Char_T char_type;

basic_filebuf：：close

關閉檔案。

basic_filebuf<Char_T, Tr> *close();

傳回值

如果檔案指標為 Null 指標，則成員函式會傳回 Null 指標。

備註

close 會呼叫 fclose(fp)。如果該函式傳回非零值，則函式會傳回 Null 指標。否則，它會傳回 this ，表示檔案已成功關閉。

如果是寬數據流，如果在開啟資料流之後發生任何插入，或自上次呼叫之後，函式會呼叫 streamposoverflow。它也會插入任何還原初始轉換狀態所需的序列，方法是視需要使用檔案轉換 Facet fac 呼叫 fac.unshift 。類型的char每個產生的項目byte都會寫入檔案指標fp所指定的相關聯數據流，就像是連續呼叫窗體 fputc(byte, fp)一樣。如果呼叫 fac.unshift 或任何寫入失敗，函式就不會成功。

範例

下列範例假設目前目錄中有兩個檔案： basic_filebuf_close.txt （內容為「測試」）和 iotest.txt （內容為「sss」）。

// basic_filebuf_close.cpp
// compile with: /EHsc
#include <fstream>
#include <iostream>

int main() {
   using namespace std;
   ifstream file;
   basic_ifstream <wchar_t> wfile;
   char c;
   // Open and close with a basic_filebuf
   file.rdbuf()->open( "basic_filebuf_close.txt", ios::in );
   file >> c;
   cout << c << endl;
   file.rdbuf( )->close( );

   // Open/close directly
   file.open( "iotest.txt" );
   file >> c;
   cout << c << endl;
   file.close( );

   // open a file with a wide character name
   wfile.open( L"iotest.txt" );

   // Open and close a nonexistent with a basic_filebuf
   file.rdbuf()->open( "ziotest.txt", ios::in );
   cout << file.fail() << endl;
   file.rdbuf( )->close( );

   // Open/close directly
   file.open( "ziotest.txt" );
   cout << file.fail() << endl;
   file.close( );
}

t
s
0
1

basic_filebuf：：int_type

使此類型在範圍中 basic_filebuf 相當於範圍中 Tr 相同名稱的類型。

typedef typename traits_type::int_type int_type;

basic_filebuf：：is_open

指出檔案是否為開啟。

bool is_open() const;

傳回值

true 如果檔案指標不是 Null，則為。

範例

// basic_filebuf_is_open.cpp
// compile with: /EHsc
#include <fstream>
#include <iostream>

int main( )
{
   using namespace std;
   ifstream file;
   cout << boolalpha << file.rdbuf( )->is_open( ) << endl;

   file.open( "basic_filebuf_is_open.cpp" );
   cout << file.rdbuf( )->is_open( ) << endl;
}

false
true

basic_filebuf：：off_type

使此類型在範圍中 basic_filebuf 相當於範圍中 Tr 相同名稱的類型。

typedef typename traits_type::off_type off_type;

basic_filebuf：：open

開啟檔案。

basic_filebuf<Char_T, Tr> *open(
    const char* filename,
    ios_base::openmode mode,
    int protection = (int)ios_base::_Openprot);

basic_filebuf<Char_T, Tr> *open(
    const char* filename,
    ios_base::openmode mode);

basic_filebuf<Char_T, Tr> *open(
    const wchar_t* filename,
    ios_base::openmode mode,
    int protection = (int)ios_base::_Openprot);

basic_filebuf<Char_T, Tr> *open(
    const wchar_t* filename,
    ios_base::openmode mode);

參數

filename
要開啟之檔案的名稱。

mode
中的 ios_base::openmode其中一個列舉。

保護
默認檔案開啟保護，相當於 _fsopen 中的shflag參數，_wfsopen。

傳回值

如果緩衝區已經開啟，或者如果檔案指標是 Null 指標，則函式會傳回 Null 指標。否則會傳回 this。

備註

此函式會使用 FILE * 來備份， basic_filebuf 就像您已呼叫 fopen/wfopen(filename, strmode)一樣。 strmode由決定自 mode & ~(ate|binary)：

ios_base::in"r" 會變成（開啟現有的檔案以供讀取）。
ios_base：：out 或 ios_base::out | ios_base::trunc 變成 "w" （截斷現有的檔案或建立以進行寫入）。
ios_base::out | app"a" 會變成（開啟現有檔案以附加所有寫入）。
ios_base::in | ios_base::out"r+" 會變成（開啟現有檔案以供讀取和寫入）。
ios_base::in | ios_base::out | ios_base::trunc"w+" 會變成（截斷現有的檔案，或建立以供讀取和寫入）。
ios_base::in | ios_base::out | ios_base::app"a+" 會變成（開啟現有檔案以供讀取，並附加所有寫入）。

如果 mode & ios_base::binary 為非零，函式會 b 附加至 strmode 以開啟二進位數據流，而不是文字數據流。如果 mode & ios_base::ate 為非零，且檔案已成功開啟，則數據流中的目前位置會位於檔案結尾。如果失敗，則會關閉檔案。

如果上述作業順利完成，則會判斷檔案轉換 Facet：use_facet<codecvt<Char_T, char, traits_type::)> >(getlocstate_type，以供下溢和溢位使用。

如果無法成功開啟檔案， nullptr 則會傳回。

範例

如需使用 open的範例，請參閱 basic_filebuf::close 。

basic_filebuf：：operator=

指派此資料流緩衝區物件的內容。這是一個移動指派，涉及不會留下複本的右值。

basic_filebuf& operator=(basic_filebuf&& right);

參數

right
basic_filebuf 物件的右值參考。

傳回值

傳回 *this。

備註

成員運算子會使用 right 的內容 (被視為 rvalue 參考) 來取代物件的內容。如需詳細資訊，請參閱右值參考宣告子：&&。

basic_filebuf：：overflow

將新字元插入已滿的緩衝區時呼叫。

virtual int_type overflow(int_type _Meta = traits_type::eof);

參數

_元
要插入緩衝區或 traits_type::eof的字元。

傳回值

如果函式無法成功，則會傳 traits_type::eof回。否則會傳回 traits_type::not_eof(_Meta)。

備註

如果 _Meta != traits_type::eof為，則受保護的虛擬成員函式會嘗試將專案 ch = traits_type::to_char_type(_Meta) 插入輸出緩衝區。它可以透過下列各種方式來執行：

如果有寫入位置可供使用，它可以將項目儲存至寫入位置，並遞增輸出緩衝區的下一個指標。
為輸出緩衝區配置新的或額外的儲存空間，即可提供寫入位置。
它可以使用檔案轉換 Facet fac 視fac.out需要呼叫，來轉換輸出緩衝區中的任何暫止輸出，後面接著 ch。 char 類型的每個產生的項目ch都會寫入檔案指標fp所指定的相關聯數據流，就像由窗體fputc(ch, fp)的後續呼叫一樣。如果有任何轉換或寫入失敗，函式就不會成功。

basic_filebuf：:p backfail

嘗試將元素放回輸入資料流，然後將其設成目前元素 (透過下一個指標所指向)。

virtual int_type pbackfail(int_type _Meta = traits_type::eof);

參數

_元
要插入緩衝區的字元，或 traits_type::eof。

傳回值

如果函式無法成功，則會傳 traits_type::eof回。否則會傳回 traits_type::not_eof(_Meta)。

備註

受保護虛擬成員函式會將元素放回輸入緩衝區，然後將其設成目前元素 (透過下一個指標所指向)。如果 _Meta == traits_type::eof為，則要回推的項目實際上是目前專案之前已在數據流中的元素。否則，該專案會取代為 ch = traits_type::to_char_type(_Meta)。此函式可以透過下列各種方式來放回元素：

putback如果位置可用，且儲存在那裡的項目會比較等於 ch，它可以遞減輸入緩衝區的下一個指標。
如果函式可以讓位置可供使用，它可以執行此動作、將下一個 putback 指標設定為指向該位置，並儲存 ch 在該位置。
如果函式可以將專案推回輸入數據流，它可以這麼做，例如呼叫 ungetc 類型的 char專案。

basic_filebuf：:p os_type

使此類型在範圍中 basic_filebuf 相當於範圍中 Tr 相同名稱的類型。

typedef typename traits_type::pos_type pos_type;

basic_filebuf：：seekoff

嘗試改變受控制資料流的目前位置。

virtual pos_type seekoff(
    off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

參數

_Off
要尋找相對於 _Way的位置。

_道路
位移作業的起點。如需可能的值，請參閱 seekdir。

_哪
指定指標位置的模式。預設為允許您修改讀取和寫入位置。

傳回值

傳回新位置或無效的資料流位置。

備註

受保護的虛擬成員函式會嘗試改變受控制數據流的目前位置。針對類別 basic_filebuf<Char_T, Tr>的對象，數據流位置可以由類型的 fpos_t物件來表示，該物件會儲存位移和剖析寬數據流所需的任何狀態資訊。位移零是指數據流的第一個專案。 (pos_type 類型的物件會儲存至少一個 fpos_t 物件)。

針對開啟進行讀取和寫入的檔案，輸入和輸出資料流會一前一後地放置在一起。若要在插入和擷取之間切換，您必須呼叫 pubseekoff 或 pubseekpos。 pubseekoff 呼叫 (因而 seekoff 呼叫) 具有文字資料流、二進位資料流和寬資料流的各種限制。

如果檔案指標是 Null 指標 fp ，則函式會失敗。否則，它會藉由呼叫 fseek(fp, _Off, _Way)來嘗試改變數據流位置。如果該函式成功，而且可以藉由呼叫 fgetpos(fp, &fposn)來判斷結果位置fposn，則函式會成功。如果函式成功，它會傳回類型 pos_type 包含 fposn的值。否則會傳回無效的資料流位置。

basic_filebuf：：seekpos

嘗試改變受控制資料流的目前位置。

virtual pos_type seekpos(
    pos_type _Sp,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

參數

_Sp
要搜尋的位置。

_哪
指定指標位置的模式。預設為允許您修改讀取和寫入位置。

傳回值

如果檔案指標是 Null 指標 fp ，則函式會失敗。否則，它會藉由呼叫 fsetpos(fp, &fposn)來嘗試改變數據流位置，其中 fposn 是 fpos_t 儲存在中的 pos物件。如果該函式成功，則函式會傳回 pos。否則會傳回無效的資料流位置。若要判斷資料流位置是否無效，請比較傳回值與 pos_type(off_type(-1))。

備註

針對開啟進行讀取和寫入的檔案，輸入和輸出資料流會一前一後地放置在一起。若要在插入和擷取之間切換，您必須呼叫 pubseekoff 或 pubseekpos。對（和對seekoff）的pubseekoff呼叫對於文字數據流、二進位數據流和寬數據流有不同的限制。

basic_filebuf：：setbuf

執行每個衍生資料流緩衝區的特定作業。

virtual basic_streambuf<Char_T, Tr> *setbuf(
    char_type* _Buffer,
    streamsize count);

參數

_緩衝區
緩衝區的指標。

計數
緩衝區的大小。

傳回值

如果檔案指標 fp 為 Null 指標，則受保護成員函式會傳回零。

備註

setbuf呼叫 setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) 以提供從 _Buffer 開始作為數據流緩衝區的項目count陣列。如果該函式傳回非零值，則函式會傳回 Null 指標。否則，它會傳回 this 表示成功。

basic_filebuf：：swap

將這個 basic_filebuf 的內容和提供的 basic_filebuf 內容交換。

void swap(basic_filebuf& right);

參數

right
另一個 basic_filebuf的左值參考。

basic_filebuf：：sync

嘗試與任何相關聯外部資料流同步處理受控制資料流。

virtual int sync();

傳回值

如果檔案指標是 Null 指標 fp ，則傳回零。否則，只有在呼叫溢位並 fflush(fp) 成功排清數據流的任何暫止輸出時，才會傳回零。

basic_filebuf：：traits_type

將類型名稱與 Tr 樣板參數產生關聯。

typedef Tr traits_type;

basic_filebuf：：下溢

從輸入資料流擷取目前元素。

virtual int_type underflow();

傳回值

如果函式無法成功，則會傳 traits_type::eof回。否則，它會傳 ch回，如一節所述轉換。

備註

受保護的虛擬成員函式會嘗試從輸入數據流擷取目前的專案 ch ，並將專案傳回為 traits_type::to_int_type(ch) 。它可以透過下列各種方式來執行：

如果有可用的讀取位置，它會接受 ch 儲存在讀取位置中的專案，並前進輸入緩衝區的下一個指標。
它可以讀取類型char為的一或多個專案，就像連續呼叫窗體 fgetc(fp)一樣，並使用檔案轉換 Facet fac 視需要呼叫fac.in，將它們轉換成類型的Char_T專案ch。如果有任何讀取或轉換失敗，函式就不會成功。

另請參閱

<fstream>
C++ 標準程式庫中的執行緒安全
 iostream 程式設計
 iostreams 慣例

共用方式為

basic_filebuf 類別

語法

參數

備註

範例

建構函式

Typedefs

成員函式

需求

basic_filebuf：：basic_filebuf

備註

basic_filebuf：：char_type

basic_filebuf：：close

傳回值

備註

範例

basic_filebuf：：int_type

basic_filebuf：：is_open

傳回值

範例

basic_filebuf：：off_type

basic_filebuf：：open

參數

傳回值

備註

範例

basic_filebuf：：operator=

參數

傳回值

備註

basic_filebuf：：overflow

參數

傳回值

備註

basic_filebuf：:p backfail

參數

傳回值

備註

basic_filebuf：:p os_type

basic_filebuf：：seekoff

參數

傳回值

備註

basic_filebuf：：seekpos

參數

傳回值

備註

basic_filebuf：：setbuf

參數

傳回值

備註

basic_filebuf：：swap

參數

basic_filebuf：：sync

傳回值

basic_filebuf：：traits_type

basic_filebuf：：下溢

傳回值

備註

另請參閱

意見反應

其他資源