Skip to content

Commit a5326fe

Browse files
trcrsiredtrcrsired
authored
Merge pull request #1243 from trcrsired/next
Add fast_io::iomnp namespace
2 parents 3c4b1e9 + ce085d4 commit a5326fe

File tree

15 files changed

+714
-77
lines changed

15 files changed

+714
-77
lines changed

‎docs/docs/01.helloworld/index.html‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Hello World - fast_io Documentation</title>
7+
<link rel="stylesheet" href="/style.css">
8+
<link rel="manifest" href="/manifest.json">
9+
</head>
10+
<body>
11+
<main>
12+
<h1>Hello World</h1>
13+
14+
<section>
15+
<h2>Hello World</h2>
16+
<p>
17+
A minimal program using <code>fast_io</code> to print <em>Hello World</em>:
18+
</p>
19+
<pre><code class="language-cpp">
20+
#include &lt;fast_io.h&gt;
21+
22+
int main()
23+
{
24+
using namespace ::fast_io::io;
25+
print("Hello World\n");
26+
}
27+
</code></pre>
28+
<p>
29+
By default, <code>::fast_io::io::print</code> writes to C’s <code>FILE*</code> <code>stdout</code> object.
30+
This means the output goes to the standard output stream, just like <code>printf</code> or
31+
<code>std::cout</code>, but with safer and faster semantics.
32+
</p>
33+
<p>
34+
In practice, using <code>fast_io</code> together with <code>stdio</code> or <code>iostream</code>
35+
usually does not cause issues. The only problematic cases arise if code calls unusual functions
36+
like <code>unput</code>, which can break assumptions because neither <code>stdio</code> nor
37+
<code>iostream</code> guarantee consistent behavior for such operations. As long as you avoid
38+
those unsafe edge cases, interoperability is fine.
39+
</p>
40+
</section>
41+
42+
<div class="page-navigation">
43+
<a href="/docs/intro" class="prev-button">← Previous: Introduction</a>
44+
<a href="/" class="main-button">↑ Back to Main Page</a>
45+
<a href="/docs/02.aplusb" class="next-button">Next: A + B Example →</a>
46+
</div>
47+
</main>
48+
</body>
49+
</html>

