ztring.h File Reference

A few string functions to enhance C's <string.h> library. More...

#include <cstring>
#include <climits>
#include <cstddef>

Go to the source code of this file.

Macros
#define	removeAccented(str)   strxacct( str ) /* mnemonic name */
#define	strxltn1_translate
	Translation table for strxltn1(). More...

Functions
char *	ztrcpy (size_t size, char *dest, const char *src)
	Copies up to 'size' characters from 'src' to 'dest'. More...
char *	ztrcat (size_t size, char *dest, const char *src)
	Append characters to a string. More...
char *	ztrins (size_t size, char *dest, size_t i, const char *insert)
	Inserts string 'insert' into 'dest' at position 'n'. More...
char *	strdel (char *dest, size_t len)
	Deletes the leading 'len' characters from 'str'. More...
char *	ztrsub (size_t size, char *dest, const char *src, size_t len)
	Copies the first 'len' characters from 'src' to 'dest'. More...
char *	strltrim (const char *str, char tr)
	Returns a pointer to the first character in 'str' different from 'tr'. More...
char *	strrtrim (char *str, char tr)
	Removes from 'str' all trailing characters that are equal to 'tr'. More...
char *	strtrim (char *str, char tr)
	return strrtrim( strltrim(s,tr),tr ). More...
size_t	memczap (size_t size, void *mem, int ch)
	Removes every ocurrence of 'ch' from 'mem'. More...
int	strpfx (const char *str, const char *prefix)
	Returns '1' if 'prefix' is a prefix of 'str'. More...
int	strsffx (const char *str, const char *suffix)
	Returns '1' if 'suffix' is a suffix of 'str'. More...
size_t	strrspn (const char *str, char a, char z)
	Get span until character in character range '[a..z]'. More...
char	strxltn1 (char accented_latin_1)
	Translates characters in range [192<–>192+63] into letters or ASCII symbols that look similar. More...
char *	strxacct (char *str)
	Uses strxltn1() to convert all letters in 'str'. More...

Detailed Description

A few string functions to enhance C's <string.h> library.

Author

Adolfo Di Mare adolf.nosp@m.o@di.nosp@m.-mare.nosp@m..com

Date

2014

Definition in file ztring.h.

Macro Definition Documentation

#define removeAccented

(

str

)

strxacct( str ) /* mnemonic name */

Definition at line 50 of file ztring.h.

#define strxltn1_translate

Value:

/* "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ" */ \
   "AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy"

Translation table for strxltn1().

Definition at line 62 of file ztring.h.

Function Documentation

char* ztrcpy	(	size_t	size,
		char *	dest,
		const char *	src
	)

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 Also

http://www.drdobbs.com/managed-string-library-for-c/184402023

http://en.wikipedia.org/wiki/C_string_handling

Remarks

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 Also

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

Parameters

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

Returns

'dest' is returned.

{{  /* test::ztrcpy() */
    char s10[9+1];   /* No more than 9 chars get copied */
    {
        ztrcpy( sizeof(s10),s10 , "123456789.abcdefghi.");
        assertTrue( eqstr(  s10 , "123456789" ) );
    }
    #define ZS(x) sizeof(x),x /* Shortcut macro */
    {
        ztrcpy(        ZS( s10 ), "123456789.abcdefghi.");
        assertTrue( eqstr( s10  , "123456789" ) );
    }
    #undef ZS /* ZS() could make code more compatible with strcpy() */
}}

See Also

test_ztrcpy()

    {{  /* test::BeUNsafe::SZ() */
        #ifdef USE_ZTR
            #define ZS(x) sizeof(x),x /* Shortcut macro */
        #else
            #define ZS(x) x
            /* convert ztrcpy(ZS(dest),src) -> strcpy(dest,src) */
            #define    ztrcpy(   dest, src)    strcpy(dest,src)
            /* convert ztrcat(ZS(dest),src) -> strcat(dest,src) */
            #define    ztrcat(   dest, src)    strcat(dest,src)
        #endif
    }}

See Also

test_BeUNsafe::SZ()

Definition at line 57 of file ztring.c.

char* ztrcat	(	size_t	size,
		char *	dest,
		const char *	src
	)

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 Also

http://www.openbsd.org/cgi-bin/man.cgi?query=strlcat

http://en.wikipedia.org/wiki/C_string_handling

Parameters

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

Returns

'dest' is returned.

