diff options
Diffstat (limited to 'doc/string_ops.rst')
| -rw-r--r-- | doc/string_ops.rst | 74 |
1 files changed, 18 insertions, 56 deletions
diff --git a/doc/string_ops.rst b/doc/string_ops.rst index aea4896..ab7f19b 100644 --- a/doc/string_ops.rst +++ b/doc/string_ops.rst @@ -102,7 +102,6 @@ In-place transformations char *HX_chomp(char *s); size_t HX_strltrim(char *s); - char *HX_stpltrim(const char *s); char *HX_strlower(char *s); char *HX_strrev(char *s); size_t HX_strrtrim(char *s); @@ -117,9 +116,6 @@ In-place transformations on the left edge of the string. Returns the number of characters that were stripped. -``HX_stpltrim`` - Returns a pointer to the first non-whitespace character in ``s``. - ``HX_strlower`` Transforms all characters in the string ``s`` into lowercase using ``tolower``(3). Returns the original argument. @@ -184,18 +180,6 @@ Possible values for type: ``HXQUOTE_URIENC`` Escapes the string so that it becomes a valid part for an URI. -``HXQUOTE_SQLSQUOTE`` - Escapes all single quotes in the string by double single-quotes, as - required for using it in a single-quoted SQL string. No surrounding - quotes will be generated to facilitate concatenating of HX_strquote - results. - -``HXQUOTE_SQLBQUOTE`` - Escape all backticks in the string by double backticks, as required for - using it in a backtick-quoted SQL string (used for table names and - columns). No surrounding ticks will be generated to facilitate - concatenation. - .. _RFC 4514: http://tools.ietf.org/html/rfc4514 .. _RFC 4515: http://tools.ietf.org/html/rfc4515 .. _RFC 4648: http://tools.ietf.org/html/rfc4648 @@ -246,7 +230,6 @@ Tokenizing char **HX_split(const char *s, const char *delimiters, size_t *fields, int max); char **HX_split_inplace(char *s, const char *delimiters, int *fields, int max); int HX_split_fixed(char *s, const char *delimiters, int max, char **arr); - char *HX_strsep(char **sp, const char *delimiters); char *HX_strsep2(char **sp, const char *dstr); ``HX_split`` @@ -277,20 +260,15 @@ Tokenizing .. [#fixfoot] An implementation may however decide to put ``NULL`` in the unassigned fields, but this is implementation-dependent. -``HX_strsep`` - Extract tokens from a string. This implementation of strsep has been - added since the function is non-standard (according to the manpage, - conforms to BSD4.4 only) and may not be available on every operating - system. This function extracts tokens, separated by one of the - characters in ``delimiters``. The string is modified in-place and thus - must be mutable. The delimiters in the string are then overwritten with - ``'\0'``, ``*sp`` is advanced to the character after the delimiter, and - the original pointer is returned. After the final token, ``HX_strsep`` - will return ``NULL``. - ``HX_strsep2`` - Like ``HX_strsep``, but ``dstr`` is not an array of delimiting - characters, but an entire substring that acts as one delimiter. + strsep is a string tokenization function from BSD4.4; the POSIX + replacement is + + strsep(&string, delim) <=> + strtok_r(nullptr, delim, &string). + + Whereas strsep/strtok would split on any character in ``delim``, + our strsep2 splits only on the entire ``delim`` string. Size-bounded string operations @@ -303,7 +281,6 @@ Size-bounded string operations char *HX_strlcat(char *dest, const char *src, size_t length); char *HX_strlcpy(char *dest, const char *src, size_t length); char *HX_strlncat(char *dest, const char *src, size_t dlen, size_t slen); - size_t HX_strnlen(const char *src, size_t max); ``HX_strlcat`` and ``HX_strlcpy`` provide implementations of the BSD-originating ``strlcat``(3) and ``strlcpy``(3) functions. ``strlcat`` and @@ -312,10 +289,6 @@ they always take the length of the entire buffer specified by ``dest``, instead of just the length that is to be written. The functions guarantee that the buffer is ``'\0'``-terminated. -``HX_strnlen`` will return the length of the input string or the upper bound -given by ``max``, whichever is less. It will not attempt to access more than -this many bytes in the input buffer. - Allocation-related ================== @@ -462,7 +435,7 @@ Conversion from/to human-readable durations with units unsigned int flags); ``HX_strtoull_sec`` and ``HX_strtoull_nsec`` convert a time duration with -units, such as ``"15min30s"`` into an all-seconds and all-nanoseconds value, +units, such as ``15min30s`` into an all-seconds and all-nanoseconds value, respectively. The recognized unit strings are: ``years``, ``year``, ``y``, ``months``, ``month``, ``days``, ``day``, ``d``, ``hours``, ``hour``, ``h``, ``minutes``, ``minute``, ``min``, ``seconds``, ``second``, ``s``, the empty @@ -471,8 +444,15 @@ string (to mean seconds), ``msec``, ``ms``, ``µsec``, ``µs``, ``nsec`` and implementation-defined. When parsing stops at any point, ``*end`` is set to the location, similar to how the ``strtoull`` C function would. -One year is defined to be 365.25 days of 86400 seconds; one month is defined to -be 1/12 such a year. This is consistent with the units employed by systemd. +One day is defined as 86400 seconds. One year is defined to be 365.25 days of +86400 seconds. One month is defined to be 1/12 such a year (30.4375 days). This +is consistent with the units employed by systemd. + +In addition, HX_strtoull_sec recognizes the most common ISO 8601-style period +syntax, e.g. ``PT15M30S``. Time lengths are applied as mentioned above, so +``P1M`` is treated as 2629800 seconds, *not* as a "calendaric month" that would +expand to 28—31 days relative to some start date. There is no function offered +to return a ``struct tm``. ``HX_unit_seconds`` is the reverse and transforms the duration given by ``seconds`` into a string representation broken into days, hours, minutes, and @@ -555,21 +535,3 @@ full-fledged ``HX_split`` that allocates space for each substring. callme(line); HX_zvecfree(field); } - -Using HX_strsep ---------------- - -``HX_strsep`` provides for thread- and reentrant-safe tokenizing a string where -strtok from the C standard would otherwise fail. - -.. code-block:: c - - #include <stdio.h> - #include <libHX/string.h> - - char line[] = "root:x:0:0:root:/root:/bin/bash"; - char *wp, *p; - - wp = line; - while ((p = HX_strsep(&wp, ":")) != NULL) - printf("%s\n", p) |