Re: [PATCH v2 1/3] string: Add stpecpy()

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3908 bytes --]

stpecpy(3)                 Library Functions Manual                 stpecpy(3)

NAME
        stpecpy - copy a string with truncation

LIBRARY
        stp string library (libstp, pkgconf ‐‐cflags ‐‐libs libstp)

SYNOPSIS
        #include <stp/stpe/stpecpy.h>

        char *_Nullable stpecpy(char *_Nullable dst, char end[0],
                                const char *restrict src);

DESCRIPTION
        This function copies the string pointed to by src, into a string at the
        buffer  pointed  to  by  dst.   If the destination buffer, limited by a
        pointer to its end —one after its last element—, isn’t large enough  to
        hold the copy, the resulting string is truncated.

        This   function   can  be  chained  with  calls  to  stpeprintf(3)  and
        vstpeprintf(3).

        An implementation of this function might be

            /* This code is in the public domain. */

            char *
            stpecpy(char *dst, char end[0], const char *restrict src)
            {
                char *p;

                if (dst == end || dst == NULL)
                    return dst;

                p = memccpy(dst, src, '\0', end - dst);
                if (p != NULL)
                    return p - 1;

                /* truncation detected */
                end[-1] = '\0';
                return end;
            }

RETURN VALUE
        NULL   If dst was NULL.

        end
               •  If this call truncated.
               •  If dst was equal to end (a previous  call  to  this  function
                  truncated).

        dst + strlen(dst)
               On  success,  this function returns a pointer to the terminating
               null byte.

ATTRIBUTES
        For an explanation of the terms  used  in  this  section,  see  attrib‐
        utes(7).
        ┌────────────────────────────────────────────┬───────────────┬─────────┐
        │Interface                                   │ Attribute     │ Value   │
        ├────────────────────────────────────────────┼───────────────┼─────────┤
        │stpecpy(3)                                  │ Thread safety │ MT‐Safe │
        └────────────────────────────────────────────┴───────────────┴─────────┘

STANDARDS
        None.

EXAMPLES
        $ cc ./stpecpy.c $(pkgconf --cflags --libs libbsd-overlay libstp)
        $ ./a.out
        [len = 12]: Hello world!
        $

        // stpecpy.c
        #include <err.h>
        #include <stdio.h>
        #include <stdlib.h>

        #include <stp/stpe/stpecpy.h>
        #include <stp/stpe/stpeprintf.h>

        int
        main(void)
        {
            char    *p, *end;
            char    buf[BUFSIZ];
            size_t  len;

            end = buf + BUFSIZ;
            p = buf;
            p = stpecpy(p, end, "Hello, ");
            p = stpeprintf(p, end, "%d worlds", 22);
            p = stpecpy(p, end, "!");
            if (p == NULL)
                err(EXIT_FAILURE, "stpeprintf()");
            if (p == end) {
                p--;
                warnx("Truncated");
            }
            len = p - buf;
            printf("[len = %zu]: ", len);
            puts(buf);

            exit(EXIT_SUCCESS);
        }

SEE ALSO
        stpeprintf(3), string_copying(7)

libstp (unreleased)                 (date)                          stpecpy(3)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]