From be6e64a6fd88b7bf27ec8ec93a8a26e48b2d0e9f Mon Sep 17 00:00:00 2001 From: trcrsired Date: Mon, 15 Dec 2025 02:18:37 +0800 Subject: [PATCH 1/7] Add 3 examples --- docs/docs/01.helloworld.html | 48 +++++++++++ docs/docs/02.aplusb.html | 123 ++++++++++++++++++++++++++ docs/docs/03.pointer.html | 163 +++++++++++++++++++++++++++++++++++ docs/docs/examples.html | 45 ---------- docs/docs/intro.html | 2 +- docs/index.html | 2 +- docs/sw.js | 7 +- 7 files changed, 342 insertions(+), 48 deletions(-) create mode 100644 docs/docs/01.helloworld.html create mode 100644 docs/docs/02.aplusb.html create mode 100644 docs/docs/03.pointer.html delete mode 100644 docs/docs/examples.html diff --git a/docs/docs/01.helloworld.html b/docs/docs/01.helloworld.html new file mode 100644 index 00000000..350a754d --- /dev/null +++ b/docs/docs/01.helloworld.html @@ -0,0 +1,48 @@ + + + + + + Hello World - fast_io Documentation + + + + +
+

Hello World

+ +
+

Hello World

+

+ A minimal program using fast_io to print Hello World: +

+ 

+#include <fast_io.h>
+
+int main()
+{
+    using namespace ::fast_io::io;
+    print("Hello World\n");
+}
+
+

+ By default, fast_io::print writes to C’s FILE* stdout object. + This means the output goes to the standard output stream, just like printf or + std::cout, but with safer and faster semantics. +

+

+ In practice, using fast_io together with stdio or iostream + usually does not cause issues. The only problematic cases arise if code calls unusual functions + like unput, which can break assumptions because neither stdio nor + iostream guarantee consistent behavior for such operations. As long as you avoid + those unsafe edge cases, interoperability is fine. +

+
+ +
+ ← Previous: Introduction + Next: A + B Example → +
+
+ + diff --git a/docs/docs/02.aplusb.html b/docs/docs/02.aplusb.html new file mode 100644 index 00000000..4cbac735 --- /dev/null +++ b/docs/docs/02.aplusb.html @@ -0,0 +1,123 @@ + + + + + + A + B Example - fast_io Documentation + + + + +
+

A + B Example

+ +
+

Basic Input and Output

+

+ A simple program that reads two integers and prints their sum. This demonstrates + scan for input and println for output: +

+ 

+#include <fast_io.h>
+
+using namespace fast_io::io;
+
+int main()
+{
+    std::size_t a, b;
+    scan(a, b);
+    println(a + b);
+}
+
+
+ +
+

What is a Manipulator?

+

+ In fast_io, a manipulator is a helper object that changes how + input or output is interpreted or formatted. Instead of relying on unsafe format strings, + manipulators make the intent explicit in the type system. +

+

+ Manipulators are defined in the namespace fast_io::manipulators, which is aliased + as fast_io::mnp for convenience. They make input and output safer, more explicit, + and more portable than traditional stdio or iostream. +

+

+ For example: +

+
    +
  • hex_get(a) — tells scan to read the variable a in hexadecimal.
    • +
  • hex(a) — tells println to print a in lowercase hexadecimal.
    • +
  • hexupper(a) — prints a in uppercase hexadecimal.
    • +
  • base_get<N>(a) — reads a in base N (2 ≤ N ≤ 36).
    • +
  • base<N>(a) — prints a in base N.
    • +
+
+ +
+

Hexadecimal Manipulators

+

+ fast_io provides manipulators to read and print numbers in hexadecimal. + hex_get reads input in hex, while hex and hexupper + print output in lowercase or uppercase hex respectively: +

+ 

+#include <fast_io.h>
+
+using namespace fast_io::io;
+
+int main()
+{
+    using namespace fast_io::mnp;
+    std::size_t a, b;
+    scan(hex_get(a), hex_get(b));
+    println(hex(a + b), " ", hexupper(a + b));
+}
+
+
+ +
+

Base-N Manipulators

+

+ Manipulators also support arbitrary bases from 2 to 36. Here’s an example using base 36: +

+ 

+#include <fast_io.h>
+
+using namespace fast_io::io;
+
+int main()
+{
+    using namespace fast_io::mnp;
+    std::size_t a, b;
+    scan(base_get<36>(a), base_get<36>(b));
+    println(base<36>(a + b));
+}
+
+
+ +
+

About Manipulators

+

+ fast_io defines a rich set of manipulators to control input and output formatting. + For convenience, the namespace fast_io::manipulators is aliased as fast_io::mnp. +

+
    +
  • base_get<N> — reads numbers in base N (where 2 ≤ N ≤ 36).
    • +
  • base<N> — prints numbers in base N.
    • +
  • hex — shorthand for base<16>.
    • +
  • hexupper — shorthand for base<16,true>, printing hex digits in uppercase.
    • +
+

+ These manipulators make it easy to work with different numeric bases without relying on unsafe format strings. +

+
+ +
+ ← Previous: Hello World + Next: Pointer → +
+
+ + diff --git a/docs/docs/03.pointer.html b/docs/docs/03.pointer.html new file mode 100644 index 00000000..591c06da --- /dev/null +++ b/docs/docs/03.pointer.html @@ -0,0 +1,163 @@ + + + + + + Pointers - fast_io Documentation + + + + +
+

