ztring.c

Go to the documentation of this file.

/* ztring.c (C) 2014 adolfo@di-mare.com */

/** \file   ztring.c
    \brief  Implementation for <ztring.h>
    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2014
*/

#include "ztring.h"

#ifdef __cplusplus
    #include <cassert>   // assert()
#else
    #include <assert.h>  /* assert() */
#endif

/** Copies up to 'size' characters from 'src' to 'dest'.

    This is a 'size' checked versions of 'strcpy()'. The 'dest' memory block
    will always be a null terminated C string (unless 'size' is zero or
    'dest' is NULL).

    Stops copying when the end of the source C string is found (which is
    signaled by a null-character), even if less than 'size' characters have
    been copied (but 'dest' is not padded with zeros).

    A null-character is implicitly appended at the end of 'dest' if the
    length of the 'src' C string is 'size' or bigger; in this case, only a
    portion of the leading characters from 'src' get copied into 'dest'.

    'dest' and 'src' shall not overlap (see 'memmove()' for a safer
    alternative when overlapping).

    \see http://www.drdobbs.com/managed-string-library-for-c/184402023
    \see http://en.wikipedia.org/wiki/C_string_handling

    \remark An alternative to this function is 'strlcpy()': when the size of
    'dest' is not big enough, invoking 'strlcpy()' will return the minimun
    size that 'dest' should have to fit every character from 'src'.
    \see http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy

    \remarks Note the differences between this function and strncpy():
     - strncpy() doesn't always NUL terminate; ztrcpy() does.
     - strncpy() pads the destination string with NULs, which is often
       unnecessary; ztrcpy() does not.
     - zstrcpy() returns a pointer to the destination 'dest' string;
       this is the same behaviour of both strcpy() and strncpy().

    \param size Size of the 'dest' memory block.
    \param dest Pointer to the destination array where the content is to be copied.
    \param src  C string to be copied.
    \returns 'dest' is returned.

    \test_example{ztrcpy}
    \test_example{BeUNsafe::SZ}
*/
char* ztrcpy( size_t size, char * dest, const char * src ) {
    if ( dest==NULL || size==0 ) { return dest; }
    else if ( size==1 ) { *dest=0; return dest; }
    else {
        char *copy = dest;
        size_t len = 0;
        --size;
        while ( len<size ) {
            if ( 0 == (*copy = *src) ) { break; }
            ++copy; ++src; ++len;
        }
        *copy = 0;
        return dest;
    }
}

/** Append characters to a string.

    This is a 'size' checked versions of 'strcat()'. The 'dest' memory block
    will always be a null terminated C string (unless 'size' is zero or
    'dest' is NULL in which case no characters would be appended).

    If appending all characters from 'src' would result in a string with
    'size' or more characters, a null-character is implicitly appended to
    'dest' to ensure that its length is less than 'size'; in this case, only
    a portion of the leading characters from 'src' would be appended.

    \see  http://www.openbsd.org/cgi-bin/man.cgi?query=strlcat
    \see  http://en.wikipedia.org/wiki/C_string_handling

    \param size Size of the 'dest' memory block.
    \param dest Pointer to the destination array of 'size' characters.
    \param src  C string to be appended.

    \returns 'dest' is returned.
    \test_example{ztrcat}
    \test_example{BeUNsafe::SZ}
*/
char* ztrcat( size_t size, char * dest, const char * src ) {
    if ( dest==NULL || size==0 ) { return dest; }
    else if ( size==1 ) { *dest=0; return dest; }
    else {
        char * copy = dest;
        size_t destlen = strlen( dest );
        --size;
        if ( destlen>size ) { destlen = size; }
        copy += destlen;
        while ( destlen<size ) {
            if ( 0 == (*copy = *src) ) { break; }
            ++copy; ++src; ++destlen;
        }
        *copy = 0;
        return dest;
    }
}

#ifndef NDEBUG
    #include "uUnit.h"
#endif

