This page introduces common states, objects, and functions of the Testlib checker/interactor/validator, together with usage instructions and notes. Please read the contents of this page in full before reading the other pages.
Common States
| Result | Testlib Alias | Meaning |
|---|---|---|
| Ok | _ok | The answer is correct. |
| Wrong Answer | _wa | The answer is incorrect. |
| Presentation Error | _pe | The answer format is incorrect. Note that many OJs, including Codeforces, do not distinguish PE from WA. |
| Partially Correct | _pc(score) | The answer is partially correct. This is only for test points with partial scores, where score is a positive integer from (no points) to (possibly the maximum score). (quitf+_pc is only for compatibility with the old pascal-testlib; if you want to output a partial score, quitp1 is recommended.) |
| Fail | _fail | In a validator, this means that the input is invalid and does not pass validation. In a checker, this means an internal program error, incorrect standard output, or that the contestant's output is better than the standard output, requiring the judge/problem setter's attention. (In other words, the problem is broken.) |
This result is usually indicated by the program's return value, but there are also some other methods: creating an output XML file, outputting information to stdout or elsewhere, and so on. These are all completed through the quitf function in the function table below.
Common Objects
| Object | Meaning |
|---|---|
inf | Input file stream |
ouf | Contestant output stream |
ans | Reference output stream |
Common Functions
Non-member functions:
| Call | Meaning |
|---|---|
void registerTestlibCmd(int argc, char* argv[]) | Register the program as a checker |
void registerInteraction(int argc, char* argv[]) | Register the program as an interactor |
void registerValidation()/void registerValidation(int argc, char* argv[]) | Register the program as a validator |
void registerGen(int argc, char* argv[], int randomGeneratorVersion) | Register the program as a generatorrandomGeneratorVersion is recommended to be 1 |
void quit(TResult verdict, string message)/void quitf(TResult verdict, string message, ...) | End the program, return verdict, and output message |
void quitif(bool condition, TResult verdict, string message, ...) | If condition holds, call quitf(verdict, message, ...) |
void quitp(F points, string message, ...) | End the program and return a partial score. For most OJs (such as Luogu and UOJ), points must be a real number in representing the score percentage. For some OJs (such as Lyrio), points must be a real number in (the OJ automatically discards the fractional part), representing the test-point score on a percentage scale |
Stream member functions:
| Call | Meaning |
|---|---|
char readChar() | Read one character |
char readChar(char c) | Read one character, which must be c |
char readSpace() | Equivalent to readChar(' ') |
string readToken()/string readWord() | Read a string, stopping at a whitespace character (space, Tab, EOLN, and so on) |
string readToken(string regex)/string readWord(string regex) | Read a string, which must match regex |
long long readLong() | Read a 64-bit integer |
long long readLong(long long L, long long R) | Read a 64-bit integer, which must lie in |
vector<long long> readLongs(int n, long long L, long long R) | Read 64-bit integers, all of which must lie in |
int readInt()/int readInteger() | Read a 32-bit integer |
int readInt(int L, int R)/int readInteger(L, R) | Read a 32-bit integer, which must lie in |
vector<int> readInts(int n, int L, int R)/vector<int> readIntegers(int n, int L, int R) | Read 32-bit integers, all of which must lie in |
double readReal()/double readDouble() | Read a double-precision floating-point number |
double readReal(double L, double R)/double readDouble(double L, double R) | Read a double-precision floating-point number, which must lie in |
double readStrictReal(double L, double R, int minPrecision, int maxPrecision)/double readStrictDouble(double L, double R, int minPrecision, int maxPrecision) | Read a double-precision floating-point number, which must lie in , with a number of decimal places in , and without using a nonstandard format such as exponential notation |
string readString()/string readLine() | Read a line (including the newline character) and point the stream pointer to the beginning of the next line |
string readString(string regex)/string readLine(string regex) | Read a line, which must match regex |
void readEoln() | Read EOLN (read LF under Linux and CR LF under Windows) |
void readEof() | Read EOF |
void quit(TResult verdict, string message)/void quitf(TResult verdict, string message, ...) | End the program. If Stream is ouf, return verdict; otherwise, return _fail. Output message |
void quitif(bool condition, TResult verdict, string message, ...) | If condition holds, call quitf(verdict, message, ...) |
To be continued...
Minimal Regular Expressions
Some of the input functions above support the features of "minimal regular expressions", as follows:
- Character sets. For example,
[a-z]represents all lowercase English letters, and[^a-z]represents any character other than a lowercase English letter. - Ranges. For example,
[a-z]{1,5}represents a string with a length in the range containing only lowercase English letters. - The "or" operator. For example,
mike|johnrepresents eithermikeorjohn. - The "optional" operator. For example,
-?[1-9][0-9]{0,3}represents a nonzero integer in the range (note the optional minus sign). - The "repetition" operator. For example,
[0-9]*represents zero or more digits, while[0-9]+represents one or more digits. - Note that these regular expressions are "greedy" (a "repetition" matches as much as possible). For example,
[0-9]?1does not match1(because[0-9]?matches1, leaving the remaining1in the template string unmatched).
Include testlib.h First
Make sure that testlib.h is the first header file you include. Testlib rewrites/disables (through name collisions) some random-related functions, such as random(), to ensure that random results are independent of the environment. This is very important for a generator; the generator page explains this in detail.
Use Item Aliases
It is recommended to pass an additional string argument at the end of restricted calls such as readInt/readInteger/readLong/readDouble/readWord/readToken/readString/readLine. This argument is the alias of the item currently being read and makes error messages easier to understand. For example, use inf.readInt(1, 100, "n") rather than inf.readInt(1, 100). The error message will then be FAIL Integer parameter [name=n] equals to 0, violates the range [1, 100].
Use ensuref/ensure()
These two functions check whether a condition holds (similar to assert()). For example, to check , we can use
ensuref(x[i] != y[i], "Graph can't contain loops");
C-style placeholders can also be used, such as
ensuref(s.length() % 2 == 0,
"String 's' should have even length, but s.length()=%d",
int(s.length()));
There is also a simplified version, ensure(). We can directly use ensure(x> y) without adding explanatory content (adding explanatory content is not supported). If this condition is not satisfied, the error will be FAIL Condition failed: "x > y". In many cases, an error without additional explanation is not user-friendly, so we usually use ensuref() with an explanation rather than ensure().
Warning
Note the difference between global and member ensuref/ensure().
The global functions ::ensuref/ensure() are mostly used in generators and validators. If a check fails, they uniformly return _fail.
The member functions InStream::ensuref/ensure() are generally used to determine whether the output of the contestant and reference program is valid. When InStream is ouf, they return _wa; when it is inf (input data is generally not checked in a checker, which should be done in a validator) or ans, they return _fail. See Checker - Writing the readAns function for details.
This article was mainly rendered and compiled from the Testlib - Codeforces series. The GitHub repository for testlib.h is MikeMirzayanov/testlib.