std::basic_...sic_ofstream(3)

✨ NAME ✨

std::basic_ofstream::basic_ofstream — std::basic_ofstream::basic_ofstream, bestie. That's the name and the one-liner, and this is the std::basic_...sic_ofstream(3) page from the C++ Standard Libary manual. We're talking about the constructor today, and it's honestly kind of iconic. 💖

🌸 Synopsis 🌸

Here are the overloads, exactly as they appear — no cap:

basic_ofstream();
explicit basic_ofstream( const char* filename, std::ios_base::openmode mode = std::ios_base::out );
explicit basic_ofstream( const std::filesystem::path::value_type* filename, std::ios_base::openmode mode = std::ios_base::out );
explicit basic_ofstream( const std::string& filename, std::ios_base::openmode mode = std::ios_base::out );
template< class FsPath >
explicit basic_ofstream( const FsPath& filename, std::ios_base::openmode mode = std::ios_base::out );
basic_ofstream( basic_ofstream&& other );
basic_ofstream( const basic_ofstream& rhs ) = delete;

Quick vibe check on the numbers: (1) is the default one, (2) is the const char* one, (3) is the std::filesystem::path::value_type* one and it's (since C++17), (4) is the std::string& one and it's (since C++11), (5) is the FsPath template one and it's (since C++17), (6) is the move constructor and it's (since C++11), and (7) is the deleted copy constructor and it's (since C++11). 💅

Constructs new file stream. Here's the tea, overload by overload:

1. Overload (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. Overload (2) — first, performs the same steps as the default constructor, then associates the stream with a file by calling rdbuf()->open(filename, mode | std::ios_base::out) (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). 🛠️
3. Overload (3) — same as (2), and it's only provided if std::filesystem::path::value_type is not char — (since C++17). 💅
4. Overload (4) — same as basic_ofstream(filename.c_str(), mode) — (since C++11). 📝
5. Overload (5) — same as basic_ofstream(filename.c_str(), mode), and it participates in overload resolution only if FsPath is std::filesystem::path — (since C++17).

Also, ngl, despite the default mode being out, the effects are identical to the effects of out | trunc as described in std::filebuf::open. 👀

6. 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. 🚚
7. Overload (7) — the copy-constructor is deleted: this class is not copyable. periodt. 🚫

🎀 Parameters 🎀

• filename — the name of the file to be opened. 🗂️
• mode — specifies stream open mode. The 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::ofstream f0;
    std::ofstream f1("test.bin", std::ios::binary);
    std::string name = "example.txt";
    std::ofstream f2(name);
    std::ofstream f3(std::move(f1));
}

This example is giving "I can construct file streams in my sleep" energy, and it's literally the whole code block. 💅

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR: 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_ostream<CharT,Traits>)

okay bestie, that's the whole page 💖 source: http://cppreference.com — version/date: 2024.06.10 — page: std::basic_...sic_ofstream(3). bye! 🫶✨