Types and functions described below will be available in a program if pt4.c or pt4.cpp file is included (any template project created for task solving on C or C++ includes this file). Declarations of types and functions are contained in the pt4.h header file.

When compiling programs in C, the C99 standard is used, when compiling programs in C++, the C++14 standard is used.

In the version 4.23 of the taskbook, the set of additional functions for the C++ language was significantly revised and supplemented due to the implementation of C language support in this version. The absence of function overloading in the C language required the introduction of a set of various functions for the input data, output results and output debugging information. Due to the complexity of the standard functions of the C language designed to convert data of various types into their string representations, an extended set of functions has been developed for the output of debugging information, which allows you to output formatted data of various types in the most visual form in the debug panel.

All the additional functions of the taskbook implemented for the C language are also available for the C++ language. The C++ language also provides a set of additional functions and operations that make it easier, compared to the C language, to input data, output results and output debugging information.

Most of the auxiliary functions for C++ defined in version 4.23 are also available for previous versions of the taskbook, but some functions in version 4.23 have had their parameter set changed or their behavior slightly changed. For this reason, in the section devoted to the C++ language, the page with descriptions of additional types and functions corresponding to version 4.22 is preserved.

Basic set of functions (C and C++ languages)

Task initialization, data input-output


void Task(const char* name);

This function initializes a task named name. It must be called at the beginning of the Solve function that contains the task solution. If the Solve function does not contain the Task function call, then the program displays the error message "The Task procedure with a task name is not called".

A task name must contain a name of a task group and an order number (for example, "Begin3"). If the group name is invalid, then the program displays the error message "Invalid task group". If the task number is invalid, then the program displays the error message with information about the range of the available task numbers for this group. The symbol "?" placed after the task name (for example, "Begin3?") means that the program will be run in the demo mode.

Starting from the version 4.8, the Task function may be also used for creating and displaying an html-page containing a description of a task or a task group. In this case, the name of the required task or the task group ended by the "#" symbol must be used for the name parameter, for example, "Begin3#" or "Begin#".

Starting from the version 4.13, the Programming Taskbook provides a program testing on several sets of input data during a single running of the program. You should place the sumbol "!" after the task name (for example, "Begin3!") in order to switch off this new feature.

All subsequent calls of the Task function are ignored with the following exception: if several calls are used for creation of an html-page containing a description of various tasks or task groups, then all these calls will be taken into account.

Starting from the version 4.12, the name parameter may include the "_en" or "_ru" suffix that determines the interface language (English or Russian respectively) for Programming Taskbook window and the task itself. The "?", "#", and "!" symbols should be placed before or after the suffix, for example, "Begin3#_en". If several calls of the Task function are used (for creation of an html-page) then only the suffix of the first call will be taken into account. If the suffix is absent, then the default language is applied (the default language may be changed by means of a pop-up menu of the PT4Load tool).


void GetB(bool *a);
void GetN(int *a);
void GetD(double *a);
void GetC(char *a);
void GetS(char *a);
void GetP(PNode *a);

These functions must be used to input initial data values in the program. They must be called after the Task function, otherwise the program displays the error message "The Task procedure with a task name is not called at the beginning of the program".

Each input function must correspond to the type of data item, otherwise the program displays the following message: "Invalid type is used for an input data item" . For example, this message will be output if GetN function will be called for input a string.

In the case of input of more data than the task requires, the program displays the error message "An attempt to input superfluous data". In the case of input of less data than the task requires, the program displays the error message "Some required data are not input".

In previous versions of the taskbook, references were used as parameters in similar input functions for the C++ language. The change in the type of parameters from references to pointers is due to the fact that there is no concept of references in the C language, and output parameters can only be represented as pointers.

It should also be taken into account that, despite the same type of parameters of the GetC and GetS functions, the data associated with them are different. The parameter of the GetC function is the address of the character variable into which the input character is written, whereas the parameter of the GetS function must contain the address of the beginning of the char[] character array into which the input string will be written. It is sufficient to specify 80 as the size of a character array, since the length of any input string data does not exceed 79 characters.

The PNode type is used in tasks related to dynamic data structures, and is described further in the section "Dynamic structures processing".