/** Inserts string 'insert' into 'dest' at position 'n'.

    If inserting all characters from 'dest' would result in a string with
    'size' or more characters, a null-character is implicitly appended to
    'dest' to ensure that its length is less than 'size'; in this case, only
    a portion of the leading characters from 'insert' would be inserted into
    'dest'. The 'dest' memory block will always be a null terminated C
    string.

    Any of the following conditions leaves the value in 'dest' unchanged:
    - (insert[0]==0) -> 'insert' is the null string
    - (size == 0)
    - (dest == NULL)

    Any of the following conditions will null terminate 'dest':
    - (n >= size)
    - (n > strlen(dest)) -> index out of bounce
    - (insert[0]==0) -> Insert empty string
    - (size==1)

    \param size     Size of the 'dest' memory block.
    \param dest     Pointer to the destination array of 'size' characters.
    \param insert   C string to be inserted.
    \param n        Position in 'dest' where the string will be inserted.
    \returns 'dest' is returned.
    \test_example{ztrins}
*/
char* ztrins( size_t size, char * dest, size_t n, const char * insert ) {
    if ( dest==NULL || size==0 ) { return dest; }
    else if ( size==1 ) { *dest=0; return dest; }
    else { /* ( size>=2 ) */
        size_t inslen, destlen = strlen( dest );
        --size; /* max length for 'dest' */
        if ( destlen>size ) { destlen = size; }
        if ( n>size || n>destlen || insert[0]==0 ) {
            dest[size] = 0; return dest;
        }
        inslen = strlen( insert );
        if ( size <= n+inslen ) { /* the whole 'insert' does not fit */
            memmove( &dest[n] , insert, (size-n) );
        }
        else { /* first move tail to the right */
            if ( size <= destlen+inslen ) { /* only a piece fits */
                memmove( &dest[n+inslen], &dest[n], (size-(n+inslen)) );
            }
            else { /* insert the whole thing */
                memmove( &dest[n+inslen], &dest[n], (destlen-n) );
                size =  destlen+inslen;
            }
            memmove( &dest[n] , insert , inslen ); /* insert */
        }
        dest[size] = 0;
    }
    return dest;
/*
        n              size
    +===!-----+.........+
            destlen
    +______+
     inslen                     strlen("-----+") = (destlen-n)

    +===!______+-----+....+
*/
        #if 0
        {
            size_t MAX = ( (0==0) ? 500 : UINT_MAX/2 );
            assert( inslen<MAX ); assert( n<MAX ); assert( destlen<MAX ); assert( size<MAX );
        }
        #endif
}

/** Deletes the leading 'len' characters from 'str'.
    When 'dest' has less than 'len' characters, it becomes the null string.
    Any of the following conditions leaves the value in 'dest' unchanged:
    - (dest[0]==0) ==> 'dest' is the null string
    - (len == 0)
    - (dest == NULL)

\param   dest   Pointer to the destination array of characters.
\param   len    Number of characters to remove from 'dest'.
\returns 'dest' is returned.
\test_example{strdel}
*/
char* strdel( char * dest, size_t len ) {
    if ( dest==NULL || len==0 ) { /* nothing nada */ }
    else if ( dest[0]==0 ) { return dest; }
    else {
        size_t destlen = strlen( dest );
        if ( destlen<=len ) { dest[0]=0; }
        else {
            memmove( dest, dest+len, 1+(destlen-len) );
        }
    }
    return dest;
}

/** Copies the first 'len' characters from 'src' to 'dest'.
    The string in 'dest' is zero terminated.
    No more than 'size' characters in 'dest' get overwritten.
    \param size   Size of the 'dest' memory block.
    \param dest   C substring to be produced.
    \param src    Source string.
    \param len    maximum length of substring to be produced.
    \test_example{ztrsub}
*/
char* ztrsub( size_t size, char * dest, const char * src, size_t len ) {
    if ( dest==NULL || size==0 ) { return dest; }
    else if ( size==1 ) { *dest=0; return dest; }
    else {
        char *copy = dest;
        --size; /* max number of chars to copy */
        size = ( size < len ? size : len );
        while (size>0) {
            if ( 0 == (*copy = *src) ) { break; }
            ++copy; ++src; --size;
        }
        *copy = 0;
    }
    return dest;
}

