/** @file  ../include/string.h

@internalComponent

*/

/** @fn  memccpy(void *t, const void *f, int c, size_t n)

@param t

@param f

@param c

@param n

@return   memccpy function returns a pointer to the next character in t after c, or NULL if c was not found in the first n characters of f.

  The memccpy function

copies bytes from string f to string t. If the character c (as converted to an unsigned char) occurs in the string f, the copy stops and a pointer to the byte after the copy of c in the string t is returned.

Otherwise, n bytes are copied, and a NULL pointer is returned.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50] = {"\0"};

    (void) memccpy(one, "abcdefgh",8,3);

    printf("String after memcpy %s

",one);

    (void) memccpy(one, "Hello",5,1);

    printf("String after memcpy %s

",one);

    return 0;

}

@endcode

 Output

@code

String after memcpy abc

String after memcpy Hbc

@endcode

@see bcopy()

@see memcpy()

@see memmove()

@see strcpy()

@publishedAll

@externallyDefinedApi

*/

/** @fn  memchr(const void *s, int c, size_t n)

@param s

@param c

@param n

@return   The memchr function

returns a pointer to the byte located,

or NULL if no such byte exists within n bytes.

  The memchr function

locates the first occurrence of c (converted to an unsigned char)

in string s.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50];

    char* ret;

    strcpy(one,"abcd");

    ret = memchr("abcd", ’c’,4);

    if(!strncmp(one+2,ret,1)) printf("\ ’c\ ’ found in string \"abcd\"\n");

    ret = memchr(one, ’z’,4);

    if(ret == NULL) printf("\ ’z\ ’ not found in string \"abcd\"\n");           

    return 0;

}

@endcode

 Output

@code

 ’c’ found in string "abcd"

 ’z’ not found in string "abcd"

@endcode

@see strchr()

@see strcspn()

@see strpbrk()

@see strsep()

@see strstr()

@see strtok()

@publishedAll

@externallyDefinedApi

*/

/** @fn  memcmp(const void *s1, const void *s2, size_t n)

@param s1

@param s2

@param n

@return   The memcmp function

returns zero if the two strings are identical,

otherwise returns the difference between the first two differing bytes

(treated as unsigned char values, so that '\\200'

is greater than '\\0'

for example).

Zero-length strings are always identical.

  The memcmp function

compares byte string s1 against byte string s2. Both strings are assumed to be n bytes long.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

   char str1[]  = "abcdefg";

   char str2[] =  "abcdefr";

   int result;

   printf( "Compare ’%.6s’ to ’%.6s\n", str1, str2 );

   result = memcmp( str1, str2, 6);

   if( result < 0 )

      printf( "str1 is less than str2.\n" );

   else if( result == 0 )

      printf( "str1 is equal to str2.\n" );

   else if( result > 0 )

      printf( "str1 is greater than str2.\n" );

   printf( "Compare ’%.7s’ to ’%.7s\n", str1, str2 );

   result = memcmp( str1, str2, 7 );

   if( result < 0 )

      printf( "str1 is less than str2.\n" );

   else if( result == 0 )

      printf( "str1 is equal to str2.\n" );

   else if( result > 0 )

      printf( "str1 is greater than str2.\n" );

   return 0;    

}

@endcode

 Output

@code

Compare ’abcdef’ to ’abcdef

str1 is equal to str2.

Compare ’abcdefg’ to ’abcdefr

str1 is less than str2.

@endcode

@see bcmp()

@see strcasecmp()

@see strcmp()

@see strcoll()

@see strxfrm()

@publishedAll

@externallyDefinedApi

*/

/** @fn  memcpy(void *dst, const void *src, size_t len)

@param dst

@param src

@param len

@return   The memcpy function

returns the original value of dst.

  The memcpy function

copies len bytes from string src to string dst.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50] = {"\0"};

    (void) memcpy(one, "abcdefgh",8);

    printf("String after memcpy %s

",one);

    (void) memcpy(one, "Hello",5);

    printf("String after memcpy %s

",one);

    return 0;   

}

@endcode

 Output

@code

String after memcpy abcdefgh

String after memcpy Hellofgh

@endcode

@see bcopy()

@see memccpy()

@see memmove()

@see strcpy()

@publishedAll

@externallyDefinedApi

*/

/** @fn  memmove(void *dst, const void *src, size_t len)

@param dst

@param src

@param len

  The memmove function copies len bytes from string src to string dst. The two strings may overlap. The copy is always done in a non-destructive 

manner.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50];

    (void) strcpy(one, "abcdefgh");

    printf("String before memmove %s

",one);

    (void) memmove(one+1, "xyz", 2);

    printf("String after memmove %s

",one);

    (void) strcpy(one, "abcdefgh");

    printf("String before memmove %s

",one);

    (void) memmove(one+1, "xyz", 0);

    printf("String after memmove %s

",one);

    return 0;   

}

@endcode

 Output

@code

String before memmove abcdefgh

String after memmove axydefgh

String before memmove abcdefgh

String after memmove abcdefgh

@endcode

@return   The memmove function returns pointer to dst dst.

@see bcopy()

@see memcpy()

@see strcpy()

@publishedAll

@externallyDefinedApi

*/