Remark. The logical data type bool is available in the C language of the C99 standard when the header file stdbool.h is connected to the program. When compiling learning programs in C, the compiler option setting the C99 standard is used; in addition, the header file pt4.h, connected to the program, contains the #include <stdio.h> directive, which allows you to use both the bool type and the logical constants true and false in the program.


void PutB(bool a);
void PutN(int a);
void PutD(double a);
void PutC(char a);
void PutS(const char *a);
void PutP(PNode a);

These functions must be used to output results on the screen and compare obtained results with control data (i.e., correct results). They must be called after the Task function, otherwise the program displays the error message "The Task procedure with a task name is not called at the beginning of the program".

Unlike the Get-functions, parameters of the Put-functions can be expressions (in particular, constants of a corresponding type). The used function should correspond to output data item, otherwise the program displays the error message "Invalid type is used for an output data item".

In the case of output of more data than the task requires, the program displays the error message "An attempt to output superfluous data". In the case of output of less data than the task requires, the program displays the error message "Some data are not output".

Regarding the use of the type bool in C language functions, see the remark at the end of the description of the Get functions. The parameter of the PutS function must be a character array ending with the null character '\0'.

Dynamic structures processing

C language

struct Node;

struct Node
{
  int Data;
  struct Node *Next;
  struct Node *Prev;
  struct Node *Left;
  struct Node *Right;
  struct Node *Parent;
};

typedef struct Node TNode;
typedef struct Node *PNode;

C++ language

struct Node
{
    int Data;
    Node *Next;
    Node *Prev;
    Node *Left;
    Node *Right;
    Node *Parent;
    static void operator delete(void *p);
};

typedef Node TNode;
typedef Node *PNode;

PNode and TNode types are used in the Dynamic and Tree group tasks. In the introductory tasks of the Dynamic group (Dynamic1–Dynamic2) and in the tasks devoted to stacks and queues (Dynamic3–Dynamic28), the Data and Next fields of the TNode structure are used. In the tasks devoted to lists (Dynamic29–Dynamic80), all fields (Data, Next, Prev) of TNode structure are used. In the most tasks devoted to binary trees, the Data, Left, and Right fields of the TNode structure are used. The Parent field is used in the tasks devoted to doubly linked binary trees (Tree48–Tree56 and Tree70–Tree71).

In the tasks, all given and resulting pointers have PNode type. They must be input and output by GetP and PutP functions respectively (or additional input tools provided for the C++ language and described below).


void DeleteNode(TNode* p);

This function provides freeing the memory allocated for a structure of TNode type (see the TNode description above). It must be used in the tasks of the Dynamic and Tree groups. For the C++ language, you may use the C++ delete operator instead the DeleteNode function.

Output debug info

Functions described below are intended to output some debug data into the debug panel located below the task panels of the Programming Taskbook window.

Since version 4.22, the debug panel can contain text data with any Unicode characters.


void ShowB(bool b);
void ShowN(int n);
void ShowD(double d);
void ShowC(char c);
void ShowS(const char *s);

void ShowLineB(bool b);
void ShowLineN(int n);
void ShowLineD(double d);
void ShowLineC(char c);
void ShowLineS(const char *s);

Displays a data item of the specified type in the debug panel of the taskbook window. Functions starting with ShowLine additionally break the current screen line in the debug panel after displaying the specified data item.

The ShowB function outputs the text false for the false parameter b and the text true for the true parameter; after the text true a space is added, so that any logical constant occupies exactly 5 screen positions (regarding the use of the type bool in C language functions, see the remark at the end of the description of the Get functions).

When the symbol is output by the ShowC function, it is enclosed in single quotes, when the string is output by the ShowS function, the string is enclosed in double quotes. Both characters and strings must have ASCII encoding or (for Russian letters) single-byte ANSI Windows-1251 encoding.

Characters with codes 0 and 10 are processed in a special way when outputting characters. For a character with code 0, the text '\0' is output, for a character with code 10, the text '\n' is output. In addition, character code 10 is interpreted in a special way when displaying strings with the ShowS function: it does not lead to line breaking in the debug panel, but is replaced by a combination of two characters \n, such as "Line ending with end-of-line marker\n".


void Show(const char *cmt);
void ShowW(const wchar_t *cmt);

void ShowLine(const char *cmt);
void ShowLineW(const wchar_t *cmt);