/** Returns a pointer to the first character in 'str' different from 'tr'.
    Does not change 'str' but returns a pointer inside it.
\param src    Source string.
\param tr     Character to trim from left of 'src'.
\test_example{strltrim}
*/
char* strltrim( const char *src , char tr ) {
    if ( src==NULL ) { return NULL; }
/*  else if ( tr==0 ) { return src; }  */
    while ( *src==tr ) {
        ++src;
    }
    return (char*)(src);
}

/** Removes from 'str' all trailing characters that are equal to 'tr'.
    Changes string 'str' and returns a pointer to it.
    All trailing characters equal to 'tr' are removed inserting one char(0).
\param src    Source string.
\param tr     Character to trim from right of 'src'.
\test_example{strrtrim}
*/
char* strrtrim( char *src , char tr ) {
    if ( src==NULL ) { return NULL; }
    else {
        char * p    = src;
        char * last = src;
        while ( *p!=0 ) {
            if ( *p==tr ) {
                last=p;
                do  {
                    ++p;
                } while ( *p==tr );
            }
            else {
                last=src;
                ++p;
            }
        }
        if ( *last==tr ) {
            *last=0;
        }
        return src;
    }
}

/** return strrtrim( strltrim(s,tr),tr ).
    Returns a pointer to the first character in 's' different from 'tr' but
    also removes from 's' all trailing characters equal to 'tr'.
*/
char* strtrim( char *src , char tr ) {
    return strrtrim( strltrim(src,tr),tr );
}

/** Removes every ocurrence of 'ch' from 'mem'.
    Mnemonic: memczap <==> memory-zap-char.

    Scans the memory buffer 'mem' for every occurrence of character 'ch' and
    removes it, for up to 'size' characters.
    - Stops after 'size' characters have been scanned.
    - Returns the number of non deleted characters that remain in 'mem'.

 \returns the size that the block should have after the characters are removed.
\param size   Size of memory block 'mem'.
\param mem    Memory block of characters.
\param ch     Character to trim from right of 'src'.
\test_example{memczap}
  */
size_t memczap( size_t size, void * mem, int ch ) {
/*
            123456789
    mem  = <-!--!--!-> size = 9
    memczap(mem, sizeof(mem), '-') yields:
    mem == <!!!>      returns 3 == (9-6)

            123456
    mem  = (*:**-*)    size = 6
    memczap(mem, sizeof(mem), '*') yields:
    mem  = (:-)        returns 2 == (6-4).

*/
    /* memczap_better() */
    char *i;  /* char in process within s     */
    char *j;  /* next position to copy from s */
    size_t len, count = 0;
    i = j = (char*)(mem);
    if ( ch!=*i ) { /* count prefix */
        assert( "needs improvement" );
        while ( ch!=*i ) {
            ++i;
            if ( (i-j)> (ptrdiff_t)(size) ) {
                return size;
            }
        }
    }
    len = count = (i-j);
    j = i;
    while ( count<size ) {
        if ( ch!=*i ) {
            *j = *i;     /* copy  */
            len++;       /* count */
            j++;         /* next  */
        }

        i++;
        count++;
    }
    return len;

} /* memczap */

#if 0
/* this is a less complictaed implementation */
size_t memczap_smaller( size_t size, void *mem, int ch ) {
    char *i;  /* char in process within s     */
    char *j;  /* next position to copy from s */

    size_t count;
    size_t len;

    i = j = (char*) mem;
    len = count = 0;
    while (count<size) {
        if ( ch!=*i ) {
            *j = *i;     /* copy  */
            len++;       /* count */
            j++;         /* next  */
        }

        i++;
        count++;
    }
    return len;

} /* memczap */
#endif

