1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
//! # hpdg
//!
//! `hpdg` is a Rust-first data generator for competitive programming and OI workflows.
//! The crate takes inspiration from tools such as CYaRon, but it leans into Rust's
//! own strengths: strong typing, feature-gated modules, reproducible randomness, and
//! composable building blocks.
//!
//! ## Why hpdg?
//!
//! - Build graph, string, vector, geometry, and query generators from a single crate.
//! - Keep testcase generation reproducible with seeded RNG streams.
//! - Use Rust-native abstractions such as traits and newtypes instead of stringly APIs.
//! - Mix quick scripts and larger generator codebases without changing tools.
//!
//! ## Quick Start
//!
//! ```rust
//! use hpdg::graph::Graph;
//! use hpdg::io::IO;
//! use hpdg::string::{SentenceConfig, StringGen};
//! use hpdg::vector::{IntRange, Vector};
//!
//! let mut io = IO::new("sample".to_string());
//!
//! let mut graph = Graph::new(4, false);
//! graph.add_edge(1, 2, None);
//! graph.add_edge(2, 3, None);
//!
//! let points = Vector::random_int(2, &[IntRange::MinMax(1, 5), IntRange::MinMax(10, 20)]);
//!
//! let mut cfg = SentenceConfig::default();
//! cfg.sentence_terminators = ".".to_string();
//! let sentence = StringGen::random_sentence(4, Some(&cfg));
//!
//! io.input_writeln("4 2");
//! io.input_writeln(graph);
//! io.input_writeln(points.len());
//! io.input_writeln(sentence);
//! ```
//!
//! ## Module Guide
//!
//! - [`io`]: testcase buffers, file naming, process execution, and streaming output.
//! - [`graph`]: graph containers plus random trees, DAGs, connected graphs, and helpers.
//! - [`math`]: number theory, combinatorics, digit helpers, and formatting utilities.
//! - [`sequence`]: memoized formula-based sequences and common progressions.
//! - [`vector`]: random integer and floating-point vectors and matrices.
//! - [`string`]: random words, sentences, paragraphs, dictionary sampling, and regex-like text.
//! - [`polygon`]: integer geometry helpers, convex hulls, and simple polygons.
//! - [`query`]: random range queries, mixed update/query streams, and weighted generators.
//! - [`compare`]: compare outputs from strings, files, or child processes with custom graders.
//! - [`rng`]: deterministic RNG wrappers and reproducible stream splitting.
//! - [`core`] and [`traits`]: Rust-flavored primitives such as newtypes and generator traits.
//!
//! ## Common Workflows
//!
//! - Generate graph-heavy datasets: [`graph::Graph`] + [`io::IO`]
//! - Build text or token data: [`string::StringGen`] + [`vector::Vector`] + [`io::IO`]
//! - Create reproducible batches: [`rng::SeededRng`] or [`rng::RngStream`]
//! - Run local checker loops: [`compare`] + [`io::IO::output_gen`]
//! - Build recurrence-driven values: [`sequence::Sequence`] + [`math`]
//!
//! ## Feature Guide
//!
//! Most modules are enabled by default. The most relevant optional integration features are:
//!
//! - `python-bindings`: enables PyO3-based Python bindings.
//! - `c-bindings`: enables the experimental C ABI module.
//!
//! Internal feature flags such as `graph`, `io`, `math`, `query`, `string`, and `vector`
//! mostly mirror module boundaries and can be used to slim down builds.
//!
//! ## Examples Index
//!
//! - `examples/full_generation.rs`: end-to-end sample combining graph, vector, string, and I/O.
//! - `docs/rust-quickstart.md`: short Rust-oriented getting-started notes.
//! - `docs/cyaron-api.md`: rough API mapping from CYaRon concepts to `hpdg`.
//!
//! ## Cross-links
//!
//! - Want deterministic testcase families? Start with [`rng`].
//! - Want local judge-like verification? Jump to [`compare`].
//! - Want graph generators specifically? [`graph::Graph`] is the main entry point.
//! - Want ergonomic file naming and flushing? See [`io::IO`] and [`testcase::Testcase`].
//!
//! ## Recommended Path
//!
//! If you are new to the crate, the smoothest way to explore it is:
//!
//! 1. Start with [`io::IO`] for testcase structure and file output.
//! 2. Pick a generator module such as [`graph::Graph`], [`string::StringGen`], or [`vector::Vector`].
//! 3. Use [`rng::SeededRng`] or [`rng::RngStream`] when you need reproducible cases.
//! 4. Add [`compare`] helpers when you want a local standard-solution workflow.
//!
//! ## Stability
//!
//! `hpdg` is still evolving. The core modules are usable today, but APIs may change before
//! `1.0` as the crate becomes more polished and more Rust-idiomatic.
//!
/// Experimental C ABI bindings.
/// Output comparison utilities and customizable graders.
/// Rust-first primitives such as strongly typed node and edge identifiers.
/// Shared error types used across the crate.
/// Graph containers, formatters, and random graph/tree generators.
/// Testcase I/O buffers, file naming, process execution, and streaming writers.
/// Math helpers for number theory, combinatorics, digits, and formatting.
/// Integer geometry helpers for points and polygons.
/// Random range-query generators, including weighted and mixed workloads.
/// Deterministic RNG wrappers and reproducible random streams.
/// Memoized formula-based sequences and common progression helpers.
/// Random strings, words, sentences, paragraphs, and regex-like generators.
/// Backward-compatible alias around [`io::IO`].
/// Traits for building reusable generator abstractions.
/// Small utility helpers for argument parsing, path escaping, and trait probes.
/// Random vectors, matrices, and vector formatting utilities.