‎docs/docs/02.aplusb/index.html‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>A + B - fast_io Documentation</title>
7+
<link rel="stylesheet" href="/style.css">
8+
<link rel="manifest" href="/manifest.json">
9+
</head>
10+
<body>
11+
<main>
12+
<h1>A + B</h1>
13+
14+
<section>
15+
<h2>Basic Input and Output</h2>
16+
<p>
17+
A simple program that reads two integers and prints their sum. This demonstrates
18+
<code>scan</code> for input and <code>println</code> for output:
19+
</p>
20+
<pre><code class="language-cpp">
21+
#include &lt;fast_io.h&gt;
22+
23+
using namespace fast_io::io;
24+
25+
int main()
26+
{
27+
std::size_t a, b;
28+
scan(a, b);
29+
println(a + b);
30+
}
31+
</code></pre>
32+
</section>
33+
34+
<section>
35+
<h2>What is a Manipulator?</h2>
36+
<p>
37+
In <code>fast_io</code>, a <strong>manipulator</strong> is a helper object that changes how
38+
input or output is interpreted or formatted. Instead of relying on unsafe format strings,
39+
manipulators make the intent explicit in the type system.
40+
</p>
41+
<p>
42+
Manipulators are defined in the namespace <code>fast_io::manipulators</code>, which is aliased
43+
as <code>fast_io::mnp</code> for convenience. They make input and output safer, more explicit,
44+
and more portable than traditional <code>stdio</code> or <code>iostream</code>.
45+
</p>
46+
<p>
47+
For example:
48+
</p>
49+
<ul>
50+
<li><code>hex_get(a)</code> — tells <code>scan</code> to read the variable <code>a</code> in hexadecimal.</li>
51+
<li><code>hex(a)</code> — tells <code>println</code> to print <code>a</code> in lowercase hexadecimal.</li>
52+
<li><code>hexupper(a)</code> — prints <code>a</code> in uppercase hexadecimal.</li>
53+
<li><code>base_get&lt;N&gt;(a)</code> — reads <code>a</code> in base <em>N</em> (2 ≤ N ≤ 36).</li>
54+
<li><code>base&lt;N&gt;(a)</code> — prints <code>a</code> in base <em>N</em>.</li>
55+
</ul>
56+
</section>
57+
58+
<section>
59+
<h2>Hexadecimal Manipulators</h2>
60+
<p>
61+
<code>fast_io</code> provides manipulators to read and print numbers in hexadecimal.
62+
<code>hex_get</code> reads input in hex, while <code>hex</code> and <code>hexupper</code>
63+
print output in lowercase or uppercase hex respectively:
64+
</p>
65+
<pre><code class="language-cpp">
66+
#include &lt;fast_io.h&gt;
67+
68+
using namespace fast_io::io;
69+
70+
int main()
71+
{
72+
using namespace fast_io::mnp;
73+
std::size_t a, b;
74+
scan(hex_get(a), hex_get(b));
75+
println(hex(a + b), " ", hexupper(a + b));
76+
}
77+
</code></pre>
78+
</section>
79+
80+
<section>
81+
<h2>Base-N Manipulators</h2>
82+
<p>
83+
Manipulators also support arbitrary bases from 2 to 36. Here’s an example using base 36:
84+
</p>
85+
<pre><code class="language-cpp">
86+
#include &lt;fast_io.h&gt;
87+
88+
using namespace fast_io::io;
89+
90+
int main()
91+
{
92+
using namespace fast_io::mnp;
93+
std::size_t a, b;
94+
scan(base_get&lt;36&gt;(a), base_get&lt;36&gt;(b));
95+
println(base&lt;36&gt;(a + b));
96+
}
97+
</code></pre>
98+
</section>
99+
100+
<section>
101+
<h2>About Manipulators</h2>
102+
<p>
103+
<code>fast_io</code> defines a rich set of <strong>manipulators</strong> to control input and output formatting.
104+
For convenience, the namespace <code>fast_io::manipulators</code> is aliased as <code>fast_io::mnp</code>.
105+
</p>
106+
<ul>
107+
<li><code>base_get&lt;N&gt;</code> — reads numbers in base <em>N</em> (where 2 ≤ N ≤ 36).</li>
108+
<li><code>base&lt;N&gt;</code> — prints numbers in base <em>N</em>.</li>
109+
<li><code>hex</code> — shorthand for <code>base&lt;16&gt;</code>.</li>
110+
<li><code>hexupper</code> — shorthand for <code>base&lt;16,true&gt;</code>, printing hex digits in uppercase.</li>
111+
</ul>
112+
<p>
113+
These manipulators make it easy to work with different numeric bases without relying on unsafe format strings.
114+
</p>
115+
</section>
116+
117+
<div class="page-navigation">
118+
<a href="/docs/01.helloworld" class="prev-button">← Previous: Hello World</a>
119+
<a href="/" class="main-button">↑ Back to Main Page</a>
120+
<a href="/docs/03.pointer" class="next-button">Next: Pointer →</a>
121+
</div>
122+
</main>
123+
</body>
124+
</html>