/** Returns '1' if 'prefix' is a prefix of 'str'. Otherwise, returns '0'.
\param str    C string to be scanned.
\param prefix C string containing the sequence of characters to match.
\test_example{strpfx}
*/
int strpfx( const char *str, const char *prefix ) {
    while ( *prefix != 0 ) {
        if ( *prefix!=*str ) { return 0; }
        ++prefix; ++str;
    }
    return 1;
}

/** Returns '1' if 'suffix' is a suffix of 'str'. Otherwise, returns '0'.
\param str    C string to be scanned.
\param suffix C string containing the sequence of characters to match.
\test_example{strsffx}
*/
int strsffx( const char *str, const char *suffix ) {
    size_t slen = strlen( str );
    size_t xlen = strlen( suffix );
    if ( slen<xlen ) { return 0; }
    else {
        const char *pStr = str+slen;
        const char *pSfx = suffix+xlen;
        while ( pSfx != suffix ) {
            if ( *pStr!=*pSfx ) { return 0; }
            --pStr; --pSfx;
        }
    }
    return 1;
}

/** Get span until character in character range '[a..z]'.
    Scans 'str' for the first occurrence of any of the characters that are
    part of character range begining in 'a' and ending in 'z', returning the
    number of characters of 'str' read before this first occurrence.
    The search includes the terminating null-characters. Therefore, the
    function will return the length of 'str' if none of the characters in
    range '[a..z]' are found in 'str'.
\param str  C string to be scanned.
\param a    First character in character range.
\param z    Last character in character range.
\returns    The length of the initial portion of 'str' containing only characters in range.
\test_example{strrspn}
*/
size_t strrspn( const char * str, char a, char z ) {
    size_t span = 0;
    while ( ((*str)!=0) && (a<=(*str)) && ((*str)<=z) ) {
        ++span; ++str;
    }
    return span;
}

/** Uses strxltn1() to convert all letters in 'str'.
    This has the effect of removing accents in many of those letters;
    for example, 'á' is translated as 'a' and 'ÿ' as 'y'.
    The translated characters are the upper 8 bit characters in the Latin 1
    alphabet, also know as Windows-1252 and ISO/IEC 8859-1.
    \see http://en.wikipedia.org/wiki/ISO/IEC_8859-1
    \see http://en.wikipedia.org/wiki/Windows-1252

    This is the translation table used:
    \code
    ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ
    AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy
    \endcode
\test_example{strxacct}
\test_example{strxltn1}
*/
char* strxacct( char* str ) {
    char *p = str;
    while ( (*p)!=0 ) {
    #if 0
        const char*
        //   "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ"
        tr = "AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy";
        size_t char ch = (*p);
        if ( ch >=192 ) {
            (*p) = tr[ ch-192 ];
        }
    #else
        *p = strxltn1(*p) ;
    #endif /* 0 */
        ++p;
        /*  http://stackoverflow.com/questions/14094621/  */
    }
    return str;
}

char* strtokl( char * str, const char * delimiters , size_t *len );

/* strtok example */
#include <stdio.h>
#include <string.h>

#if 0

int main () {
    char str[] ="- This, a sample string.";
    char * pch;
    printf ("Splitting string \"%s\" into tokens:\n",str);
    pch = strtok (str," ,.-");
    while (pch != NULL) {
        printf ("%s\n",pch);
        pch = strtok (NULL, " ,.-");
    }
    return 0;
}

int main() {
    char str[] ="- This, a sample string.";
    char * pch;
    size_t len;
    printf ("Splitting string \"%s\" into tokens:\n",str);
    pch = strtokl (str," ,.-",&len);
    while (pch != NULL) {
        {
            const char* p = pch;
            size_t l = 0;
            while (l!=len) {
                printf ("%c",*p);
                ++l;
            }
            printf ("\n",str);
        }
        pch += len;
        strtokl (pch, " ,.-",&len);
    }
    return 0;
}
#endif /* 0 */


/* ztring.c */