diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst index 7172f81eb7..39ac9c716b 100644 --- a/doc/src/Developer_utils.rst +++ b/doc/src/Developer_utils.rst @@ -21,18 +21,21 @@ In that case, the functions will stop with an error message, indicating the name of the problematic file, if possible unless the *error* argument is a NULL pointer. -The :cpp:func:`fgets_trunc` function will work similar for ``fgets()`` -but it will read in a whole line (i.e. until the end of line or end -of file), but store only as many characters as will fit into the buffer -including a final newline character and the terminating NULL byte. -If the line in the file is longer it will thus be truncated in the buffer. -This function is used by :cpp:func:`read_lines_from_file` to read individual -lines but make certain they follow the size constraints. +The :cpp:func:`utils::fgets_trunc() ` +function will work similar for ``fgets()`` but it will read in a whole +line (i.e. until the end of line or end of file), but store only as many +characters as will fit into the buffer including a final newline +character and the terminating NULL byte. If the line in the file is +longer it will thus be truncated in the buffer. This function is used +by :cpp:func:`utils::read_lines_from_file() +` to read individual lines but +make certain they follow the size constraints. -The :cpp:func:`read_lines_from_file` function will read the requested -number of lines of a maximum length into a buffer and will return 0 -if successful or 1 if not. It also guarantees that all lines are -terminated with a newline character and the entire buffer with a +The :cpp:func:`utils::read_lines_from_file() +` function will read the +requested number of lines of a maximum length into a buffer and will +return 0 if successful or 1 if not. It also guarantees that all lines +are terminated with a newline character and the entire buffer with a NULL character. ---------- @@ -62,7 +65,7 @@ silently returning the result of a partial conversion or zero in cases where the string is not a valid number. This behavior improves detecting typos or issues when processing input files. -Similarly the :cpp:func:`logical() ` function +Similarly the :cpp:func:`utils::logical() ` function will convert a string into a boolean and will only accept certain words. The *do_abort* flag should be set to ``true`` in case this function @@ -70,8 +73,8 @@ is called only on a single MPI rank, as that will then trigger the a call to ``Error::one()`` for errors instead of ``Error::all()`` and avoids a "hanging" calculation when run in parallel. -Please also see :cpp:func:`is_integer() ` -and :cpp:func:`is_double() ` for testing +Please also see :cpp:func:`utils::is_integer() ` +and :cpp:func:`utils::is_double() ` for testing strings for compliance without conversion. ---------- @@ -393,21 +396,26 @@ A typical code segment would look like this: ---------- +.. file-reader-classes: + File reader classes ------------------- The purpose of the file reader classes is to simplify the recurring task of reading and parsing files. They can use the -:cpp:class:`LAMMPS_NS::ValueTokenizer` class to process the read in -text. The :cpp:class:`LAMMPS_NS::TextFileReader` is a more general -version while :cpp:class:`LAMMPS_NS::PotentialFileReader` is specialized -to implement the behavior expected for looking up and reading/parsing -files with potential parameters in LAMMPS. The potential file reader -class requires a LAMMPS instance, requires to be run on MPI rank 0 only, -will use the :cpp:func:`LAMMPS_NS::utils::get_potential_file_path` -function to look up and open the file, and will call the -:cpp:class:`LAMMPS_NS::Error` class in case of failures to read or to -convert numbers, so that LAMMPS will be aborted. +:cpp:class:`ValueTokenizer ` class to process +the read in text. The :cpp:class:`TextFileReader +` is a more general version while +:cpp:class:`PotentialFileReader ` is +specialized to implement the behavior expected for looking up and +reading/parsing files with potential parameters in LAMMPS. The +potential file reader class requires a LAMMPS instance, requires to be +run on MPI rank 0 only, will use the +:cpp:func:`utils::get_potential_file_path +` function to look up and +open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in +case of failures to read or to convert numbers, so that LAMMPS will be +aborted. .. code-block:: C++ :caption: Use of PotentialFileReader class in pair style coul/streitz @@ -482,10 +490,10 @@ provided, as that is used to determine whether a new page of memory must be used. The :cpp:class:`MyPage ` class offers two ways to -reserve a chunk: 1) with :cpp:func:`get() ` the -chunk size needs to be known in advance, 2) with :cpp:func:`vget() +reserve a chunk: 1) with :cpp:func:`MyPage::get() ` the +chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget() ` a pointer to the next chunk is returned, but -its size is registered later with :cpp:func:`vgot() +its size is registered later with :cpp:func:`MyPage::vgot() `. .. code-block:: C++ @@ -588,4 +596,3 @@ the communication buffers. .. doxygenunion:: LAMMPS_NS::ubuf :project: progguide -