The Show and ShowW functions output a string comment, which is usually specified before one or more debugging data items are output. Unlike usual string data (output by the ShowS function), comments are not enclosed in double quotes. The ShowLine and ShowLineW functions additionally break the current screen line in the debug panel after the specified comment is output.

You can also switch to a new screen line by specifying a character with code 10 ('\n') in the cmt comment. Thus, the way this character is handled in the cmt comment differs from the way it is handled in the string and character data output of the ShowS and ShowC functions (which output the \n text).

When a comment is output, all trailing spaces are automatically removed (recall that when a subsequent data item is output in the debug section, a space is automatically added before it). If the removal of spaces makes the comment blank, it is not output, and no space is added between it and the subsequent data item.

The Show and ShowLine functions allow you to output comments containing (like ShowC and ShowS functions) ASCII characters or Russian letters in the one-byte ANSI code Windows-1251. This function should be used in editors of integrated environments that do not support UTF-8 encoding, for example, Dev-C++ 5.11.

The ShowW and ShowLineW functions allow you to output comments containing any Unicode characters; for this purpose, they must be represented as wchar_t* strings (constants of such strings are prefixed with L, for example, L"Example of comment"). If the editor of the integrated environment supports UTF-8 encoding (such are the editors of most modern development environments), all comments containing characters other than ASCII characters, including Russian letters, should be represented as wchar_t* strings and output using the ShowW or ShowLineW functions.


void HideTask(void);

The HideTask function hides all panels of the Programming Taskbook window with the exception of the debug panel (and therefore increases the debug panel height). If the debug panel contains no data, then the call of the HideTask function is ignored. All subsequent calls of this function are ignored too.

After displaying the Programming Taskbook window you can hide/restore task panels of this window by means of the [Ctrl]+[Space] hot key or the command of the pop-up menu.


void SetPrecision(int n);

The function defines the output format of real numbers in the debug panel. If the parameter n is positive, then this parameter defines the amount of fractional digits and a number is output in the fixed-point numeric format. If the parameter n is negative or is equal to 0, then a number is output in the exponential numeric format with the amount of fractional digits that is equal to the absolute value of n (if n = 0, then the amount of fractional digits has the default value 6).

Before the first call of the SetPrecision function, real numbers are output in the fixed-point format with 2 fractional digits.

If the value of parameter n is greater than 16 or less than -16, the function call is ignored.


void SetWidth(int n);

The SetWidth function is intended to adjust the width n of the debug data output field. The field width affects all subsequent output data items until the next call of the SetWidth function with a different parameter. By default, the width of the output field is assumed to be 0, which ensures the output of any data item in the field that is minimally necessary for its display.

If the actual width of the output data item is less than the current value of the output field width, then numeric data (int and double) are padded with spaces on the left, and other data (bool, char and char*) are padded with spaces on the right. If the width of the output item is greater than the current value of the output field width, then the output field of the minimum required width sufficient to display the output item is used.

The function does not affect the comments (output by the Show, ShowW, ShowLine, ShowLineW functions), for which the output field of the minimum required width is always used.

If the value of parameter n is less than zero or greater than 100, then the call of this functions is ignored.

Conversion of encodings


void RuAnsi(char *result, const wchar_t *source);

This function solves the problem related to character data encoding mismatch. This problem occurs when using a code editor which supports UTF-8 encoding (for example, the VS Code editor). Any string constants containing characters other than ASCII characters should be formatted in this editor as "wide" string literals (of type wchar_t*) with the prefix L, for example, L"String of type wchar_t*". This does not prevent their output in the debug panel (because a special ShowWCmt function is intended for this purpose), but does not allow them to be used when generating output text data containing Russian letters (since input and output functions work with single-byte strings of type char*). Therefore, if you want to use string constants with Russian letters for transforming given string data, you must first convert these constants (of type wchar_t*) to single-byte ANSI Windows-1251 encoding using the RuAnsi function.

The given "wide" string of type wchar_t* is passed to the RuAnsi function as the source parameter, the converted string of type char* is returned in the result parameter. If the converted constants contain Unicode characters other than Russian letters and characters from the ASCII set, then these characters are replaced with question marks "?".

Before calling the RuAnsi function, it is necessary to allocate sufficient memory for the result parameter to store the converted string. For example, you can use a wcslen(source) + 1 character array as a result parameter.

