Skip to content

Add fast_io::iomnp namespace #1243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trcrsired merged 7 commits into from
Dec 16, 2025
Merged

Add fast_io::iomnp namespace #1243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
be6e64a
Add 3 examples
trcrsired Dec 14, 2025
fa1f789
add more docs also enable service worker
trcrsired Dec 14, 2025
4f57941
Move docs/xxx.html to docs/xxx/index.html or cloudflare would not fin…
trcrsired Dec 14, 2025
177d61f
Deal with several mistakes in documentaions for the usage of copilot
trcrsired Dec 15, 2025
6a210f8
Add explainations for every layer of file types
trcrsired Dec 15, 2025
3b27f33
Add fast_io::iomnp namespace for allowing user to do things like
trcrsired Dec 16, 2025
ce085d4
0002.a+b should not test any of them
trcrsired Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/docs/01.helloworld/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Hello World - fast_io Documentation</title>
<link rel="stylesheet" href="/style.css">
<link rel="manifest" href="/manifest.json">
</head>
<body>
<main>
<h1>Hello World</h1>

<section>
<h2>Hello World</h2>
<p>
A minimal program using <code>fast_io</code> to print <em>Hello World</em>:
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;

int main()
{
using namespace ::fast_io::io;
print("Hello World\n");
}
</code></pre>
<p>
By default, <code>::fast_io::io::print</code> writes to C’s <code>FILE*</code> <code>stdout</code> object.
This means the output goes to the standard output stream, just like <code>printf</code> or
<code>std::cout</code>, but with safer and faster semantics.
</p>
<p>
In practice, using <code>fast_io</code> together with <code>stdio</code> or <code>iostream</code>
usually does not cause issues. The only problematic cases arise if code calls unusual functions
like <code>unput</code>, which can break assumptions because neither <code>stdio</code> nor
<code>iostream</code> guarantee consistent behavior for such operations. As long as you avoid
those unsafe edge cases, interoperability is fine.
</p>
</section>

<div class="page-navigation">
<a href="/docs/intro" class="prev-button">← Previous: Introduction</a>
<a href="/" class="main-button">↑ Back to Main Page</a>
<a href="/docs/02.aplusb" class="next-button">Next: A + B Example →</a>
</div>
</main>
</body>
</html>
124 changes: 124 additions & 0 deletions docs/docs/02.aplusb/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>A + B - fast_io Documentation</title>
<link rel="stylesheet" href="/style.css">
<link rel="manifest" href="/manifest.json">
</head>
<body>
<main>
<h1>A + B</h1>

<section>
<h2>Basic Input and Output</h2>
<p>
A simple program that reads two integers and prints their sum. This demonstrates
<code>scan</code> for input and <code>println</code> for output:
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;

using namespace fast_io::io;

int main()
{
std::size_t a, b;
scan(a, b);
println(a + b);
}
</code></pre>
</section>

<section>
<h2>What is a Manipulator?</h2>
<p>
In <code>fast_io</code>, a <strong>manipulator</strong> 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.
</p>
<p>
Manipulators are defined in the namespace <code>fast_io::manipulators</code>, which is aliased
as <code>fast_io::mnp</code> for convenience. They make input and output safer, more explicit,
and more portable than traditional <code>stdio</code> or <code>iostream</code>.
</p>
<p>
For example:
</p>
<ul>
<li><code>hex_get(a)</code> — tells <code>scan</code> to read the variable <code>a</code> in hexadecimal.</li>
<li><code>hex(a)</code> — tells <code>println</code> to print <code>a</code> in lowercase hexadecimal.</li>
<li><code>hexupper(a)</code> — prints <code>a</code> in uppercase hexadecimal.</li>
<li><code>base_get&lt;N&gt;(a)</code> — reads <code>a</code> in base <em>N</em> (2 ≤ N ≤ 36).</li>
<li><code>base&lt;N&gt;(a)</code> — prints <code>a</code> in base <em>N</em>.</li>
</ul>
</section>

<section>
<h2>Hexadecimal Manipulators</h2>
<p>
<code>fast_io</code> provides manipulators to read and print numbers in hexadecimal.
<code>hex_get</code> reads input in hex, while <code>hex</code> and <code>hexupper</code>
print output in lowercase or uppercase hex respectively:
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;

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));
}
</code></pre>
</section>

