docs: Enhance documentation for fast I/O utilities with detailed method descriptions

Author: weilycoder

weilycoder/fast-io.hpp

@@ -1,6 +1,11 @@
 #ifndef WEILYCODER_FAST_IO_HPP
 #define WEILYCODER_FAST_IO_HPP
 
+/**
+ * @file fast-io.hpp
+ * @brief Fast Input/Output Utilities
+ */
+
 #include <cstddef>
 #include <cstdint>
 #include <cstdio>
@@ -14,13 +19,20 @@
 
 namespace weilycoder {
 #if defined(__linux__) || defined(__unix__) || defined(__APPLE__)
+/**
+ * @brief Fast Reader using Memory-Mapped I/O
+ */
 struct FastReadMMap {
   size_t file_size;
   char *data, *pos;
 
   FastReadMMap(const FastReadMMap &) = delete;
   FastReadMMap &operator=(const FastReadMMap &) = delete;
 
+  /**
+   * @brief Constructs a FastReadMMap object and memory-maps stdin.
+   *        If mapping fails, sets file_size to max size_t.
+   */
   FastReadMMap() {
     struct stat st;
 
@@ -35,19 +47,34 @@ struct FastReadMMap {
     pos = data;
   }
 
+  /**
+   * @brief Destructor that unmaps the memory-mapped file.
+   */
   ~FastReadMMap() {
     if (file_size != std::numeric_limits<size_t>::max())
       munmap(data, file_size);
   }
 
+  /**
+   * @brief Gets the next character from the memory-mapped input.
+   * @return The next character, or EOF if the end of the file is reached.
+   */
   inline char getchar() {
     return static_cast<size_t>(pos - data) < file_size ? *pos++ : EOF;
   }
 
+  /**
+   * @brief Alias for getchar().
+   * @return The next character from input.
+   */
   inline char operator()() { return getchar(); }
 };
 #endif
 
+/**
+ * @brief Fast Reader using fread
+ * @tparam buffer_size Size of the internal buffer (default: 1 MB)
+ */
 template <size_t buffer_size = 1 << 20> struct FastReadFRead {
   char buf[buffer_size], *pos = buf, *end = buf;
 
@@ -56,20 +83,39 @@ template <size_t buffer_size = 1 << 20> struct FastReadFRead {
   FastReadFRead(const FastReadFRead &) = delete;
   FastReadFRead &operator=(const FastReadFRead &) = delete;
 
+  /**
+   * @brief Gets the next character from input using buffered fread.
+   * @return The next character, or EOF if the end of the file is reached.
+   */
   inline char getchar() {
     return pos == end && (end = (pos = buf) + fread(buf, 1, buffer_size, stdin),
                           pos == end)
                ? EOF
                : *pos++;
   }
 
+  /**
+   * @brief Clears the internal buffer.
+   */
   inline void clear() { pos = end = buf; }
 
+  /**
+   * @brief Reopens the input stream by clearing the buffer
+   *        and seeking to the beginning.
+   */
   inline void reopen() { clear(), fseek(stdin, 0, SEEK_SET); }
 
+  /**
+   * @brief Alias for getchar().
+   * @return The next character from input.
+   */
   inline char operator()() { return getchar(); }
 };
 
+/**
+ * @brief Fast Writer using fwrite
+ * @tparam buffer_size Size of the internal buffer (default: 1 MB)
+ */
 template <size_t buffer_size = 1 << 20> struct FastWriteFWrite {
   char buf[buffer_size], *pos = buf;
 
@@ -79,12 +125,20 @@ template <size_t buffer_size = 1 << 20> struct FastWriteFWrite {
   FastWriteFWrite(const FastWriteFWrite &) = delete;
   FastWriteFWrite &operator=(const FastWriteFWrite &) = delete;
 
+  /**
+   * @brief Puts a character into the output buffer.
+   *        Flushes the buffer if it is full.
+   * @param c Character to put into the buffer.
+   */
   inline void putchar(char c) {
     if (pos - buf == buffer_size)
       flush();
     *pos++ = c;
   }
 
+  /**
+   * @brief Flushes the output buffer to stdout.
+   */
   inline void flush() {
     size_t write_size = pos - buf;
     if (write_size) {
@@ -93,9 +147,19 @@ template <size_t buffer_size = 1 << 20> struct FastWriteFWrite {
     }
   }
 
+  /**
+   * @brief Alias for putchar().
+   * @param c Character to put into the buffer.
+   */
   inline void operator()(char c) { putchar(c); }
 };
 
+/**
+ * @brief Fast Input/Output handler combining a Reader and a Writer.
+ * @tparam Reader Type of the input reader.
+ * @tparam Writer Type of the output writer.
+ * @tparam debug If true, uses standard I/O functions for debugging.
+ */
 template <typename Reader, typename Writer, bool debug = false> struct FastIO {
   Reader reader;
   Writer writer;
@@ -105,24 +169,45 @@ template <typename Reader, typename Writer, bool debug = false> struct FastIO {
   FastIO(const FastIO &) = delete;
   FastIO &operator=(const FastIO &) = delete;
 
+  /**
+   * @brief Gets the next character from input.
+   * @return The next character from input.
+   */
   inline char getchar() {
     if constexpr (debug)
       return std::getchar();
     else
       return reader.getchar();
   }
 
+  /**
+   * @brief Puts a character into output.
+   * @param c Character to put into output.
+   */
   inline void putchar(char c) {
     if constexpr (debug)
       std::putchar(c), std::fflush(stdout);
     else
       writer.putchar(c);
   }
 
+  /**
+   * @brief Flushes the output buffer.
+   */
   inline void flush() { writer.flush(); }
 
-  int32_t abs(int32_t x) { return x >= 0 ? x : -x; }
-
+  /**
+   * @brief Computes the absolute value of a 32-bit integer.
+   * @param x The integer to compute the absolute value for.
+   * @return The absolute value of x.
+   */
+  static int32_t abs(int32_t x) { return x >= 0 ? x : -x; }
+
+  /**
+   * @brief Reads an unsigned integer of type utype from input.
+   * @tparam utype Unsigned integer type to read.
+   * @return The read unsigned integer.
+   */
   template <typename utype> inline utype _read_u() {
     char c;
     do
@@ -135,6 +220,13 @@ template <typename Reader, typename Writer, bool debug = false> struct FastIO {
     return x;
   }
 
+  /**
+   * @brief Reads a signed integer of type itype from input.
+   * @tparam itype Signed integer type to read.
+   * @tparam utype Unsigned integer type used for intermediate calculations,
+   *         should be the corresponding unsigned type of itype.
+   * @return The read signed integer.
+   */
   template <typename itype, typename utype> inline itype _read_i() {
     char c;
     bool neg = false;
@@ -149,6 +241,12 @@ template <typename Reader, typename Writer, bool debug = false> struct FastIO {
     return static_cast<itype>(neg ? -x : x);
   }
 
+  /**
+   * @brief Writes an unsigned integer of type utype to output.
+   * @tparam utype Unsigned integer type to write.
+   * @tparam bufsize Size of the internal buffer used for conversion.
+   * @param x The unsigned integer to write.
+   */
   template <typename utype, size_t bufsize> inline void _write_u(utype x) {
     static char buf[bufsize];
     size_t len = 0;
@@ -159,6 +257,12 @@ template <typename Reader, typename Writer, bool debug = false> struct FastIO {
       putchar(buf[i]);
   }
 
+  /**
+   * @brief Writes a signed integer of type itype to output.
+   * @tparam itype Signed integer type to write.
+   * @tparam bufsize Size of the internal buffer used for conversion.
+   * @param x The signed integer to write.
+   */
   template <typename itype, size_t bufsize> inline void _write_i(itype x) {
     bool neg = x < 0;
     static char buf[bufsize];
@@ -172,22 +276,76 @@ template <typename Reader, typename Writer, bool debug = false> struct FastIO {
       putchar(buf[i]);
   }
 
+  /**
+   * @brief Reads a signed 32-bit integer from input.
+   * @return The read signed 32-bit integer.
+   */
   inline int32_t read_i32() { return _read_i<int32_t, uint32_t>(); }
+
+  /**
+   * @brief Reads an unsigned 32-bit integer from input.
+   * @return The read unsigned 32-bit integer.
+   */
   inline uint32_t read_u32() { return _read_u<uint32_t>(); }
 
+  /**
+   * @brief Writes a signed 32-bit integer to output.
+   * @param x The signed 32-bit integer to write.
+   */
   inline void write_i32(int32_t x) { _write_i<int32_t, 10>(x); }
+
+  /**
+   * @brief Writes an unsigned 32-bit integer to output.
+   * @param x The unsigned 32-bit integer to write.
+   */
   inline void write_u32(uint32_t x) { _write_u<uint32_t, 10>(x); }
 
+  /**
+   * @brief Reads a signed 64-bit integer from input.
+   * @return The read signed 64-bit integer.
+   */
   inline int64_t read_i64() { return _read_i<int64_t, uint64_t>(); }
+
+  /**
+   * @brief Reads an unsigned 64-bit integer from input.
+   * @return The read unsigned 64-bit integer.
+   */
   inline uint64_t read_u64() { return _read_u<uint64_t>(); }
 
+  /**
+   * @brief Writes a signed 64-bit integer to output.
+   * @param x The signed 64-bit integer to write.
+   */
   inline void write_i64(int64_t x) { _write_i<int64_t, 20>(x); }
+
+  /**
+   * @brief Writes an unsigned 64-bit integer to output.
+   * @param x The unsigned 64-bit integer to write.
+   */
   inline void write_u64(uint64_t x) { _write_u<uint64_t, 20>(x); }
 
+  /**
+   * @brief Reads a signed 128-bit integer from input.
+   * @return The read signed 128-bit integer.
+   */
   inline __int128 read_i128() { return _read_i<__int128, unsigned __int128>(); }
+
+  /**
+   * @brief Reads an unsigned 128-bit integer from input.
+   * @return The read unsigned 128-bit integer.
+   */
   inline unsigned __int128 read_u128() { return _read_u<unsigned __int128>(); }
 
+  /**
+   * @brief Writes a signed 128-bit integer to output.
+   * @param x The signed 128-bit integer to write.
+   */
   inline void write_i128(__int128 x) { _write_i<__int128, 40>(x); }
+
+  /**
+   * @brief Writes an unsigned 128-bit integer to output.
+   * @param x The unsigned 128-bit integer to write.
+   */
   inline void write_u128(unsigned __int128 x) {
     _write_u<unsigned __int128, 40>(x);
   }