{{  /* test::ztrcat() */
    char s10[9+1]; s10[0] = 0;
    ztrcat( sizeof(s10),s10 , "123456789.abcdefghi.");
    assertTrue( eqstr(  s10 , "123456789" ) );
    {
        s10[3] = '.'; s10[3+1] = 0;
        assertTrue( eqstr(  s10 , "123." ) );
        ztrcat( sizeof(s10),s10 , "123456789.abcdefghi.");
        assertTrue( eqstr(  s10 , "123.12345" ) );
    }
    #define ZS(x) sizeof(x),x /* Shortcut macro */
    {
        s10[3] = '.'; s10[3+1] = 0;
        assertTrue( eqstr( s10 , "123." ) );
        ztrcat(         ZS(s10), "123456789.abcdefghi.");
        assertTrue( eqstr( s10 , "123.12345" ) );
    }
    #undef ZS  /* ZS() could make code more compatible with strcat() */
}}

See Also

test_ztrcat()

    {{  /* test::BeUNsafe::SZ() */
        #ifdef USE_ZTR
            #define ZS(x) sizeof(x),x /* Shortcut macro */
        #else
            #define ZS(x) x
            /* convert ztrcpy(ZS(dest),src) -> strcpy(dest,src) */
            #define    ztrcpy(   dest, src)    strcpy(dest,src)
            /* convert ztrcat(ZS(dest),src) -> strcat(dest,src) */
            #define    ztrcat(   dest, src)    strcat(dest,src)
        #endif
    }}

See Also

test_BeUNsafe::SZ()

Definition at line 95 of file ztring.c.

char* ztrins	(	size_t	size,
		char *	dest,
		size_t	n,
		const char *	insert
	)

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)

Parameters

size	Size of the 'dest' memory block.
dest	Pointer to the destination array of 'size' characters.
insert	C string to be inserted.
n	Position in 'dest' where the string will be inserted.

Returns

'dest' is returned.

{{  /* test::ztrins() */
    char s30[30];              /* 123456789.123456789.1 -> 21 chars */
    ztrcpy(     sizeof(s30),s30, "====!-----+.........+" );
    { { ztrins( sizeof(s30),s30,  4, "_2_4_"); } } /* [4] <-> s30+(4) */
                            /*   /!\   */
    assertTrue(  eqstr(s30,  "====_2_4_!-----+.........+") );
    assertTrue( 26 == strlen("====_2_4_!-----+.........+") );
    { { { assertTrue(  21+strlen("_2_4_") == strlen(s30) ); } } }

    {   /* replace JIM with ROMEO */
        char *p; char poem[] = "JIM, JIM, JIM ... Where are you?";
        while ( 0!=(p=strstr(poem,"JIM")) ) {
            strdel( p, strlen("JIM") );
            ztrins( sizeof(poem),poem, p-poem, "ROMEO" );
        }
        assertTrue( eqstr(poem,"ROMEO, ROMEO, ROMEO ... Where ar") );

        assertTrue( strlen("JIM")<strlen("ROMEO") ); /* -> truncation */
        assertTrue( strlen("ROMEO, ROMEO, ROMEO ... Where ar") ==
                    strlen("JIM, JIM, JIM ... Where are you?") );
    }

    ztrcpy(     sizeof(s30),s30, "====!-----+.........+" ); /* -> 21 chars */
    { { ztrins( sizeof(s30),s30, 00, "________18________"); } } /* [0] */
    assertTrue(  eqstr(s30,  "________18________====!-----+") );
    assertTrue( strlen(s30) == sizeof(s30)-1 ); /* max size */

    ztrcpy(     sizeof(s30),s30, "0123456789" );
    { { ztrins( /*size->*/1,s30, 0, "" ); } }
    assertTrue( eqstr(s30, "") ); /* (size==1) ==> (s30[0]==0) */
    assertTrue( eqstr(s30+1 ,     "123456789" ) );
}}

See Also

test_ztrins()

Definition at line 144 of file ztring.c.

char* strdel	(	char *	dest,
		size_t	len
	)

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)

Parameters

dest	Pointer to the destination array of characters.
len	Number of characters to remove from 'dest'.

Returns

'dest' is returned.

{{  /* test::strdel() */
    char s10[9+1]; char *p;    assertTrue( sizeof(s10)>9 );
    {   /* remove 5 leading chars from string 's10' */
        ztrcpy( sizeof(s10),s10, "123456789.123456789.abcde" );
        assertTrue(   eqstr(s10, "123456789") );
        { { strdel( s10, 5 ); } }
        assertTrue( strlen(s10)==4 && eqstr( s10, "6789" ) );
    }
    {   /* find leading '.' and remove up to it */
        ztrcpy( sizeof(s10),s10, "1234.abcd.1234.abcd" );
        if ( NULL!=(p=strchr(s10,'.')) ) { { strdel( s10 , 1+(p-s10) ); } }
        assertTrue( eqstr( s10, "abcd" ) );  assertTrue(  4==(p-s10) );
        /*   (p-s10) -> length of prefix before '.' */
        /* 1+(p-s10) -> remove also the '.'         */
    }
    {   /* remove in the middel of 's10' */
        ztrcpy( sizeof(s10),s10, "0123..678" );
        { { strdel( s10+4 , 2 ); } } /* s10+4 points inside 's10' */
        assertTrue( eqstr( s10, "0123678" ) );
    }
}}

