std::basic_...sic_ifstream(3)

🌸 NAME 🌸

okay so bestie 💖 you're on the manual page std::basic_...sic_ifstream(3) for the C++ Standard Library — and the thing it's documenting is std::basic_ifstream::basic_ifstream. Yes, it's the constructor page. The constructor. Very main character energy. ✨

std::basic_ifstream::basic_ifstream - std::basic_ifstream::basic_ifstream (the file-stream constructor, slay).

✨ SYNOPSIS ✨

basic_ifstream(); // (1)

explicit basic_ifstream( const char* filename,
                         std::ios_base::openmode mode
                         = std::ios_base::in ); // (2)

explicit basic_ifstream( const std::filesystem::path::value_type*
                         filename,
                         std::ios_base::openmode mode
                         = std::ios_base::in ); // (3) (since C++17)

explicit basic_ifstream( const std::string& filename,
                         std::ios_base::openmode mode
                         = std::ios_base::in ); // (4) (since C++11)

template< class FsPath >
explicit basic_ifstream( const FsPath& filename,
                         std::ios_base::openmode mode
                         = std::ios_base::in ); // (5) (since C++17)

basic_ifstream( basic_ifstream&& other ); // (6) (since C++11)

basic_ifstream( const basic_ifstream& rhs ) = delete; // (7) (since C++11)

Constructs new file stream. 🫶

• 1) Default constructor: constructs a stream that is not associated with a file: default-constructs the std::basic_filebuf and constructs the base with the pointer to this default-constructed std::basic_filebuf member.
• 2,3) 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::in) (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)
• 4,5) Same as basic_ifstream(filename.c_str(), mode). (5) participates in overload resolution only if FsPath is std::filesystem::path. (since C++17)
• 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) The copy-constructor is deleted: this class is not copyable. 💀

💅 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, bestie 👇

// Run this code

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

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

🦋 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_istream<CharT,Traits>)

that's the whole page, bestie 💖 source/version/date: http://cppreference.com, 2024.06.10, manual page std::basic_...sic_ifstream(3). periodt. 💅✨