librock_astrcat - (re)allocate a destination buffer and concatenate a NUL terminated string.

Home

License Awareness

Highly Reusable Software

By activity
Professions, Sciences, Humanities, Business, ...

User Interface
Text-based, GUI, Audio, Video, Keyboards, Mouse, Images,...

Text Strings
Conversions, tests, processing, manipulation,...

Math
Integer, Floating point, Matrix, Statistics, Boolean, ...

Processing
Algorithms, Memory, Process control, Debugging, ...

Stored Data
Data storage, Integrity, Encryption, Compression, ...

Communications
Networks, protocols, Interprocess, Remote, Client Server, ...

Hard World
Timing, Calendar and Clock, Audio, Video, Printer, Controls...

File System
Management, Filtering, File & Directory access, Viewers, ...

NAME

librock_astrcat - (re)allocate a destination buffer and concatenate a NUL terminated string.
librock_astrn0cat - (re)allocate buffer and concatenate a string with limit
librock_astrcatX - (re)allocate a destination buffer and concatenate a NUL terminated string using specified allocator
librock_astrn0catX - (re)allocate buffer and concatenate a string with limit using specified allocator

#License - #Source code - #Example Use -

SYNOPSIS

#include <librock/astring.h>

char *librock_astrcat(
    char * *ppasz,
    const char *pSrc
);

char *librock_astrn0cat(
    char * *ppasz,
    const char *pSrc,
    int n
);

DESCRIPTION

These are strcat() replacements which do automatic reallocation. Instead of a pointer to the destination buffer, these take a pointer to the pointer, so that the buffer can be reallocated if necessary to avoid overrun.

The return value (which is also stored at *ppasz) is a pointer to the possibly moved buffer, which will contain a copy of the NUL terminated string at pSrc appended, (or at most n bytes of pSrc if astrn0cat() is used.)

The NUL termination character is always stored by both functions.

n cannot be used to reserve more space, or append more bytes than strlen(pSrc) See librock_astrensure() for that need.

The point of concatenation is determined by strlen().

The caller must assume pointers into the old buffer are stale after calling these functions. See librock_afgets() implementation for a good way to use indexes and not pointers.

The allocation function, librock_astrensure(), makes realloc requests in multiples of a fixed size. The primary benefit of this strategy is to reduce realloc calls by assuming the buffer is at least a minimum size. For this and other reasons, be sure to call only with *ppasz set to 0 or a value obtained from a previous call to one of these functions.

Typical Use

#ifdef librock_TYPICAL_USE_astrcat
        char *asz = 0;
        librock_astrcpy(&asz,"Long buffer");
        librock_astrcat(&asz,"Longer buffer");
        printf("%s\n",asz);

        librock_astrfree(&asz);
#endif

VARIANTS

Supply a realloc function on a per-call basis (useful for memory pooling, optimization, and more), by using the X suffix variants:

#include <librock/target/types.c>
#include <librock/astring.h>

char *librock_astrcatX(
    char * *ppasz,
    const char *pSrc,
    void *(*reallocfn)(void *,librock_SIZE_T)
);

char *librock_astrn0catX(
    char * *ppasz,
    const char *pSrc,
    int n,
    void *(*reallocfn)(void *,librock_SIZE_T)
);

USES

    strlen() strcpy() librock_astrensureX() // used by librock_astrcatX
    librock_astrcatX() realloc().           // used by librock_astrcat
    strlen() memchr() memcpy() librock_astrensureX() // used by librock_astrn0catX
    librock_astrn0catX() and realloc()      // used by librock_astrn0cat

LICENSE

  Copyright 1998-2000 Forrest J. Cavalier III, http://www.mibsoftware.com
  Open-source under MIT license. NO WARRANTY. Copies must retain this block.
  License text in <librock/license/mit.txt> librock_LIDESC_HC=cc598307414a9997b32b60a2e7a8e7c6a13d6438

Source Code

./text/astring.c (implementation, plus source of this manual page)

This software is part of Librock

Rapid reuse, without rework.

Source code which is Open-source, Free (Libre) and free (no cost)
Namespace limited. All compile-time macros and names visible at link time are prefixed by "librock_". Integrate into your project and expect no name collisions.
Stable API means new functions get new names so that there is no risk that updating a source file will break existing applications.
Highly portable, cross-platform, and multithread compatible. Works with many machines, compilers, and operating systems (gcc/MSVC/Windows/Linux/BSD).

Details

Verbatim copying and distribution of this generated page is permitted in any medium provided that no changes are made.
(The source of this manual page may be covered by a more permissive license which allows modifications.)

Want to help? We welcome comments, patches. -- Need help? Request paid support.