See Also

test_strdel()

Definition at line 200 of file ztring.c.

char* ztrsub	(	size_t	size,
		char *	dest,
		const char *	src,
		size_t	len
	)

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.

Parameters

size	Size of the 'dest' memory block.
dest	C substring to be produced.
src	Source string.
len	maximum length of substring to be produced.

{{  /* test::ztrsub()       .123456789 */
    char str[] = ".123456789.abcdefghi.";
    char sub[22];
    assertTrue( strlen(str) == 21 && sizeof(sub)==22 );
    {   /* first 5 chars from 'str' */
        ztrsub( sizeof(sub),sub ,  str,5 );
        assertTrue( eqstr(  sub , ".1234" ) );
    }
    {   /* all chars from 'str' [similar to ztrcpy()] */
        ztrsub( sizeof(sub),sub , str,UINT_MAX );
        assertTrue( eqstr(  sub , str ) );
    }
    {   /* a substring taken from the middle of 'str' */
        ztrsub( sizeof(sub),sub , str+10,7 );
        assertTrue( eqstr(  sub ,   ".abcdef" ) );
        assertTrue( eqstr( str+10 , ".abcdefghi." ) );
        assertTrue(    7 == strlen( ".abcdef" ) );
    }
    {   /* 0 length substring produces the empty string */
        ztrsub( sizeof(sub),sub , str,000 );
        assertTrue( eqstr(  sub , "" ) );
    }
}}

See Also

test_ztrsub()

Definition at line 222 of file ztring.c.

char* strltrim	(	const char *	src,
		char	tr
	)

Returns a pointer to the first character in 'str' different from 'tr'.

Does not change 'str' but returns a pointer inside it.

Parameters

src	Source string.
tr	Character to trim from left of 'src'.

{{  /* test::strltrim() */
    char s[] =      "   la mona  es     una loca  ";
    assertTrue( eqstr( "la mona  es     una loca  " , strltrim( s, ' ' ) ) );
    {
        char t[] =         "XXXla mona  es     una loca  ";
        assertTrue( eqstr(    "la mona  es     una loca  " , strltrim( t, 'X' ) ) );
        assertTrue( eqstr( "XXXla mona  es     una loca  " , t ) ); /* no change */
    }
}}

See Also

test_strltrim()

Definition at line 244 of file ztring.c.

char* strrtrim	(	char *	src,
		char	tr
	)

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

Parameters

src	Source string.
tr	Character to trim from right of 'src'.

{{  /* test::strrtrim() */
    char s[] =          "   la mona  es     una loca  ";
    assertTrue(  eqstr( "   la mona  es     una loca" , strrtrim( s, ' ' ) ) );
    {
        char t[] =          "   la mona  es     una loca  XXX";
        assertTrue(  eqstr( "   la mona  es     una loca  " , strrtrim( t, 'X' ) ) );
        assertFalse( eqstr( "XXXla mona  es     una loca  ", t ) );
    }
}}

See Also

test_strrtrim()

Definition at line 260 of file ztring.c.

char* strtrim	(	char *	src,
		char	tr
	)

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

Definition at line 288 of file ztring.c.

size_t memczap	(	size_t	size,
		void *	mem,
		int	ch
	)

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.

Parameters

size	Size of memory block 'mem'.
mem	Memory block of characters.
ch	Character to trim from right of 'src'.

{{  /* test::memczap() */
    char m30[30]; size_t n;
    strcpy( m30, "-!--!--!-" ); assertTrue( strlen(m30)==9 );
    {          /* 12345678  */
        n = memczap(strlen(m30),m30, '-' ); /* ZAP '-' */
        assertTrue( n==3 && 3==(9-6) );
        assertTrue( 0==memcmp(m30, "!!!", strlen("!!!") ) );

        assertTrue( 0!=strcmp(m30, "!!!" ) );
        /* ==> */ m30[n] = 0; /* <== */
        assertTrue( 0==strcmp(m30, "!!!" ) );
    }
    strcpy( m30, "(*:**-*)" ); assertTrue( strlen(m30)==8 );
    {          /* 12345678  */
        n = memczap(strlen(m30),m30, '*'); /* ZAP '*' */
        assertTrue( n==4 && 4==(8-4) );
        assertTrue( 0==memcmp(m30, "(:-)",     strlen("(:-)") ) );
        assertTrue( 0==memcmp(m30, "(:-)*-*)", strlen(m30) ) );
    }
    strcpy( m30, "*:**-*" ); assertTrue( strlen(m30)==6 );
    {         /*  123456  */
        n = memczap(strlen(m30),m30, '*'); /* ZAP '*' */
        assertTrue( n==2 && 2==(6-4) );
        assertTrue( 0==memcmp(m30, ":-", strlen(":-") ) );
    }
}}

