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/target/types.c>
#include <librock/astring.h>

char *
librock_astrensure(
    char * * ppasz,
    int len
);  /* (re)allocate space to store a NUL terminated string */

void
librock_astrfree(
    char * *ppasz
); /* deallocate space obtained using librock_astring functions */

char *
librock_astrstatic(
    char * * ppasz
); /* minimize space to store a NUL terminated string */

DESCRIPTION

For most uses, initialize a char pointer to 0, and then call librock_astrcpy() and others, making a final call to librock_astrfree() when finished. Be aware that the buffer will move around in memory. Callers should not keep stale pointers.

IMPORTANT: Calls to astring functions will run strlen(), so the caller must always ensure there is a '\0' string terminator at or before pasz+len.

librock_astrensure() is what librock_astrcpy and librock_astrcat (and others) use to allocate (or reallocate) a buffer of at least len+1 bytes for direct manipulation. librock_astrensure is suitable for external use also. The caller must not write beyond pasz[len] bytes. Callers which do no direct buffer manipulation (only use librock_astrcpy and others) do not need to call librock_astrensure().

librock_astrfree() deallocates the space and stores 0 at *ppasz; When using the standard realloc(), it is equivalent to a call to free(*ppasz) followed by *ppasz = 0.

librock_astrstatic() minimizes storage for the astring, and returns a pointer to the possibly moved string. AFTER THE CALL, THE POINTER IS NO LONGER AN ASTRING. Do not use it as an astring in any other calls. Be sure to call the appropriate deallocator directly, do not use astrfree().

The implementation of astrings "overallocates" to prevent unnecessary copying of "active" strings. This is fine for most astrings. Only if a large number of astrings are persistent ("long-lived") use astrstatic() to realloc exactly what is needed to store the string, for less memory waste.

The X suffix versions allow use of a specific memory allocator, instead of the library malloc. Read more below at "Variants"

RETURN VALUE: librock_astrensure() librock_astrstatic() return a pointer to the possibly moved buffer. The return value is also stored at *ppasz.

The caller must assume pointers into the old buffer are stale after calling these functions.

#ifdef librock_TYPICAL_USE_astrstatic
        char *asz =0; /* Important: initialize to 0 before first call*/
        char *ptr;

        librock_astrcpy(&asz,"Big buffer....");
        librock_astrcat(&asz,"Other big buffer....");
        printf("Length: %d\n",strlen(asz));
        librock_astrfree(&asz);
        /* . . . */
        librock_astrcat(&asz,"strcat to initialized = 0 is fine.");
        ptr = librock_astrstatic(&asz);  /* Sets asz = 0 */
        printf("Length: %d\n",strlen(ptr));
        free(ptr); /* Not librock_astrfree() here */
        /* . . . */
#endif

VARIANTS

char *librock_astrensureX(
                          char * * ppasz,
                          int len,
                          void *(*reallocfn)(void *,librock_SIZE_T));

void librock_astrfreeX(
                          char * *ppsz,
                          void *(*reallocfn)(void *,librock_SIZE_T));

char * librock_astrstaticX( char * * ppasz,
                          void *(*reallocfn)(void *,librock_SIZE_T));

USES

    librock_astrfreeX()
    realloc() librock_astrensureX() // used by librock_astrensure
    realloc() librock_astrfreeX()   // used by librock_astrfree
    realloc() librock_astrstaticX() // used by librock_astrstatic

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.