Reuse, not rework

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,...

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

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

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

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

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

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


librock_astrensure - (re)allocate space to store a NUL terminated string
librock_astrfree - deallocate space obtained using librock_astring functions
librock_astrstatic - minimize space to store a NUL terminated string
librock_astrensureX - (re)allocate space to store a NUL terminated string using specified allocator
librock_astrfreeX - deallocate space obtained using librock_astring functions using specified allocator
librock_astrstaticX - minimize space to store a NUL terminated string using specified allocator

#License - #Source code - #Example Use -


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

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

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

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


The librock_astring family of functions simplify the task of using unlimited size string buffers. Pass in a pointer to a pointer to a char, and buffers are allocated and reallocated as needed with a little extra space to cut down on needing to call realloc().

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.

Typical use:
#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_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 */
        /* . . . */
For instructive use of librock_astrensure(), see the implementation of librock_afgets.


These functions use the realloc function supplied when the astring implementation was compiled. Supply a realloc function on a per-call basis (useful for memory pooling, optimization, and more), by using the X suffix 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));


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


  Copyright 1998-2000 Forrest J. Cavalier III,
  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. Details
This page copyright (C) 2002-2004 Forrest J. Cavalier III, d-b-a Mib Software, Saylorsburg PA 18353, USA

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.