std::fread(3)

💅 NAME 💅

Okay so this is std::fread(3) from the C++ Standard Libary (that spelling is the manual’s, not mine 😭), and it’s literally std::fread — the “read up to count objects from a stream into a buffer” girlie. Bestie, she’s iconic, she’s lowkey everywhere, and she has one job. 💖

✨ Synopsis ✨

Defined in header <cstdio> — write that down, bestie.

std::size_t fread( void* buffer, std::size_t size, std::size_t count,
std::FILE*
stream );

Here’s the tea: std::fread reads up to count objects into the array buffer from the given input stream stream, as if by calling std::fgetc size times for each object. It stores the results, in the order obtained, into the successive positions of buffer, which is reinterpreted as an array of unsigned char. The file position indicator for the stream is advanced by the number of characters read. ✨

If the objects are not TriviallyCopyable, the behavior is undefined. 🚨 Not a vibe, not a slay, do not do it.

If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate. 💀

🌸 Parameters 🌸

• buffer — pointer to the first object in the array to be read.
• size — size of each object in bytes.
• count — the number of the objects to be read.
• stream — input file stream to read from.

🫶 Return value 🫶

Number of objects read successfully, which may be less than count if an error or end-of-file condition occurs. 🥺

If size or count is zero, fread returns zero and performs no other action. Literally zero, zero extra moves. 💅

fread does not distinguish between end-of-file and error, and callers must use std::feof and std::ferror to determine which occurred. So yeah, she reads, but she does not gossip about why the read stopped. You gotta ask std::feof and std::ferror yourself. 😭

🎀 Example 🎀

The page says // Run this code right before the example, so here’s the code exactly as the manual lays it out — wraps and all, bestie 🫶

        #include <cstddef>
        #include <cstdio>
        #include <fstream>
        #include <iomanip>
        #include <iostream>
        #include <vector>

        int main()
        {
            // Prepare file
            std::ofstream("test.txt") << 1 << ' ' << 2 << '\n';
            std::FILE* f = std::fopen("test.txt", "r");

            std::vector<char> buf(4); // char is trivially copyable
            const std::size_t n = std::fread(&buf[0], sizeof buf[0],
       buf.size(), f);

            std::cout << "Read " << n << " object" << (n > 1 ? "s" : "") << ":
       "
                      << std::hex << std::uppercase << std::setfill('0');
            for (char n : buf)
                std::cout << "0x" << std::setw(2) << static_cast<short>(n) << '
       ';
            std::cout << '\n';

            std::vector<std::string> buf2; // string is not trivially copyable
        //  This would result in undefined behavior:
        //  std::fread(&buf2[0], sizeof buf2[0], buf2.size(), f);
        }

⭐ Possible output ⭐

Read 4 objects: 0x31 0x20 0x32 0x0A

🌈 See also 🌈

• scanf — reads formatted input from stdin, a file stream or a buffer
• fscanf (function)
• sscanf
• fgets — gets a character string from a file stream (function)
• fwrite — writes to a file (function)
• C documentation for fread

Source/version/date vibe check: http://cppreference.com, 2024.06.10, page std::fread(3) — mwah 💋✨