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

SYNOPSIS

#include <librock/astring.h>

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

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

DESCRIPTION

These string copying functions update *ppasz with a pointer to a buffer allocated by () which will contain a copy of the NUL-terminated string at pSrc. If librock_astrn0cpy() is used, at most the first n bytes of pSrc are copied, up to a NUL.

Note that librock_astrn0cpy() will not reserve more space, nor copy more bytes than strlen(pSrc) and the terminating character. Instead, you will want to use librock_astrensure() to reserve space to prepare for memcpy() or other modifying operations.

The NUL termination character is always stored by both functions. (NUL is ASCII 00, '\0', which is not to be confused with NULL, (void *) 0.)

These functions are part of the Librock allocated string functions. See () for an overview. Since the librock allocated string buffers hold NUL terminated strings, most "read-only" string functions of libc and other libraries, such as strlen(), strchr(), can be used.

As with all librock_astr* functions, the caller must assume the buffer will move, and consider all pointers into the old buffer *ppasz unusable. See the () implementation for a good way to use indexes to avoid pointers which go stale.

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_astrcpy

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

        librock_astrfree(&asz);
#endif

VARIANTS

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

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

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

USES

    strlen() strcpy() librock_astrensureX() // used by librock_astrcpyX
    realloc() librock_astrcpyX()            // used by librock_astrcpy

    memchr() memcpy() librock_astrensureX() // used by librock_astrn0cpyX
    librock_astrn0cpyX() realloc()          // used by librock_astrn0cpy

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

This software is part of Librock

• 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).

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.