‎docs/docs/03.pointer/index.html‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>Pointers - fast_io Documentation</title>
7+
<link rel="stylesheet" href="/style.css">
8+
<link rel="manifest" href="/manifest.json">
9+
</head>
10+
<body>
11+
<main>
12+
<h1>Pointers</h1>
13+
14+
<section>
15+
<h2>Introduction</h2>
16+
<p>
17+
In <code>fast_io</code>, raw pointers and iterators are not printed directly. This is a deliberate
18+
safety choice: printing them without explicit intent can lead to undefined or inconsistent
19+
behavior across platforms. Instead, <code>fast_io</code> provides a family of <strong>pointer‑related
20+
manipulators</strong> that make the intent explicit and ensure consistent, portable formatting.
21+
</p>
22+
</section>
23+
24+
<section>
25+
<h2>Pointer Manipulators Overview</h2>
26+
<ul>
27+
<li><code>pointervw(ptr)</code> — prints the raw address of a pointer in fixed‑width hexadecimal.</li>
28+
<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>
29+
<li><code>funcvw(f)</code> — prints the address of a free function.</li>
30+
<li><code>methodvw(m)</code> — prints member function pointers, including offset information for multiple inheritance.</li>
31+
<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>
32+
</ul>
33+
</section>
34+
35+
<section>
36+
<h2>Printing Pointers</h2>
37+
<p>
38+
Use <code>pointervw</code> to print raw addresses. The format is consistent across platforms:
39+
<code>0x</code> followed by 8 hex digits on 32‑bit systems, or 16 hex digits on 64‑bit systems.
40+
</p>
41+
<pre><code class="language-cpp">
42+
#include &lt;fast_io.h&gt;
43+
44+
using namespace fast_io::io;
45+
46+
int main()
47+
{
48+
using namespace fast_io::mnp;
49+
int x{42};
50+
int *ptr{::std::addressof(x)};
51+
println("Address:", pointervw(ptr));
52+
}
53+
</code></pre>
54+
</section>
55+
56+
<section>
57+
<h2>C‑String Manipulator</h2>
58+
<p>
59+
To treat a <code>char const*</code> as a C‑string, use <code>os_c_str</code>. This calls
60+
<code>strlen</code> or <code>strnlen</code> depending on overload.
61+
</p>
62+
<pre><code class="language-cpp">
63+
#include &lt;fast_io.h&gt;
64+
65+
int main()
66+
{
67+
using namespace fast_io::io;
68+
using namespace fast_io::mnp;
69+
constexpr char const* ptr{"Hello\0World\n"};
70+
71+
println(
72+
"Literal: Hello\0World\n\n"
73+
"Pointer:", pointervw(ptr), "\n"
74+
"os_c_str:", os_c_str(ptr), "\n"
75+
"os_c_str(ptr,4):", os_c_str(ptr,4), "\n"
76+
"os_c_str(ptr,10):", os_c_str(ptr,10)
77+
);
78+
}
79+
</code></pre>
80+
</section>
81+
82+
<section>
83+
<h2>Function and Method Pointers</h2>
84+
<p>
85+
<code>funcvw</code> prints the address of a free function. <code>methodvw</code> prints member
86+
function pointers, including offset information for multiple inheritance cases.
87+
</p>
88+
<pre><code class="language-cpp">
89+
#include &lt;fast_io.h&gt;
90+
#include &lt;memory&gt;
91+
92+
class dummy_class { public: void dummy_method() noexcept {} };
93+
struct A { virtual void f() noexcept {} };
94+
struct B { virtual void g() noexcept {} };
95+
struct C : A, B {};
96+
97+
using namespace fast_io::io;
98+
99+
void foo(){}
100+
101+
int main()
102+
{
103+
using namespace fast_io::mnp;
104+
void (C::*downcptr)() noexcept = &B::g;
105+
106+
println(
107+
"funcvw(foo):", funcvw(foo), "\n"
108+
109+
"methodvw(&dummy_class::dummy_method):",
110+
methodvw(&dummy_class::dummy_method), "\n"
111+
112+
"methodvw(downcptr):", methodvw(downcptr)
113+
);
114+
}
115+
</code></pre>
116+
</section>
117+
118+
<section>
119+
<h2>Handles</h2>
120+
<p>
121+
<code>handlevw</code> is used when printing operating system handles. A handle may be an
122+
integer (POSIX file descriptor) or a pointer (Win32 <code>HANDLE</code>, <code>FILE*</code>).
123+
<code>handlevw</code> adapts automatically, printing integers directly and pointers in
124+
consistent hexadecimal format.
125+
</p>
126+
<pre><code class="language-cpp">
127+
#include &lt;fast_io.h&gt;
128+
#include &lt;cstdio&gt;
129+
130+
using namespace fast_io::io;
131+
132+
int main()
133+
{
134+
using namespace fast_io::mnp;
135+
int fd{3}; // POSIX file descriptor
136+
FILE *f{stdout};
137+
138+
println(
139+
"POSIX fd:", handlevw(fd), "\n"
140+
"FILE* handle:", handlevw(f)
141+
);
142+
}
143+
</code></pre>
144+
</section>
145+
146+
<section>
147+
<h2>Summary</h2>
148+
<p>
149+
Pointer‑related manipulators in <code>fast_io</code> make printing low‑level entities explicit,
150+
safe, and portable. They cover raw pointers, C‑strings, free functions, member functions,
151+
and OS handles. This design avoids the unsafe and inconsistent behavior of
152+
<code>stdio</code> and <code>iostream</code>.
153+
</p>
154+
</section>
155+
156+
<div class="page-navigation">
157+
<a href="/docs/02.aplusb" class="prev-button">← Previous: A+B</a>
158+
<a href="/" class="main-button">↑ Back to Main Page</a>
159+
<a href="/docs/04.fileio" class="next-button"> Next: File I/O →</a>
160+
</div>
161+
</main>
162+
</body>
163+
</html>

0 commit comments

Comments
 (0)