The need to use the RuAnsi function arises only when solving tasks that require processing text data in Russian and only in code editors that support UTF-8 encoding.

Additional set of functions and classes (C++ language)

Data input-output


void GetS(std::string &a);
void PutS(std::string a);

For the C++ language, overloaded functions for input and output of string data have been added to the basic set of input-output functions, which use the type std::string which is not present in the C language. It should be noted that the variant of the GetS function for the type string is not a pointer, but a reference to a string parameter; thus, calling this variant, like the initial variant for the char* parameter, does not require the & operator: GetS(a).


bool GetBool();
int GetInt();
double GetDouble();
char GetChar();
std::string GetString();
PNode GetNode();

For the C++ language, input functions have also been added that allow you to get an element of the input data in the form of the return value of the function itself (this approach is implemented in many modern programming languages). These functions appeared in the version 4.22 of the taskbook; they are convenient to use in a situation when it is enough to pass the value of an element of the input data to the constructor of an object or to a function. In addition, they allow you to combine the description and initialization of variables associated with the input data.


Input-output stream pt

A special input-output stream called pt may be used for input-output operations instead of Get and Put functions. For instance, function calls GetN(&n); GetD(&d); GetS(s); may be replaced by one stream-read statement as follows: pt >> n >> d >> s;.

In version 4.22, the capabilities of the pt output stream have been significantly extended. Variables of the pair type and any container type can now be specified as output data for the pt stream, and the container items can be data of scalar types, pair types, and container types. Components of the pair type can also have any scalar type, pair type, and container type.


Input iterator ptin_iterator<T>
Output iterator ptout_iterator<T>

Since version 4.15, specialized iterators ptin_iterator<T> and ptout_iterator<T> can be used for input and output items of sequences of type T, respectively. These iterators have the same properties as the standard stream iterators istream_iterator<T> and ostream_iterator<T>.

Let us list the properties of the ptin_iterator iterator that coincide with those of the stream iterators:

type T defines the type of sequence elements;
the reading of an element of the sequence from the pt stream is performed at the initial moment of working with the iterator, and then at each increment operation ++;
there are two variants of the ++ operation: prefix increment (++i) and postfix increment (i++);
the * operation returns the last read value; this operation can be used repeatedly to get the same value;
the end-of-sequence iterator is created using the constructor without parameters;
when reaching the end of the sequence, the iterator becomes equal to the end-of-sequence iterator, the subsequent calls of the increment operation are ignored, and the value of the last read element of the sequence is always returned as a result of calling the * operation.

Now let us list ptout_iterator properties that coincide with the similar properties of stream iterators:

there is no special constructor for creating the end-of-sequence iterator;
* and ++ operations do not perform any actions and just return the iterator itself;
the assignment operation of the form o = expression (where o is the name of the ptout_iterator variable) writes the value of the expression to the pt stream.

Unlike the standard istream_iterator iterator, the constructor for ptin_iterator (except for the end-of-sequence iterator constructor) has one parameter of type int that defines the size of the sequence to be read (in elements). In case of a special parameter value equal to 0, the size of the sequence is read from the pt stream itself just before the first element of the sequence is read. If, when reading the size, it turns out that the data element read is not an integer or the number is not positive, the iterator immediately goes to the end of the sequence (i. e., it becomes equal to the iterator ptin_iterator<T>()).

This way of organizing ptin_iterator<T> iterators makes it easy to implement reading multiple sequences from the pt input stream if their size is known beforehand or if the size is specified just before the start of the sequence.

As an example of using iterators from the pt stream for input and output, consider the Array7 task, where we need to input an array of real numbers of a specified size and then output its elements in reverse order (note the use of standard header files <vector> and <algorithm>; the vector container is used to store the array):

#include "pt4.h"
#include <vector>
#include <algorithm>
using namespace std;

void Solve()
{
    Task("Array7");
    vector<double> a(ptin_iterator<double>(0), ptin_iterator<double>());
    copy(a.rbegin(), a.rend(), ptout_iterator<double>());
}

Output debug info


void ShowS(std::string s)
void ShowW(std::wstring cmt)
void Show(std::string cmt)
void Show(std::wstring cmt)

void ShowLineS(std::string s)
void ShowLineW(std::wstring cmt)
void ShowLine(std::string cmt)
void ShowLine(std::wstring cmt)

