str.h
=============================================================================

    This header file has the prototypes for all string-related routines.
    There are several macros available too. All functions have a 'str'
    prefix and use the standard library passing convention (dest, src)
    where appropriate.

    MACROS
    -------------------------------------------------------------------------

        Summary   Special macros to improve readability of comparisons.

        Syntax    #define STREQU(a,b)     ( 0 == strcmp(a,b)    )
                  #define STRNEQU(a,b)    ( 0 != strcmp(a,b)    )
                  #define STRIEQU(a,b)    ( 0 == stricmp(a,b)   )
                  #define STRINEQU(a,b)   ( 0 != stricmp(a,b)   )
                  #define MEMEQU(a,b,l)   ( 0 == memcmp(a,b,l)  )
                  #define MEMNEQU(a,b,l)  ( 0 != memcmp(a,b,l)  )
                  #define MEMIEQU(a,b,l)  ( 0 == memicmp(a,b,l) )
                  #define MEMINEQU(a,b,l) ( 0 != memicmp(a,b,l) )

        Remarks  These macros are very nice when you do string comparisons.
                 It might me somewhat misleading that all functions return
                 0 if the strings are equal and non-zero if they are not.
                 These routines return 1 if the strings are the same and 0
                 if they are not thereby making conditionals easier to read.
                 The versions with IEQU and INEQU ignore the case when
                 performing the comparisons.

        Return   1 if the strings are the same (EQU) or different (NEQU)
                 0 if the strings are different (EQU) or the same (NEQU)


    STRADD
    -------------------------------------------------------------------------

        Summay   Adds two numbers in string format and returns result.

        Syntax   char *stradd(char *dest, const char *s1, const char *s2);

        Remarks  This is a peculiar function, it adds two numbers 's1' and
                 's2' (in string format, decimal) and creates a result
                 string which represents the sum (also in decimal). This
                 can be used for adding large numbers. Note that you can
                 not have whitespace or signs in the strings. Also, the
                 function performs no error checking.

        Return   Locally allocated string with result. Must be destroyed
                 by the caller.

        Example  char buf[255];
                 stradd(buf, "1245232", "9739320093");
                 printf("result is: %s\n", buf);


    STRCCAT
    -------------------------------------------------------------------------

        Summary  Append a character to a string.

        Syntax   char *strccat(char *s, int ch);

	    Remarks  Appends character c to string s. s must be big enough to
	             hold the new character.

        Return	 Pointer to modified string s

        Example  char buf[20];
                 strcpy( buf, "Hello, world" );
                 printf( "%s\n", strccat( buf, '!' ) );


    STRCDEL
    -------------------------------------------------------------------------

        Summary  Deletes character from string

        Syntax   char *strcdel(char *s, size_t index);

        Remarks  Removes character at position index from string s. If index
                 is > strlen(s), nothing is removed. Note that index starts
                 from 0. To remove the 5th character, the index should be 4.

        Return   Pointer to modified string s

        Example  char buf[] = "Hello,, world!";
                 printf( "%s\n", strcdel(buf,5) );


    STRCENT
    -------------------------------------------------------------------------

        Summary	 Centers a string into a buffer

        Syntax   char *strcent(char *dest, const char *src, size_t n);

        Remarks  Centers 'src' into 'dest' using width 'n' by padding with
                 spaces or truncating when necessary. Note that 'n' will be
                 filled, as strcent() does pad with whitespace. The
                 destination buffer must be large enough to hold the new
                 string.

        Return   dest

        Example  char buf[100];
                 printf("%s\n", strcent(buf, "centered at 80 chars.", 80));
                 printf("%s\n", strcent(buf, "centered at 37 chars.", 37));
                 printf("%s\n", strcent(buf, "centered at 9 chars.", 9));


    STRCINS
    -------------------------------------------------------------------------

        Summary  Inserts a character in a string

        Syntax   char *strcins(char *s, size_t index, int ch);

        Remarks  Inserts character 'ch' in string 's' at position 'index'.
                 The string must be big enough to accomodate the new
                 character. If index is > strlen(s), no action is performed.

        Return   A pointer to the string

        Example  char buf[15] = "Hello world!";
                 printf( "%s\n", strcins(buf, 5, ',') );


    STRCMA
    -------------------------------------------------------------------------

        Summary	 Inserts comma-delimeters in string number

        Syntax   char *strcma(char *dest, const char *src);

        Remarks  Inserts the comma-separators in a number represented as a
                 string. The destination string must be big enough to
                 accomodate the result. The function doesn't care if you
                 actually have valid symbols in the string, it also doesn't
                 know anything about signs and whitespace.

        Return   dest

        Example  char buf[20];
                 printf( "%s\n", strcma(buf, "1234567890") );


    STRCREP
    -------------------------------------------------------------------------

        Summary	 Replace all occurences of a character with another

        Syntax   char *strcrep(char *s, int ch1, int ch2);

        Remarks  Replaces all occurences of character ch1 in the string s
                 with new character c2. A pointer to the modified string s
                 is returned.

        Return   The modified string

        Example  char s[] = "ThiS iS just another of thoSe teSt StringS!";
                 printf( "Orig: %s\n", s );
                 printf( "Mod : %s\n", strcrep(s,'S','s') );

        See also strsrep, strcrm, strcdel, strsrm


    STRCRM
    -------------------------------------------------------------------------

        Summary  Remove all occurences of a character from a string

        Syntax   char *strcrm(char *s, int ch);

        Remarks  Removes all occurences of character c from string s. Returns
                 modified string s.

        Return   Modified string.

        Example  char s[] = "This is just another ntest string!";
                 printf( "Orig: %s\n", s );
                 printf( "Mod.: %s\n", strcrm(s,'n') );

        See also strsrm, strsrep, strcrep, strdel



    STRDATE
    -------------------------------------------------------------------------

        Summary  Returns current date in a string

        Syntax   char *strdate(void);

        Remarks  Returns the current date in a string as: mm/dd/yy. The
                 result is a pointer to a staticly allocated buffer, 9
                 characters long. It is overwritten with each call.

        Return   Pointer to a static buffer with current date.

        Example  printf( "Current date: %s\n", strdate() );


    STRDEL
    -------------------------------------------------------------------------

        Summary  Deletes a portion of string

        Syntax   char *strdel(char *s, size_t index, size_t n);

        Remarks  Deletes n characters starting from index position within
                 string s. If index + n exceeds strlen(s), all of the string,
                 starting at index, will be deleted. If index is > strlen(s),
                 no action is performed.

        Return   String s with portion deleted

        Example  char buf[20] = "Hello, my world!";
                 strcpy( buf, "Hello, my world!" );
                 printf( "%s\n", strdel(buf, 6, 3) );


    STRECPY
    -------------------------------------------------------------------------

        Summary  strcpy without null-terminating, returns pointer to end

        Syntax   char *strecpy(char *dest, const char *src);

        Remarks  Copies src into dest but does not copy the NUL terminator
                 character. Returns a pointer to the end of the new dest
                 (where the NUL character would go).

        Return   Pointer to the end of dest (where the NUL would go)


    STRFUPR
    -------------------------------------------------------------------------

        Summary  Convert first character of each word to uppercase

        Syntax   char *strfupr(char *s, const char *sep);

        Remarks  Converts the first character of each word in s to uppercase.
                 Words are defined as sequence of characters that are
                 separated by one or more runs of whitespace as defined by
                 the isspace() call and one or more characters from the sep
                 string.

        Return   This function returns the modified string s.

        Example  char *s = "this; is.a test String-here, that!we have.";
                 printf( "%s\n", strfupr(s, ".,;!-") );


    STRICHR
    -------------------------------------------------------------------------

        Summary  Case-insensitive search for a character in string

        Syntax   char *strichr(const char *s, int ch);

        Remarks  Same as strchr() except the search is not case-sensitive.
                 The pointer returned will point to the character as it
                 appears in s, not as specified by the ch parameter. If no
                 match is found, NULL is returned.

        Return   Pointer to character if found, NULL otherwise

        Example  char *p = strichr( s, 'I' );
                 if( p ) printf( "Found 'I': %s", p );

        See also stristr


    STRIGHT
    -------------------------------------------------------------------------

        Summary  Returns last characters from a string

        Syntax   char *stright(char *dest, const char *src, size_t n);

        Remarks  Copies the last n characters from string src into dest.
                 The destination buffer will be NUL-terminated and should be
                 big enough to hold the resulting string. If n > strlen(s),
                 the whole string is copied.

        Return   String dest with last n characters from src

        Example  char buf[30];
                 printf("%s\n", stright(buf, "I say: Hello, world!", 13));


    STRINS
    -------------------------------------------------------------------------

        Summary  Inserts a string into another

        Syntax   char *strins(char *s1, const char *s2, size_t index);

        Remarks  Inserts s2 into s1 at position index. s1 must be big enough
                 to accomodate the new string. Note that index starts from 0.
                 So, to insert after the fourth character, index should be 4,
                 not 5. If index exceeds strlen(s), the new string is
                 appended.

        Return   s1 with s2 inserted at the requested position

        Example  char buf[30];
                 strcpy(buf, "Hell!");
                 printf("%s\n", strins(buf, "o, world", 4));


    STRISTR
    -------------------------------------------------------------------------

        Summary  Searches for a substring in string, case insensitive

        Syntax   char *stristr(const char *s1, const char *s2);

        Remarks  Searches for the strung s2 in string s1. The search is not
                 case-sensitive. This function works like strstr() except
                 for that case is ignored when comparing characters.

        Return   Pointer to the first character of the match in s1 if found
                 or NULL if not found.

        Example  char *buf = "Hello, HELLO, 987heLlO,89 d  dhell o hELLo, e";
                 char *p = buf;
		         while( NULL != (p = stristr(p, "hello")) )
                     printf( "Found '%s'\n", p++ );


    STRLEFT
    -------------------------------------------------------------------------

        Summary  Returns first characters from a string

        Syntax   char *strleft(char *dest, const char *src, size_t n);

        Remarks  Copies the first n characters from string src into dest.
                 The destination buffer must be big enough to accomodate the
                 result. If n > strlen(s), the whole string src will be
                 copied into dest. The resulting buffer will always be NUL-
                 terminated.

        Return   String dest with first n characters from src.

        Example  char buf[30];
                 printf("%s\n", strleft(buf, "Hello, world! And others", 13));


    STRMID
    -------------------------------------------------------------------------

        Summary  Returns characters starting at given index

        Syntax   char *strmid(char *dest, const char *src,
                              size_t index, size_t n);

        Remarks  Copies n characters from string src, starting at index into
                 dest. The destination buffer must be big enough to
                 accomodate the result. If index + n > strlen(s), all
                 characters from index to the end of the string will be
                 copied. If index > strlen(s), no action is performed and
                 the resulting dest is undefined.

        Return   dest with specified number of characters from src.

        Example  char buf[30];
                 printf("%s\n", strmid(buf,"Here: 'Hello, world!' again",13,7));


    STRNECPY
    -------------------------------------------------------------------------

        Summary  Copies a specified number of bytes to a string

        Syntax   char *strnecpy(char *dest, const char *src, size_t n);

        Remarks  Same as strncpy() except it always NUL-terminates the
                 destination. This function copies n bytes from src into
                 dest and returns dest. Destination buffer must be big
                 enough to accomodate the resulting string. If n > strlen(s),
                 the copying stops after the end of the source string.

        Return   dest (always NUL-terminated)

        Example  char *cbuf = "This is a long constant buffer.";
                 char  ebuf[30];
                 printf( "%s\n", strnecpy(ebuf,cbuf,10) );


    STRNESET
    -------------------------------------------------------------------------

        Summary  Sets characters of string to specified value

        Syntax   char *strneset(char *s, int ch, size_t n);

        Remarks  Same as strnset() except it always NUL-terminates the
                 destination string. strneset() sets the first n characters
                 of string s to value ch. The buffer allocated for s must be
                 large enough to accomodate at least n + 1 characters since
                 no error checking is done. Actually, s is not treated as a
                 string, but as a buffer whose first n bytes will be set to
                 ch value. The difference is that the result will always be
                 terminated by the NUL character. The function returns	s.

        Return   Modified string s

        Example  char buf[50];
                 printf( "%s\n", strneset(buf,'a',49) );


    STRRTRM
    -------------------------------------------------------------------------

        Summary  Trims trailing whitespace from a string

        Syntax   char *strrtrm(char *s);

        Remarks  Trims all whitespace characters from the end of the string
                 s. Whitespace is defined by the isspace() call.

        Return   Modified string s

        Example  char buf[30];
                 strcpy( buf, "Hello, world!  \t \n\t   " );
                 printf( "%s\n", strrtrm(buf) );


    STRSKPNW
    -------------------------------------------------------------------------

        Summary  Skip leading non-whitespace characters.

        Syntax   char *strskpnw(char *s);

        Remarks  This function skips the leading characters in string s if
                 they are non-whitespace.

        Return   Pointer to appropriate position in s

        Example  printf( strskpnw("mess this remains!") );

        See also strskpw


    STRSKPW
    -------------------------------------------------------------------------

        Summary  Skip leading whitespace in a string.

        Syntax   char *strskpw(char *s);

        Remarks  Unlike strskpnw(), this function strips all leading
                 characters if they are whitespace.

        Return   Pointer to appropriate position in s

        Example  printf(strskpw(" \t Branislav is Here!"));


    STRSREP
    -------------------------------------------------------------------------

        Summary	 Replaces all occurences of a substring in a string

        Syntax   char *strsrep(char *s1, const char *s2, const char *s3);

        Remarks  Replaces all occurences of string s2 in s1 with s3. If
                 strlen(s3) > strlen(s2), the resulting string s1 will be
                 longer and the allocated buffer should be large enough to
                 accomodate the result.

        Return   s1

        Example  char *s1 = "This is just another string, isn't it. It is";
                 char s2[80] = "Ok, we'll try to do some replacing here too.";
                 printf( "Orig1: %s\n", s1 );
                 printf( "Mod1 : %s\n", strsrep(s1,"is","IS") );
                 printf( "Orig2: %s\n", s2 );
                 printf( "Mod2 : %s\n", strsrep(s2, "o", "uh-oh") );

        See also strcrep, strcdel, strcrm, strsrm, strdel


    STRSRM
    -------------------------------------------------------------------------

        Summary  Remove all occurences of a substring from a string

        Syntax   char *strsrm(char *s1, const char *s2);

        Remarks  Removes all occurences of s2 from s1. The comparison for
                 the matching is case-sensitive.

        Return   Modified string s1

        Example  char s[] = "This is just another of those test "
                            "strings, isn't it?";
                 printf( "Orig: %s\n", s );
                 printf( "Mod : %s\n", strsrm(s,"is") );

        See also strcrm, strcrep, strsrep, strcdel, strdel


    STRTIME
    -------------------------------------------------------------------------

        Summary	 Returns current time in a string

        Syntax   char *strtime(void);

        Remarks  Returns the current time in a string as: hh:mm:ss. The
                 result is a pointer to a staticly allocated buffer, 9
                 characters long. It is overwritten with each call.

        Return   Pointer to a static buffer with current system time

        Example  printf( "Current time: %s\n", strtime() );


    STRTRM
    -------------------------------------------------------------------------

        Summary	 Trims leading whitespace from a string

        Syntax   char *strtrm(char *s);

        Remarks  Trims all whitespace characters from the start of the string
                 s. Whitespace is defined by the isspace call (spaces,
                 horizontal tabs, newlines, form feeds, vertical tabs).

        Return   Modified string s

        Example  char buf[20] = ;
                 strcpy( buf, "  \n\t \t    Hello, world!" );
                 printf( "%s\n", strtrm(buf) );


    STRTTS
    -------------------------------------------------------------------------

        Summary  Expands tabs to spaces

        Syntax   char *strtts(const char *s, int n);

        Remarks  Expands all tabs in string s to spaces using a width n.
                 It returns a pointer to a newly allocated string which
                 contains the string with the tabs converted to appropriate
                 number of spaces. The caller is responsible for freeing the
                 resulting string.

        Return	 Dynamically allocated string or NULL if memory failure

        Example  ptr = strtts(buf,"This\tis some\t\t test here",4);
                 if( ptr )
                 {
                     printf( "%s\n", ptr );
                     free( ptr );
                 }


    STRVCAT
    -------------------------------------------------------------------------

        Summary  Concatenates multiple strings

        Syntax   char *strvcat(char *s, ...);

        Remarks  Concatenates a NULL-terminated list of strings into a new
                 string that is allocated by the function. Failure to specify
                 NULL as the last entry in the list will certainly crash the
                 system as the function will go into an infinte loop. Don't
                 forget that this is a concatenation function and if you give
                 it a non-initialized buffer, the results are unpredictable.
                 It is acceptable, however, to pass NULL as the s parameter,
                 then it will simply be ignored. Freeing of the resulting
                 buffer is the responsibility of the caller.

        Return   On success, returns a pointer to the new string
                 On error, returns NULL

        Example  char *ptr;
                 ptr = strvcat("Hello", ",", " w", "orld", "!", (char *)0);
                 if( ptr )
                 {
                     printf( "%s\n", ptr );
                     free( ptr );
                 }

