std::basic_...asic_fstream(3)

💖 NAME 💖

okay so you're on the std::basic_...asic_fstream(3) page in the C++ Standard Libary manual (yes, spelling exactly as the header gives it 💅), and the main character is:

std::basic_fstream::basic_fstream — std::basic_fstream::basic_fstream

---

✨ Synopsis ✨

bestie, this is the constructor overload set, and there are seven of them. stay with me 🫶

basic_fstream();

(1)

explicit basic_fstream( const char* filename,
                        std::ios_base::openmode mode
                        = std::ios_base::in | std::ios_base::out );

(2)

explicit basic_fstream( const std::filesystem::path::value_type* filename,
                        std::ios_base::openmode mode
                        = std::ios_base::in | std::ios_base::out );

(3) (since C++17)

explicit basic_fstream( const std::string& filename,
                        std::ios_base::openmode mode
                        = std::ios_base::in | std::ios_base::out );

(4) (since C++11)

template< class FsPath >
explicit basic_fstream( const FsPath& filename,
                        std::ios_base::openmode mode
                        = std::ios_base::in | std::ios_base::out );

(5) (since C++17)

basic_fstream( basic_fstream&& other );

(6) (since C++11)

basic_fstream( const basic_fstream& rhs ) = delete;

(7) (since C++11)

Constructs new file stream. That's the whole assignment, but the details are giving very much “read the fine print” energy. 🌸

1. Default constructor — constructs a stream that is not associated with a file: it default-constructs the std::basic_filebuf and constructs the base with the pointer to this default-constructed std::basic_filebuf member.
2. Overloads (2), (3) — first, performs the same steps as the default constructor, then associates the stream with a file by calling rdbuf()->open(filename, mode) (see std::basic_filebuf::open for the details on the effects of that call). If the open() call returns a null pointer, sets setstate(failbit). Overload (3) is only provided if std::filesystem::path::value_type is not char. (since C++17)
3. Overloads (4), (5) — same as basic_fstream(filename.c_str(), mode). Overload (5) participates in overload resolution only if FsPath is std::filesystem::path. (since C++17)
4. Overload (6) — move constructor. First, move-constructs the base class from other (which does not affect the rdbuf() pointer), then move-constructs the std::basic_filebuf member, then calls this->set_rdbuf() to install the new basic_filebuf as the rdbuf() pointer in the base class.
5. Overload (7) — the copy-constructor is deleted: this class is not copyable. no duplicating, bestie 🚫

---

🎀 Parameters 🎀

• filename — the name of the file to be opened.
• mode — specifies stream open mode. Following constants and bit-wise OR between them may be used:
  • app — seek to the end of stream before each write
  • binary — open in binary mode
  • in — open for reading
  • out — open for writing
  • trunc — discard the contents of the stream when opening
  • ate — seek to the end of stream immediately after open
  • noreplace (C++23) — open in exclusive mode
• other — another file stream to use as source.

---

🌸 Example 🌸

// Run this code

#include <fstream>
#include <string>
#include <utility>

int main()
{
    std::fstream f0;
    std::fstream f1("test.bin", std::ios::binary);
    std::string name = "example.txt";
    std::fstream f2(name);
    std::fstream f3(std::move(f1));
}

---

🦋 Defect reports 🦋

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. history really said “let me fix that for you” 💀

• LWG 460 — applied to C++98. Behavior as published: the default argument of mode in overload (2) was missing (it is present in the synopsis). Correct behavior: added.
• LWG 3430 — applied to C++17. Behavior as published: std::filesystem::path overload led to unwanted conversions. Correct behavior: avoided by making it a template.

---

🌈 See also 🌈

• open — opens a file and associates it with the stream (public member function).
• open — opens a file and configures it as the associated character sequence (public member function of std::basic_filebuf<CharT,Traits>).
• set_rdbuf — replaces the rdbuf without clearing its error state (protected member function).
• constructor — constructs the object (public member function of std::basic_iostream<CharT,Traits>).

---

source/version + date sign-off, bestie: http://cppreference.com · 2024.06.10 · std::basic_...asic_fstream(3) — that's the footer, and we're done. periodt. 💜