void ShowLine(void)

For the C++ language, overloaded functions have been added to the basic set of debugging output functions for the output of logical data, string data and comments, which use bool, string and wstring types that are not present in the C language. In addition, the ShowLine() function without parameters is added, which breaks the current screen line in the debug panel.

Note that all overloaded versions of Show and ShowLine functions with a single string parameter provide output of a comment (as in the version for C). In particular, such strings are not enclosed in double quotes, all their trailing spaces are automatically removed, and the '\n' character breaks the current screen line.


void Show([string type cmt,] bool a[, int w]);
void Show([string type cmt,] int a[, int w]);
void Show([string type cmt,] double a[, int w]);
void Show([string type cmt,] char a[, int w]);
void Show(string type cmt, const char *a[, int w]);
void Show(string type cmt, std::string a[, int w]);
void ShowLine([string type cmt,] bool a[, int w]);
void ShowLine([string type cmt,] int a[, int w]);
void ShowLine([string type cmt,] double a[, int w]);
void ShowLine([string type cmt,] char a[, int w]);
void ShowLine(string type cmt, const char *a[, int w]);
void ShowLine(string type cmt, std::string a[, int w]);

A set of overloaded Show and ShowLine functions that allows you to output one data item a (of boolean, integer, real, character or string type) to the debug panel, as well as provide it with an optional string comment cmt and set the (optional) width w of the output field. If the w parameter is not specified, the width previously set using the SetWidth function is used. A cmt comment may have any of the following four string types: const char*, std::string, const wchar_t*, std::wstring. Overloaded versions of the ShowLine function additionally perform a line breaking in the debug panel after the output of the required data item.

Note that in overloaded versions for debugging output of string data (const char* and std::string types), the first cmt comment parameter is mandatory. This is necessary to avoid conflicts with Show and ShowLine versions that have one string parameter (which is interpreted as a comment) or two parameters - string and integer (which are interpreted as a comment and an integer type data item). For debugging output of string data without additional comment, use either ShowS and ShowLineS functions or versions of Show and ShowLine functions with two or three parameters, the first of which is an empty comment "".


template<typename T1, typename T2>
  void Show([string type cmt,] pair<T1, T2> &a)
template<typename T1, typename T2>
  void ShowLine([string type cmt,] pair<T1, T2> &a)

Variants of the Show and ShowLine functions that allow you to output data of type pair<T1, T2> to the debug panel. The bool, int, double, char, char* and string types can be used as T1 and T2 types, as well as type pair<T1, T2> (the depth of embedding of pair types can be arbitrary) and containers vector, deque, list, set, multiset, map, multimap with data of the specified types.

Before the output of the first element of the pair, an optional string comment cmt is output (of type const char*, std::string, const wchar_t* or std::wstring) as well as an opening parenthesis; a comma is output between the elements of the pair; a closing parenthesis is output after the output of the second element. When output all data (except comments, parentheses and commas), the width of the output field is used, which is set at the last call of the SetWidth function. For example, a data item of type pair<int, pair<int, int>> with values 5, 2 and 9 and the comment "p =" will be output as follows (provided that the current width of the output field is 0 or 1):

p = ( 5 , ( 2 , 9 ) )


template<typename InIter>
  void Show(InIter first, InIter last[, string type cmt])
template<typename InIter>
  void ShowLine(InIter first, InIter last[, string type cmt])

Variants of the Show and ShowLine functions that allow you to output sequence of elements to the debug panel using the first and last input iterators associated with this sequence. Sequence elements can be of type bool, int, double, char, char* and string, as well as pair<T1, T2> (the depth of embedding of pair types can be arbitrary); in addition, the elements themselves (or components of a pair) can be containers vector, deque, list, set, multiset, map, multimap. The optional string parameter cmt (of type const char*, std::string, const wchar_t* or std::wstring) allows you to specify a string comment that is displayed before the output sequence.

The Show function outputs the sequence elements on one line, separating them with spaces; after the output of the sequence elements is completed, the line break is automatically added. The ShowLine function outputs each element of the sequence on a new line; a string comment, if specified, is also output on a separate line.

In particular, these variants of the Show functions can be used to output elements of an array a of size n, for example:

double a[5] = {1, 2, 3};
Show(a, a + 5);

