ANSI C String Library

The mikroC PRO for PIC provides a set of standard ANSI C library functions useful for manipulating strings and RAM memory.

  Important :

Library Functions

memchr

Prototype

void *memchr(void *p, char n, unsigned int v);

Description

Function locates the first occurrence of char n in the initial v bytes of memory area starting at the address p. The function returns the pointer to this location or 0 if the n was not found.

For parameter p you can use either a numerical value (literal/variable/constant) indicating memory address or a dereferenced value of an object, for example &mystring or &PORTB.

Example
char txt[] = "mikroElektronika";
res = memchr(txt, 'e', 16);  // example locates first occurrence of the letter 'e' in the string 'txt' in the first 16 characters of the string

memcmp

Prototype

int memcmp(void *s1, void *s2, int n);

Description

Function compares the first n characters of objects pointed to by s1 and s2 and returns zero if the objects are equal, or returns a difference between the first differing characters (in a left-to-right evaluation). Accordingly, the result is greater than zero if the object pointed to by s1 is greater than the object pointed to by s2 and vice versa.

Example
char txt[] = "mikroElektronika";
char txt_sub[] = "mikro;

res = memcmp(txt, txt_sub, 16);  // returns 69, which is ASCII code of the first differing character - letter 'E'

memcpy

Prototype

void *memcpy(void *d1, void *s1, int n);

Description

Function copies n characters from the object pointed to by s1 into the object pointed to by d1. If copying takes place between objects that overlap, the behavior is undefined. The function returns address of the object pointed to by d1.

Example
char txt[] = "mikroElektronika";
char txt_sub[] = "mikr;

res = memcpy(txt+4, txt_sub, 4);  // string 'txt' will be populated with the first 4 characters of the 'txt_sub' string, beginning from the 4th character
                                  // routine returns the address of the first populated character, if memory areas of the strings don't overlap

memmove

Prototype

void *memmove(void *to, void *from, int n);

Description

Function copies n characters from the object pointed to by from into the object pointed to by to. Unlike memcpy, the memory areas to and from may overlap. The function returns address of the object pointed to by to.

Example
char txt[] = "mikroElektronika";
char txt_sub[] = "mikr;

res = memmove(txt+7, txt_sub, 4);  // string 'txt' will be populated with first 4 characters of the 'txt_sub' string, beginning from the 7th character
                                  // routine returns the address of the first populated character (memory areas of the object may overlap)

memset

Prototype

void *memset(void *p1, char character, int n);

Description

Function copies the value of the character into each of the first n characters of the object pointed by p1. The function returns address of the object pointed to by p1.

Example
char txt[] = "mikroElektronika";

memset(txt, 'a', 2);  // routine will copy the character 'a' into each of the first 'n' characters of the string 'txt', 

strcat

Prototype

char *strcat(char *to, char *from);

Description

Function appends a copy of the string from to the string to, overwriting the null character at the end of to. Then, a terminating null character is added to the result. If copying takes place between objects that overlap, the behavior is undefined. to string must have enough space to store the result. The function returns address of the object pointed to by to.

Example
char txt[] = "mikroElektronika";
char *res;

txt[3] = 0;
res = strcat(txt, "_test");  // routine will append the '_test' at the place of the first null character, adding terminating null character to the result
                             // routine returns the address of the 'txt' string

strchr

Prototype

char *strchr(char *ptr, char chr);

Description

Function locates the first occurrence of character chr in the string ptr. The function returns a pointer to the first occurrence of character chr, or a null pointer if chr does not occur in ptr. The terminating null character is considered to be a part of the string.

Example
char txt[] = "mikroElektronika";
char *res;

res = strchr(txt, 'E');  // routine will locate the character 'E' in the 'txt' string, and return the address of the character

strcmp

Prototype

int strcmp(char *s1, char *s2);

Description

Function compares strings s1 and s2 and returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation). Accordingly, the result is greater than zero if s1 is greater than s2 and vice versa.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro";
int res;

res = strcmp(txt,txt_sub);  // compares strings 'txt' and 'txt_sub' and returns returns a difference between the first differing characters, in this case 69 

strcpy

Prototype

char *strcpy(char *to, char *from);

Description

Function copies the string from into the string to. If copying is successful, the function returns to. If copying takes place between objects that overlap, the behavior is undefined.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro_test";
int res;