/** @fn  memset(void *dst0, int c0, size_t length)

@param dst0

@param c0

@param length

  The memset function

writes length bytes of value c0 (converted to an unsigned char) to the string dst0.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50];       

    strcpy(one, "abcdefgh");

    printf("String before memset %s

",one);

    memset(one+1, 'x', 3);

    printf("String after calling memset first time %s

",one);          

    memset(one+2, 'y', 0);

    printf("String after calling memset second time %s

",one);

    return 0;   

}

@endcode

 Output

@code

String before memset abcdefgh

String after calling memset first time axxxefgh

String after calling memset second time axxxefgh

@endcode

@return   The memset function returns its first argument.

@see bzero()

@see swab()

@publishedAll

@externallyDefinedApi

*/

/** @fn  stpcpy(char *to, const char *from)

@param to

@param from

Note: This description also covers the following functions -

 strcpy()  strncpy() 

@return   The strcpy and strncpy functions

return to. The stpcpy function returns a pointer to the terminating ‘\\0’

character of to.

  The stpcpy and strcpy functions

copy the string from to to (including the terminating ‘\\0’

character.)

 The strncpy function copies at most len characters from from into to. If from is less than len characters long,

the remainder of to is filled with '\\0'

characters.

Otherwise, to is not terminated.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50] = {"abcdefgh"};        

    printf("String before strcpy %s

",one);

    strcpy(one,"Hello");

    printf("String after strcpy %s

",one);

    strncpy(one + 5, " ",1);

    strncpy(one + 6, "World",5);

    printf("String after strncpy %s

",one);

    return 0;   

}

@endcode

 Output

@code

String before strcpy abcdefgh

String after strcpy Hello

String after strncpy Hello World

@endcode

Examples:

 The following sets chararray to "abc\\0\\0\\0"

@code

char chararray[6];

(void)strncpy(chararray, "abc", sizeof(chararray));

@endcode

 The following sets chararray to "abcdef:"

@code

char chararray[6];

(void)strncpy(chararray, "abcdefgh", sizeof(chararray));

@endcode

 Note that it does not NULL terminate chararray because the length of the source string is greater than or equal

to the length argument. The following copies as many characters from input to buf as will fit and NULL terminates the result.

Because strncpy does not guarantee to NULL terminate the string itself, this must be done explicitly.

@code

char buf[1024];

(void)strncpy(buf, input, sizeof(buf) - 1);

buf[sizeof(buf) - 1] = ’\0’;

@endcode

Security considerations:

 The strcpy function is easily misused in a manner which enables malicious users

to arbitrarily change a running program's functionality through a

buffer overflow attack.

@see bcopy()

@see memcpy()

@see memmove()

@publishedAll

@externallyDefinedApi

*/

/** @fn  strcasestr(const char *s, const char *find)

@param s

@param find

Refer to  strstr() for the documentation

@see memchr()

@see strchr()

@see strcspn()

@see strpbrk()

@see strrchr()

@see strsep()

@see strspn()

@see strtok()

@publishedAll

@externallyDefinedApi

*/

/** @fn  strcat(char *  s, const char *  append)

@param s

@param append

Note: This description also covers the following functions -

 strncat() 

@return   The strcat and strncat functions

return the pointer s.

  The strcat and strncat functions

append a copy of the null-terminated string append to the end of the null-terminated string s, then add a terminating ‘\\0’

The string s must have sufficient space to hold the result.

 The strncat function

appends not more than count characters from append, and then adds a terminating ‘\\0’

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

    char one[50] = {"\0"};              

    strcpy(one,"Hello");

    strcat(one," World");

    printf("Concatenated String %s

",one);

    return 0;   

}

@endcode

 Output

@code

Concatenated String Hello World

@endcode

Security considerations:

 The strcat function is easily misused in a manner

which enables malicious users to arbitrarily change

a running program's functionality through a buffer overflow attack. Avoid using strcat. Instead, use strncat or strlcat and ensure that no more characters are copied to the destination buffer

than it can hold. Note that strncat can also be problematic.

It may be a security concern for a string to be truncated at all.

Since the truncated string will not be as long as the original,

it may refer to a completely different resource

and usage of the truncated resource

could result in very incorrect behavior.

Example:

@see bcopy()

@see memcpy()

@see memmove()

@see strcpy()

@publishedAll

@externallyDefinedApi

*/

/** @fn  strchr(const char *s, int c)

@param s

@param c

Note: This description also covers the following functions -

 strrchr() 

@return   The functions strchr and strrchr return a pointer to the located character, or NULL if the character does not appear in the string.

  The strchr function locates the first occurrence of c (converted to a char)

in the string pointed to by s. The terminating null character is considered part of the string;

therefore if c is ‘\\0’

the functions locate the terminating ‘\\0’

 The strrchr function is identical to strchr except it locates the last occurrence of c.

Examples:

@code

#include <string.h>

#include <stdio.h>

int main()

{

        char one[50];

        char* ret;

        strcpy(one,"abcd");

        ret = strchr("abcd", 'c');

        if(!strncmp(one+2,ret,1)) printf("\ 'c\ ' found in string \"abcd\"

");

        ret = strchr(one, 'z');

        if(ret == NULL) printf("\ 'z\ ' not found in string \"abcd\"

");               

        return 0;

}

@endcode

 Output

@code

 ’c’ found in string "abcd"

 ’z’ not found in string "abcd"

@endcode

@see memchr()

@see strcspn()

@see strpbrk()

@see strsep()

@see strspn()

@see strstr()

@see strtok()