See Also

test_memczap()

Definition at line 306 of file ztring.c.

int strpfx	(	const char *	str,
		const char *	prefix
	)

Returns '1' if 'prefix' is a prefix of 'str'.

Otherwise, returns '0'.

Parameters

str	C string to be scanned.
prefix	C string containing the sequence of characters to match.

{{  /* test::strpfx() */
    assertTrue(  strpfx( "123456789.123456789.", "12345678" ) );
    assertTrue(  strpfx( "123456789.123456789.", "" ) );

    assertFalse( strpfx( "12345678" , "123456789.123456789." ) );
}}

See Also

test_strpfx()

Definition at line 380 of file ztring.c.

int strsffx	(	const char *	str,
		const char *	suffix
	)

Returns '1' if 'suffix' is a suffix of 'str'.

Otherwise, returns '0'.

Parameters

str	C string to be scanned.
suffix	C string containing the sequence of characters to match.

{{  /* test::strsffx() */
    assertTrue( strsffx( "123456789.123456789.", "6789." ) );
    assertTrue( strsffx( "123456789.123456789.", "" ) );

    assertFalse( strsffx( "6789.", "123456789.123456789." ) );
}}

See Also

test_strsffx()

Definition at line 393 of file ztring.c.

size_t strrspn	(	const char *	str,
		char	a,
		char	z
	)

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

Parameters

str	C string to be scanned.
a	First character in character range.
z	Last character in character range.

Returns

The length of the initial portion of 'str' containing only characters in range.

See Also

test_strrspn()

Definition at line 421 of file ztring.c.

char strxltn1 ( char  accented_latin_1 )

inline

Translates characters in range [192<–>192+63] into letters or ASCII symbols that look similar.

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 Also

http://en.wikipedia.org/wiki/ISO/IEC_8859-1

http://en.wikipedia.org/wiki/Windows-1252

This is the translation table used:

ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ
AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy

{{  /* test::strxltn1() */
    char Atilde[]  = "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ";
    char Asimple[] = "AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy";

    assertTrue( 'A' == strxltn1('Á') );    assertTrue( 'N' == strxltn1('Ñ') );
    assertTrue( 'Y' == strxltn1('Ý') );    assertTrue( 'D' == strxltn1('Ð') );

    assertTrue( 's' == strxltn1('ß') );    assertTrue( 'P' == strxltn1('Þ') );
    assertTrue( 'x' == strxltn1('×') );    assertTrue( '/' == strxltn1('÷') );
    assertTrue( '0' == strxltn1('Ø') );    assertTrue( 'd' == strxltn1('ð') );

    assertTrue( Atilde != Asimple );
}}

See Also

test_strxltn1()

Definition at line 86 of file ztring.h.

char* strxacct

(

char *

str

)

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 Also

http://en.wikipedia.org/wiki/ISO/IEC_8859-1

http://en.wikipedia.org/wiki/Windows-1252

This is the translation table used:

ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ
AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy

{{  /* test::strxacct() */
    char Atilde[]  = "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ";
    char Asimple[] = "AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy";

    char Astr[ sizeof(Atilde) ];
    strcpy( Astr, Atilde );

    assertTrue( 0==strcmp( Asimple, strxacct(Astr) ) );
}}

See Also

test_strxacct()

{{  /* test::strxltn1() */
    char Atilde[]  = "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ";
    char Asimple[] = "AAAAAAECEEEEIIIIDNOOOOOx0UUUUYPsaaaaaaeceeeeiiiidnooooo/0uuuuypy";

    assertTrue( 'A' == strxltn1('Á') );    assertTrue( 'N' == strxltn1('Ñ') );
    assertTrue( 'Y' == strxltn1('Ý') );    assertTrue( 'D' == strxltn1('Ð') );

    assertTrue( 's' == strxltn1('ß') );    assertTrue( 'P' == strxltn1('Þ') );
    assertTrue( 'x' == strxltn1('×') );    assertTrue( '/' == strxltn1('÷') );
    assertTrue( '0' == strxltn1('Ø') );    assertTrue( 'd' == strxltn1('ð') );

    assertTrue( Atilde != Asimple );
}}

See Also

test_strxltn1()

Definition at line 445 of file ztring.c.