The following information will be displayed in the debug panel:

  1>  1.00 2.00 3.00 0.00 0.00

Here is also an example of debugging output of a two-dimensional vector (pay attention to using the ShowLine function and setting the width of the output field using the SetWidth function):

vector<vector<int>> v(10);
for (int i = 0; i < (int)v.size(); ++i)
    for (int j = 0; j < 10; ++j)
        v[i].push_back((i + 1) * (j + 1));
SetWidth(3);
ShowLine(v.begin(), v.end());

Contents of the debug panel:

  1>    1   2   3   4   5   6   7   8   9  10
  2>    2   4   6   8  10  12  14  16  18  20
  3>    3   6   9  12  15  18  21  24  27  30
  4>    4   8  12  16  20  24  28  32  36  40
  5>    5  10  15  20  25  30  35  40  45  50
  6>    6  12  18  24  30  36  42  48  54  60
  7>    7  14  21  28  35  42  49  56  63  70
  8>    8  16  24  32  40  48  56  64  72  80
  9>    9  18  27  36  45  54  63  72  81  90
 10>   10  20  30  40  50  60  70  80  90 100

Remark. These versions of functions can be used, in particular, to output text strings; however, the characters of the output string will be enclosed in single quotes and separated by a space (when using the Show function) or output on separate lines (when using the ShowLine function). Here are examples of output of the string s containing the text "Test":

std::string s("Test");
ShowLine("Example 1:", s);
Show(s.begin(), s.end(), "Example 2:");
ShowLine(s.begin(), s.end(), "Example 3:");

As a result of performing these statements, the following text will be output in the debug panel:

  1>  Example 1: "Test"
  2>  Example 2: 'T' 'e' 's' 't'
  3>  Example 3:
  4>  'T'
  5>  'e'
  6>  's'
  7>  't'

Conversion of encodings


std::string RuAnsi(const wchar_t *source);
std::string RuAnsi(std::wstring source);

There are more convenient versions of the previously described RuAnsi function, which allow you to get a resulting string as the return value of the function itself. As an example of using the RuAnsi function, we will give a fragment of the program from the previous remark, in which both the comments and the source line contain Russian letters (note that it is not necessary to encode the text of the comments):

std::string s(RuAnsi(L"Тест"));
ShowLine(L"Пример 1:", s);
Show(s.begin(), s.end(), L"Пример 2:");
ShowLine(s.begin(), s.end(), L"Пример 3:");

Contents of the debug panel:

  1>  Пример 1: "Тест"
  2>  Пример 2: 'Т' 'е' 'с' 'т'
  3>  Пример 3:
  4>  'Т'
  5>  'е'
  6>  'с'
  7>  'т'


void ForceUnicode(void);

An auxiliary function intended for programs that were developed in one of the editors that support UTF-8 encoding and then run in Visual Studio environment. The editor of this environment has a number of peculiarities that should be taken into account if strings containing Russian text or Unicode characters are used in programs.

In the program template created for Visual Studio, the ANSI-encoding is used by default, so there is no need to use the RuAnsi finction or wide strings. But when Unicode characters are added to the program text, it is converted into UTF-8 (the corresponding message is displayed beforehand). After such conversion, it is necessary to apply the RuAnsi function and wide strings for correct processing the Russian text.

Converted to UTF-8 encoding, the program will be saved by Visual Studio editor in a file with corresponding byte order mark (BOM). This does not prevent the program from being loaded in other environments with editors supporting UTF-8 (such as Code::Blocks, Dev-C++ 6.30, Visual Studio Code). But UTF-8-encoded program developed in another editor (for example, Visual Studio Code) may not contain BOM. In this case, if this program is loaded into Visual Studio environment, Unicode characters (including Russian letters) will be displayed correctly in the Visual Studio editor, but the debugging panel will display the wrong encoding. To solve this problem, you should call the ForceUnicode function at the beginning of the Solve function.

In versions of the pt4.cpp library not associated with the Visual Studio environment, the ForceUnicode function does not perform any action.

Getting the executable file name


std::string GetExename();

Returns the full name of the executable file which is a result of compiling the learning program. This auxiliary function can be used when performing tasks from an electronic problem book on parallel programming based on MPI-2 related to the creation of processes.

Last revised:
01.01.2024