diff --git a/doc/src/pg_developer.rst b/doc/src/pg_developer.rst index f88576fa51..9ea30d599f 100644 --- a/doc/src/pg_developer.rst +++ b/doc/src/pg_developer.rst @@ -741,6 +741,8 @@ files additional settings and functions are needed: - the functions ``void pack_restart(int i, double *buf)`` and ``void unpack_restart(int nlocal, int nth)`` need to be implemented +--------------------------- + LAMMPS utility functions ======================== @@ -796,11 +798,85 @@ typos or issues when processing input files. :project: progguide -Convenience functions -^^^^^^^^^^^^^^^^^^^^^ +String processing functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following are functions to help with processing strings +and parsing files or arguments. + +.. doxygenfunction:: trim + :project: progguide + +.. doxygenfunction:: trim_comment + :project: progguide + +.. doxygenfunction:: count_words(const char *text) + :project: progguide + +.. doxygenfunction:: count_words(const std::string &text) + :project: progguide + +.. doxygenfunction:: count_words(const std::string &text, const std::string &separators) + :project: progguide + +.. doxygenfunction:: trim_and_count_words + :project: progguide + +.. doxygenfunction:: split_words + :project: progguide .. doxygenfunction:: strmatch :project: progguide +.. doxygenfunction:: is_integer + :project: progguide + +.. doxygenfunction:: is_double + :project: progguide + +Filename and path functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. doxygenfunction:: guesspath + :project: progguide + +.. doxygenfunction:: path_basename + :project: progguide + +.. doxygenfunction:: path_join + :project: progguide + +.. doxygenfunction:: file_is_readable + :project: progguide + +Potential file functions +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. doxygenfunction:: get_potential_file_path + :project: progguide + +.. doxygenfunction:: get_potential_date + :project: progguide + +.. doxygenfunction:: get_potential_units + :project: progguide + +.. doxygenfunction:: get_supported_conversions + :project: progguide + +.. doxygenfunction:: get_conversion_factor + :project: progguide + +Convenience functions +^^^^^^^^^^^^^^^^^^^^^ + +.. doxygenfunction:: logmesg + :project: progguide + +.. doxygenfunction:: getsyserror + :project: progguide + .. doxygenfunction:: check_packages_for_style :project: progguide + +.. doxygenfunction:: timespec2seconds + :project: progguide diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 81ff943ae9..cd68c3ddda 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -248,6 +248,7 @@ bispectrum Bispectrum bitbucket bitmapped +bitmask bitrate bitrates Bitzek @@ -302,6 +303,7 @@ Bryantsev Btarget btype buckPlusAttr +buf builtin Bulatov Bureekaew @@ -370,6 +372,7 @@ charmm CHARMM charmmfsh charmmfsw +charptr Chaudhuri checkbox checkmark @@ -845,6 +848,7 @@ Erhart erorate erose erotate +errno Ertas ervel Espanol @@ -903,6 +907,7 @@ Fc fcc fcm Fd +fd fdotr fdt Fehlberg @@ -927,6 +932,7 @@ ffplay fft fftbench fftw +fgets fhg Fi Fichthorn @@ -962,6 +968,7 @@ fmackay fmag fmass fmm +fmt fmx fmy fmz @@ -991,6 +998,7 @@ Fraige framerate Frauenheim Fraunhofer +fread Freitas Frenkel Friedrichs @@ -2256,6 +2264,8 @@ Particuology pastewka Pastewka pathangle +pathname +pathnames Patomtrans Pattnaik Pavese @@ -2855,8 +2865,12 @@ strcmp streitz Streitz Streiz +strerror strided strietz +strmatch +strncmp +strstr Stukowski Su subbox @@ -2999,6 +3013,7 @@ Tmin tmp tN Tobias +tokenizer tokyo tol toolchain diff --git a/src/utils.cpp b/src/utils.cpp index f841086673..e9058d4c2d 100644 --- a/src/utils.cpp +++ b/src/utils.cpp @@ -71,7 +71,7 @@ using namespace LAMMPS_NS; * This function is supposed to be a more safe, more specific and * simple to use API to find pattern matches. The purpose is to replace * uses of either strncmp() or strstr() in the code base to find - * substrings safely. With strncmp() finding prefixes, the number of + * sub-strings safely. With strncmp() finding prefixes, the number of * characters to match must be counted, which can lead to errors, * while using "^pattern" will do the same with less problems. * Matching for suffixes using strstr() is not as specific as 'pattern$', @@ -88,7 +88,7 @@ bool utils::strmatch(const std::string &text, const std::string &pattern) return (pos >= 0); } -/* This simplifies the repetitive task of outputting some +/** This function simplifies the repetitive task of outputting some * message to both the screen and/or the log file. In combination * with using fmt::format(), which returns the formatted text * in a std::string() instance, this can be used to reduce @@ -109,9 +109,11 @@ std::string utils::getsyserror() return std::string(strerror(errno)); } -/* - * On Linux the folder /proc/self/fd holds symbolic links to the actual +/** On Linux the folder /proc/self/fd holds symbolic links to the actual * pathnames associated with each open file descriptor of the current process. + * + * This function is used to provide a filename with error messages in functions + * where the filename is not passed as an argument, but the FILE * pointer. */ const char *utils::guesspath(char *buf, int len, FILE *fp) { diff --git a/src/utils.h b/src/utils.h index 4b9d3f7e81..4b1c68fb8e 100644 --- a/src/utils.h +++ b/src/utils.h @@ -150,14 +150,14 @@ namespace LAMMPS_NS { */ std::string trim(const std::string &line); - /** Trim anything from '#' onward + /** Return string with anything from '#' onward removed * * \param line string that should be trimmed * \return new string without comment (string) */ std::string trim_comment(const std::string &line); - /** Count words in string + /** Count words in string with custom choice of separating characters * * \param text string that should be searched * \param separators string containing characters that will be treated as whitespace @@ -189,11 +189,11 @@ namespace LAMMPS_NS { /** Take text and split into non-whitespace words. * - * This can handle single and double quotes, escaped quotes, - * and escaped codes within quotes, but due to using an STL - * container and STL strings is rather slow because of making - * copies. Designed for parsing command lines and similar text - * and not for time critical processing. Use a tokenizer for that. + * This can handle strings with single and double quotes, escaped quotes, + * and escaped codes within quotes, but due to using an STL container and + * STL strings is rather slow because of making copies. Designed for parsing + * command lines and similar text and not for time critical processing. + * Use a tokenizer class for that. * * \param text string that should be split * \return STL vector with the words @@ -220,7 +220,7 @@ namespace LAMMPS_NS { * * \param buf storage buffer for pathname. output will be truncated if not large enough * \param len size of storage buffer. output will be truncated to this length - 1 - * \param fp FILE pointer structe from STDIO library for which we want to detect the name + * \param fp FILE pointer struct from STDIO library for which we want to detect the name * \return pointer to the storage buffer, i.e. buf */ const char *guesspath(char *buf, int len, FILE *fp);