Pointers in fast_io

+ +
+

Introduction

+

+ In fast_io, raw pointers and iterators are not printed directly. This is a deliberate + safety choice: printing them without explicit intent can lead to undefined or inconsistent + behavior across platforms. Instead, fast_io provides a family of pointer‑related + manipulators that make the intent explicit and ensure consistent, portable formatting. +

+
+ +
+

Pointer Manipulators Overview

+
    +
  • pointervw(ptr) — prints the raw address of a pointer in fixed‑width hexadecimal.
    • +
  • os_c_str(ptr) — treats a char const* as a C‑string, using strlen or strnlen.
    • +
  • funcvw(f) — prints the address of a free function.
    • +
  • methodvw(m) — prints member function pointers, including offset information for multiple inheritance.
    • +
  • handlevw(h) — prints operating system handles, whether represented as integers (POSIX fd) or pointers (Win32 HANDLE, FILE*).
    • +
+
+ +
+

Printing Pointers

+

+ Use pointervw to print raw addresses. The format is consistent across platforms: + 0x followed by 8 hex digits on 32‑bit systems, or 16 hex digits on 64‑bit systems. +

+ 

+#include <fast_io.h>
+
+using namespace fast_io::io;
+
+int main()
+{
+    using namespace fast_io::mnp;
+    int x{42};
+    int* ptr = &x;
+    println("Address:", pointervw(ptr));
+}
+
+
+ +
+

C‑String Manipulator

+

+ To treat a char const* as a C‑string, use os_c_str. This calls + strlen or strnlen depending on overload. +

+ 

+#include <fast_io.h>
+
+using namespace fast_io::io;
+#include 
+
+using namespace fast_io::io;
+
+int main()
+{
+    using namespace fast_io::mnp;
+    constexpr char const* ptr{"Hello\0World\n"};
+
+    println(
+        "Literal: Hello\0World\n\n"
+        "Pointer:", pointervw(ptr), "\n"
+        "os_c_str:", os_c_str(ptr), "\n"
+        "os_c_str(ptr,4):", os_c_str(ptr,4), "\n"
+        "os_c_str(ptr,10):", os_c_str(ptr,10)
+    );
+}
+
+
+ +
+

Function and Method Pointers

+

+ funcvw prints the address of a free function. methodvw prints member + function pointers, including offset information for multiple inheritance cases. +

+ 

+#include <fast_io.h>
+#include <memory>
+
+class dummy_class { public: void dummy_method() noexcept {} };
+struct A { virtual void f() noexcept {} };
+struct B { virtual void g() noexcept {} };
+struct C : A, B {};
+
+using namespace fast_io::io;
+
+void foo(){}
+
+int main()
+{
+    using namespace fast_io::mnp;
+    void (C::*downcptr)() noexcept = &B::g;
+
+    println(
+        "funcvw(foo):", funcvw(foo), "\n",
+        "methodvw(&dummy_class::dummy_method):", methodvw(&dummy_class::dummy_method), "\n",
+        "methodvw(downcptr):", methodvw(downcptr)
+    );
+}
+
+
+ +
+

Handles

+

+ handlevw is used when printing operating system handles. A handle may be an + integer (POSIX file descriptor) or a pointer (Win32 HANDLE, FILE*). + handlevw adapts automatically, printing integers directly and pointers in + consistent hexadecimal format. +

+ 

+#include <fast_io.h>
+#include <cstdio>
+
+using namespace fast_io::io;
+
+int main()
+{
+    using namespace fast_io::mnp;
+    int fd{3};       // POSIX file descriptor
+    FILE* f = stdout;
+
+    println(
+        "POSIX fd:", handlevw(fd), "\n",
+        "FILE* handle:", handlevw(f)
+    );
+}
+
+
+ +
+

Summary

+

+ Pointer‑related manipulators in fast_io make printing low‑level entities explicit, + safe, and portable. They cover raw pointers, C‑strings, free functions, member functions, + and OS handles. This design avoids the unsafe and inconsistent behavior of + stdio and iostream. +

+
+ +
+ ← Previous: Hello World + +
+
+ + diff --git a/docs/docs/examples.html b/docs/docs/examples.html deleted file mode 100644 index d3e0d864..00000000 --- a/docs/docs/examples.html +++ /dev/null @@ -1,45 +0,0 @@ - - - - - - Examples - fast_io Documentation - - - - -
-

Examples

- -
-

Hello World Example

-

- A minimal program using fast_io to print Hello World: -

- 

-#include <fast_io.h>
-
-int main()
-{
-    using namespace ::fast_io::io;
-    print("Hello World\n");
-}
-
-
- - -
-

More Examples Coming Soon

-

- Additional examples demonstrating input, file handling, and platform compatibility will be added here. -

-
- -
- ← Previous: Introduction - Next: API Reference → -
-
- - - diff --git a/docs/docs/intro.html b/docs/docs/intro.html index 4f6ab8ad..cb25eac1 100644 --- a/docs/docs/intro.html +++ b/docs/docs/intro.html @@ -149,7 +149,7 @@

Video Introduction

- Next: Examples → + Next: Hello World →
diff --git a/docs/index.html b/docs/index.html index 71e96611..996191dd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -11,8 +11,8 @@

fast_io