From 0cbb8bf372a5cedbd9450224d81f564213385856 Mon Sep 17 00:00:00 2001 From: Ashar Fuadi Date: Sat, 16 Nov 2024 17:04:24 +0700 Subject: [PATCH] Docs refinement: add tables and hrs --- web/docs/api/01-problem-spec.md | 219 ++++++++++++++++++++++++++------ web/docs/api/02-test-spec.md | 16 ++- web/docs/api/03-rnd.md | 2 + 3 files changed, 195 insertions(+), 42 deletions(-) diff --git a/web/docs/api/01-problem-spec.md b/web/docs/api/01-problem-spec.md index 275101c..25e9a17 100644 --- a/web/docs/api/01-problem-spec.md +++ b/web/docs/api/01-problem-spec.md @@ -12,6 +12,8 @@ class ProblemSpec : public BaseProblemSpec {}; Except for private helper functions, every member of `ProblemSpec` listed below must be `protected`. +--- + ## Input/output variables Defined as instance member variables of `ProblemSpec`, which will be referenced in other methods of `ProblemSpec` and `TestSpec`. @@ -30,9 +32,7 @@ Variables of built-in integral types (`int`, `long long`, `char`, etc.), built-i `std::vector>`, where `T` is a scalar type as defined above. 2D arrays (`T[][]`) are not supported. ---- - -Example: +**Example** ```cpp class ProblemSpec : public BaseProblemSpec { @@ -43,6 +43,8 @@ protected: }; ``` +--- + ## Input/output formats ### `InputFormat()` @@ -53,6 +55,8 @@ virtual void InputFormat() = 0; Defines the input format. It is mandatory. +--- + ### `OutputFormat()`, `OutputFormatX()` ```cpp @@ -66,6 +70,8 @@ virtual void OutputFormat5() {} Defines the possible output format(s). If there is only one output format, only `OutputFormat()` can be specified, otherwise multiple `OutputFormatX()` should be specified. +--- + ### Definitions The following macros are exposed to define input/output formats: @@ -78,10 +84,7 @@ The following macros are exposed to define input/output formats: Defines an empty line. -Usage: - -- `EMPTY_LINE();` - +--- #### `RAW_LINE()` @@ -89,27 +92,43 @@ Usage: #define RAW_LINE(var) /* see below */ ``` -Defines a line of raw string. - -Usage: - -- `RAW_LINE();` +Defines a line of raw string (which may contain whitespaces). The variable must be a `std::string`. -The variable must be of `std::string` type. +**Example** -Example: + + + + + + + + + + + + + + + +
UsageVariableFormat
```cpp void InputFormat() { RAW_LINE(S); } ``` + -With **S** = "Hello, world!", the above format will produce: +**S** = "Hello, world!" + ``` Hello, world! ``` +
+ +--- #### `RAW_LINES()` @@ -124,9 +143,22 @@ Usage: - `RAW_LINES();` - `RAW_LINES() % SIZE();` -The variable must be of `std::vector` type. If the size is not given, then this must be the last segment in the I/O format. +The variable must be a vector of `std::string`. If the size is not given, then this must be the last segment in the I/O format. + +**Example** + + + + + + + + + + + + + + + + +
UsageVariablesFormat
-Example: ```cpp void InputFormat() { @@ -134,8 +166,18 @@ void InputFormat() { RAW_LINES(Y); } ``` + -With **X** = \{"Hello, world!", "Happy new year."}, **Y** = \{"lorem", "ipsum", "dolor sit amet"}, the above format will produce: +- **X** = \{ + - "Hello, world!", + - "Happy new year."} +- **Y** = \{ + - "lorem", + - "ipsum", + - "dolor sit amet"} + ``` Hello, world! @@ -144,6 +186,12 @@ lorem ipsum dolor sit amet ``` +
+ +--- #### `LINE()` @@ -163,7 +211,19 @@ where each **arg** is one of: - ` % SIZE()`. The number of elements can be a constant or a scalar variable. - ``. Here, the number of elements is unspecified. This kind of element must occur last in a line segment, if any. Elements will be considered until new line is found. -Example: +**Example** + + + + + + + + + + + + + + + + +
UsageVariablesFormat
```cpp void InputFormat() { @@ -172,14 +232,28 @@ void InputFormat() { LINE(M, C % SIZE(M)); } ``` + -With **N** = 2, **A** = \{1, 2, 3}, **B** = \{100, 200, 300, 400}, **M** = 2, **C** = \{7, 8}, the above format will produce: +- **N** = 2 +- **A** = \{1, 2, 3} +- **B** = \{100, 200, 300, 400} +- **M** = 2 +- **C** = \{7, 8} + ``` 2 1 2 3 100 200 300 400 2 7 8 ``` +
+ +--- #### `LINES()` @@ -198,7 +272,21 @@ where each variable is a vector or matrix. If the size is not given, this must be the last segment in the I/O format. -Example: +If a matrix variable is given, it must occur as the last argument, and the number of rows must match with the number of elements of the other vector variables (if any). It is not required that each row of the matrix consists of the same number of columns. + +**Examples** + + + + + + + + + + + + + + + -If a matrix variable is given, it must occur as the last argument, and the number of rows must match with the number of elements of the other vector variables (if any). It is not required that each row of the matrix consists of the same number of columns. - -Example: + + + + + + +
UsageVariablesFormat
```cpp void InputFormat() { @@ -207,8 +295,17 @@ void InputFormat() { LINES(Z); } ``` + + +- **V** = \{1, 2} +- **X** = \{100, 110, 120} +- **Y** = \{200, 210, 220} +- **N** = 3 +- **Z** = \{1, 2, 3, 4} -With **V** = \{1, 2}, **X** = \{100, 110, 120}, **Y** = \{200, 210, 220} **N** = 3, **Z** = \{1, 2, 3, 4} the above format will produce: + ``` 1 @@ -221,23 +318,35 @@ With **V** = \{1, 2}, **X** = \{100, 110, 120}, **Y** = \{200, 210, 220} **N** = 3 4 ``` +
```cpp void InputFormat() { LINES(op, data) % SIZE(2); } ``` + -With **op** = \{"UPDATE", "QUERY"}, **data** = \{{3, 5}, {7}}, the above format will produce: +- **op** = \{"UPDATE", "QUERY"} +- **data** = \{ \{3, 5}, \{7} } + ``` UPDATE 3 5 QUERY 7 ``` +
+ +--- #### `GRID()` @@ -251,9 +360,19 @@ Usage: - `GRID() % SIZE(, );` -where the variable is a matrix. +**Example** -Example: + + + + + + + + + + + + + + + +
UsageVariablesFormat
```cpp void InputFormat() { @@ -261,8 +380,15 @@ void InputFormat() { GRID(H) % SIZE(R, C); } ``` + -With **G** = \{\{'a', 'b'}, \{'c', 'd'}}, **H** = \{\{1, 2, 3}, \{4, 5, 6}}, **R** = 2, **C** = 3, the above format will produce: +- **R** = 2 +- **C** = 3 +- **G** = \{ \{'a', 'b'}, \{'c', 'd'} } +- **H** = \{ \{1, 2, 3}, \{4, 5, 6} } + ``` ab @@ -270,6 +396,12 @@ cd 1 2 3 4 5 6 ``` +
+ +--- ### `BeforeOutputFormat()` @@ -279,6 +411,7 @@ virtual void BeforeOutputFormat() {} Executed right before the produced output is validated against the output format(s). See [BeforeOutputFormat()](../topic-guides/io-formats#beforeoutputformat) for more details. +--- ## Problem style config @@ -290,6 +423,8 @@ virtual void StyleConfig() {} Defines the options to enable for problem styles. The following methods are exposed: +--- + #### `BatchEvaluator()` ```cpp @@ -324,9 +459,7 @@ Declares that the problem does not need test case output files. See [Problem styles](../topic-guides/styles) for more details. ---- - -Example: +**Example** ```cpp void StyleConfig() { @@ -335,6 +468,8 @@ void StyleConfig() { } ``` +--- + ## Constraints and subtasks ### `MultipleTestCasesConstraints()` @@ -345,6 +480,8 @@ virtual void MultipleTestCasesConstraints() {} Defines the constraints to be imposed to the multiple test cases counter. +--- + ### `Constraints()` ```cpp @@ -353,6 +490,8 @@ virtual void Constraints() {} Defines the constraints to be imposed to the [input/output variables](#inputoutput-variables). +--- + ### `SubtaskX()` ```cpp @@ -364,6 +503,8 @@ virtual void Subtask25() {} Defines the constraints to be imposed to the input/output variables for each subtask (up to 25). +--- + ### Definitions #### `CONS()` @@ -382,9 +523,7 @@ void Points(double points); Sets the points assigned to a subtask. If not specified, the default is 0. Only available in `SubtaskX()`s. ---- - -Examples: +**Examples** ```cpp void MultipleTestCasesConstraints() { @@ -408,6 +547,8 @@ void Subtask1() { } ``` +--- + ## Multiple test cases config ### `MultipleTestCasesConfig()` @@ -434,9 +575,7 @@ void OutputPrefix(std::string prefix); Sets the prefix to be prepended to the output of each test case. It can include ``%d``, which will be replaced by the actual test case number (1-based). ---- - -Example: +**Example** ``` cpp void MultipleTestCasesConfig() { @@ -445,6 +584,8 @@ void MultipleTestCasesConfig() { } ``` +--- + ## Grading config ### `GradingConfig()` @@ -455,6 +596,8 @@ virtual void GradingConfig() {} Defines the config for [local grading](../topic-guides/grading). The following methods are exposed: +--- + #### `TimeLimit()` ```cpp diff --git a/web/docs/api/02-test-spec.md b/web/docs/api/02-test-spec.md index 96c465d..fa1193e 100644 --- a/web/docs/api/02-test-spec.md +++ b/web/docs/api/02-test-spec.md @@ -12,6 +12,8 @@ class TestSpec : public BaseTestSpec {}; Except for private helper functions, every member of `TestSpec` listed below must be `protected`. +--- + ## Sample test cases ### `SampleTestCaseX()` @@ -25,6 +27,8 @@ virtual void SampleTestCase25() {} Defines the sample test cases (up to 25). The following methods are exposed: +--- + #### `Subtasks()` ```cpp void Subtasks(std::set subtaskNumbers); @@ -48,9 +52,7 @@ void Output(std::vector lines); Defines the input as exact literal string, given as list of lines. It is optional; if not specified, the solution will be run against the sample input to produce the corresponding sample output. ---- - -Example: +**Example** ```cpp void SampleTestCase1() { @@ -74,6 +76,8 @@ virtual void TestCases() {} Defines the test cases. +--- + ### `TestGroupX()` ```cpp virtual void TestGroup1() {} @@ -84,6 +88,8 @@ virtual void TestGroup25() {} Defines the test cases on each test group (up to 25). +--- + ### Definitions The following macro is exposed to define test cases: @@ -101,7 +107,7 @@ Each **statement** should be one of: - assignment to an input variables - private method call that assigns values to one or more input variables -Example: +**Example** ```cpp void TestCases() { @@ -111,6 +117,8 @@ void TestCases() { } ``` +--- + ## Test case lifecycle ### `BeforeTestCase()`, `AfterTestCase()` diff --git a/web/docs/api/03-rnd.md b/web/docs/api/03-rnd.md index 92cfd5e..b485d18 100644 --- a/web/docs/api/03-rnd.md +++ b/web/docs/api/03-rnd.md @@ -8,6 +8,8 @@ toc_max_heading_level: 4 `BaseTestSpec` exposes a random number generator object `rnd` that can be utilized to define test cases. The following methods are available on it: +--- + ### `nextInt(minNum, maxNum)` ```cpp