res = strcpy(txt,txt_sub);  // copies string 'txt_sub' to 'txt'

strlen

Prototype

int strlen(char *s);

Description

Function returns the length of the string s (the terminating null character does not count against string’s length).

Example
char txt = "mikroElektronika";
int result;

result = strlen(txt);  // calculates the length of the 'txt' string, result = 16

strncat

Prototype

char *strncat(char *to, char *from, int size);

Description

Function appends not more than size characters from the string from to to. The initial character of from overwrites the null character at the end of to. The terminating null character is always appended to the result. The function returns to.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro";
char *result;

txt[5] = 0;
result = strncat(txt,txt_sub,4);  // routine appends first 4 characters from the string 'txt_sub' at the place of first null character in the 'txt' string

strncpy

Prototype

char *strncpy(char *to, char *from, int size);

Description

Function copies not more than size characters from string from to to. If copying takes place between objects that overlap, the behavior is undefined. If from is shorter than size characters, then to will be padded out with null characters to make up the difference. The function returns the resulting string to.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro_test";
int res;

res = strncpy(txt,txt_sub,4);  // copies first 4 characters form the string 'txt_sub' to 'txt'

strspn

Prototype

int strspn(char *str1, char *str2);

Description

Function returns the length of the maximum initial segment of str1 which consists entirely of characters from str2. The terminating null character at the end of the string is not compared.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro_test";
int res;

result = strspn(txt,txt_sub);  // routne returns 4

strncmp

Prototype

int strncmp(char *s1, char *s2, char len);

Description

Function lexicographically compares not more than len characters (characters that follow the null character are not compared) from the string pointed by s1 to the string pointed by s2. The function returns a value indicating the s1 and s2 relationship:

Value     Meaning
< 0       s1 "less than" s2
= 0       s1 "equal to" s2
> 0       s1 "greater than" s2
Example
char txt = "mikroElektronika";
char txt_sub = "mikro";
int res;

res = strncmp(txt_sub,txt,3);  // compares the first 3 characters from the string 'txt' with the sting 'txt_sub' and returns a difference

strstr

Prototype

char *strstr(char *s1, char *s2);

Description

Function locates the first occurrence of the string s2 in the string s1 (excluding the terminating null character).

The function returns pointer to first occurrence of s2 in s1; if no string was found, function returns 0. If s2 is a null string, the function returns 0.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro";
char *res;

res = strstr(txt,txt_sub);

strcspn

Prototype

char *strcspn(char * s1, char *s2);

Description

Function computes the length of the maximum initial segment of the string pointed to by s1 that consists entirely of characters that are not in the string pointed to by s2.

The function returns the length of the initial segment.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro";
char *res;

res = strcspn(txt_sub,txt);

strpbrk

Prototype

char *strpbrk(char * s1, char *s2);

Description

Function searches s1 for the first occurrence of any character from the string s2. The terminating null character is not included in the search. The function returns pointer to the matching character in s1. If s1 contains no characters from s2, the function returns 0.

Example
char txt = "mikroElektronika";
char txt_sub = "mikro";
char *res;

res = strpbrk(txt_sub,txt);

strrchr

Prototype

char *strrchr(char * ptr, char chr);

Description

Function searches the string ptr for the last occurrence of character chr. The null character terminating ptr is not included in the search. The function returns pointer to the last chr found in ptr; if no matching character was found, function returns 0.

Example
char txt = "mikroElektronika";

res = strrchr(txt_sub,'k');  // returns the pointer to the 'k' character of the 'txt' string

strtok

Prototype

char * strtok(char * s1, char * s2);

Returns

The strtok function returns a pointer to the first character of a token, or a null pointer if there is no token.

Description

A sequence of calls to the strtok function breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2. The first call in the sequence has s1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 may be different from call to call.

The first call in the sequence searches the string pointed to by s1 for the first character that is not contained in the current separator string pointed to by s2. If no such character is found, then there are no tokens in the string pointed to by s1 and the strtok function returns a null pointer. If such character is found, it is the start of the first token.

The strtok function then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by s1, and subsequent searches for a token will return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token. The strtok function saves a pointer to the following character, from which the next search for a token will start.

Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.

Example
char x[10] ;

void main(){

 strcpy(x, strtok("mikroEl", "Ek"));
 strcpy(x, strtok(0, "kE"));

}
Copyright (c) 2002-2012 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries? 
Find them on LibStock - A place for the code