<section>
<h2>Base-N Manipulators</h2>
<p>
Manipulators also support arbitrary bases from 2 to 36. Here’s an example using base 36:
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;

using namespace fast_io::io;

int main()
{
using namespace fast_io::mnp;
std::size_t a, b;
scan(base_get&lt;36&gt;(a), base_get&lt;36&gt;(b));
println(base&lt;36&gt;(a + b));
}
</code></pre>
</section>

<section>
<h2>About Manipulators</h2>
<p>
<code>fast_io</code> defines a rich set of <strong>manipulators</strong> to control input and output formatting.
For convenience, the namespace <code>fast_io::manipulators</code> is aliased as <code>fast_io::mnp</code>.
</p>
<ul>
<li><code>base_get&lt;N&gt;</code> — reads numbers in base <em>N</em> (where 2 ≤ N ≤ 36).</li>
<li><code>base&lt;N&gt;</code> — prints numbers in base <em>N</em>.</li>
<li><code>hex</code> — shorthand for <code>base&lt;16&gt;</code>.</li>
<li><code>hexupper</code> — shorthand for <code>base&lt;16,true&gt;</code>, printing hex digits in uppercase.</li>
</ul>
<p>
These manipulators make it easy to work with different numeric bases without relying on unsafe format strings.
</p>
</section>

<div class="page-navigation">
<a href="/docs/01.helloworld" class="prev-button">← Previous: Hello World</a>
<a href="/" class="main-button">↑ Back to Main Page</a>
<a href="/docs/03.pointer" class="next-button">Next: Pointer →</a>
</div>
</main>
</body>
</html>
163 changes: 163 additions & 0 deletions docs/docs/03.pointer/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Pointers - fast_io Documentation</title>
<link rel="stylesheet" href="/style.css">
<link rel="manifest" href="/manifest.json">
</head>
<body>
<main>
<h1>Pointers</h1>

<section>
<h2>Introduction</h2>
<p>
In <code>fast_io</code>, 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, <code>fast_io</code> provides a family of <strong>pointer‑related
manipulators</strong> that make the intent explicit and ensure consistent, portable formatting.
</p>
</section>

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

<section>
<h2>Printing Pointers</h2>
<p>
Use <code>pointervw</code> to print raw addresses. The format is consistent across platforms:
<code>0x</code> followed by 8 hex digits on 32‑bit systems, or 16 hex digits on 64‑bit systems.
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;

using namespace fast_io::io;

int main()
{
using namespace fast_io::mnp;
int x{42};
int *ptr{::std::addressof(x)};
println("Address:", pointervw(ptr));
}
</code></pre>
</section>

<section>
<h2>C‑String Manipulator</h2>
<p>
To treat a <code>char const*</code> as a C‑string, use <code>os_c_str</code>. This calls
<code>strlen</code> or <code>strnlen</code> depending on overload.
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;

int main()
{
using namespace fast_io::io;
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)
);
}
</code></pre>
</section>

<section>
<h2>Function and Method Pointers</h2>
<p>
<code>funcvw</code> prints the address of a free function. <code>methodvw</code> prints member
function pointers, including offset information for multiple inheritance cases.
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;
#include &lt;memory&gt;

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)
);
}
</code></pre>
</section>

<section>
<h2>Handles</h2>
<p>
<code>handlevw</code> is used when printing operating system handles. A handle may be an
integer (POSIX file descriptor) or a pointer (Win32 <code>HANDLE</code>, <code>FILE*</code>).
<code>handlevw</code> adapts automatically, printing integers directly and pointers in
consistent hexadecimal format.
</p>
<pre><code class="language-cpp">
#include &lt;fast_io.h&gt;
#include &lt;cstdio&gt;

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)
);
}
</code></pre>
</section>

<section>
<h2>Summary</h2>
<p>
Pointer‑related manipulators in <code>fast_io</code> 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
<code>stdio</code> and <code>iostream</code>.
</p>
</section>

<div class="page-navigation">
<a href="/docs/02.aplusb" class="prev-button">← Previous: A+B</a>
<a href="/" class="main-button">↑ Back to Main Page</a>
<a href="/docs/04.fileio" class="next-button"> Next: File I/O →</a>
</div>
</main>
</body>
</html>
Loading