String Library

mikroPascal PRO for dsPIC30/33 and PIC24 includes a library which automatizes string related tasks.

Library Functions

memchr

Prototype

function memchr(p : ^byte; ch : byte; n : word) : word;

Description

The function locates the first occurrence of the word ch in the initial n words of memory area starting at the address p. The function returns the offset of this occurrence from the memory address p or 0xFFFF if ch was not found.

For the 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
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

function memcmp(p1, p2 : ^byte; n : word) : integer;

Description

The function returns a positive, negative, or zero value indicating the relationship of first n words of memory areas starting at addresses p1 and p2.

This function compares two memory areas starting at addresses p1 and p2 for n words and returns a value indicating their relationship as follows:

Value     Meaning
< 0       p1 "less than" p2
= 0       p1 "equal to" p2
> 0       p1 "greater than" p2

The value returned by the function is determined by the difference between the values of the first pair of words that differ in the strings being compared.

For parameters p1 and p2 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
txt := 'mikroElektronika';
txt_sub := 'mikro';

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

memcpy

Prototype

procedure memcpy(p1, p2 : ^byte; nn : word);

Description

The function copies nn words from the memory area starting at the address p2 to the memory area starting at p1. If these memory buffers overlap, the memcpy function cannot guarantee that words are copied before being overwritten. If these buffers do overlap, use the memmove function.

For parameters p1 and p2 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
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

memmove

Prototype

procedure memmove(p1, p2 : ^byte; nn : word);

Description

The function copies nn words from the memory area starting at the address p2 to the memory area starting at p1. If these memory buffers overlap, the Memmove function ensures that the words in p2 are copied to p1 before being overwritten.

For parameters p1 and p2 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
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

memset

Prototype

procedure memset(p : ^byte; character : byte; n : word);

Description

The function fills the first n bytes in the memory area starting at the address p with the value of word character.

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

procedure strcat(var s1, s2 : string);

Description

The function appends the value of string s2 to string s1 and terminates s1 with a null character.

Example
txt := 'mikroElektronika';

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

strcat2

Prototype

procedure strcat2(var l1, s1, s2 : string);

Description

The procedure adjoins string s2 at the end of the string s1, or at the first null character of the s1, and places the result string into l string.

Example
txt := 'mikroElektronika';
txt_sub := '_Test';
l1 := string[21];

strcat2(l1, txt, txt_sub);  // routine will adjoin strings txt and txt_sub and place the result into l; l = mikroElektronika_Test

strchr

Prototype

function strchr(var s : string; ch : byte) : word;

Description

The function searches the string s for the first occurrence of the character ch. The null character terminating s is not included in the search.

The function returns the position (index) of the first character ch found in s; if no matching character was found, the function returns 0xFFFF.

Example
txt := 'mikroElektronika';

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

strcmp

Prototype

function strcmp(var s1, s2 : string) : integer;

Description

The function lexicographically compares the contents of the strings s1 and s2 and returns a value indicating their relationship:

Value    Meaning
< 0      s1 "less than" s2
= 0      s1 "equal to" s2
> 0      s1 "greater than" s2

The value returned by the function is determined by the difference between the values of the first pair of words that differ in the strings being compared.

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

procedure strcpy(var s1, s2 : string);

Description

The function copies the value of the string s2 to the string s1 and appends a null character to the end of s1.

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

strlen

Prototype

function strlen(var s : string) : word;

Description

The function returns the length, in words, of the string s. The length does not include the null terminating character.

Example
txt := 'mikroElektronika';

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

strncat

Prototype

procedure strncat(var s1, s2 : string; size : word);

Description

The function appends at most size characters from the string s2 to the string s1 and terminates s1 with a null character. If s2 is shorter than the size characters, s2 is copied up to and including the null terminating character.

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';
txt[5] := 0;

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

procedure strncpy(var s1, s2 : string; size : word);

Description

The function copies at most size characters from the string s2 to the string s1. If s2 contains fewer characters than size, s1 is padded out with null characters up to the total length of the size characters.

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

strspn

Prototype

function strspn(var s1, s2 : string) : word;

Description

The function searches the string s1 for characters not found in the s2 string.

The function returns the index of first character located in s1 that does not match a character in s2. If the first character in s1 does not match a character in s2, a value of 0 is returned. If all characters in s1 are found in s2, the length of s1 is returned (not including the terminating null character).

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

strncmp

Prototype

function strncmp(var s1, s2 : string; len : word) : integer;

Description

The function lexicographically compares the first len characters of the strings s1 and s2 and returns a value indicating their relationship:

Value     Meaning
< 0       s1 "less than" s2
= 0       s1 "equal to" s2
> 0       s1 "greater than" s2

The value returned by the function is determined by the difference between the values of the first pair of words that differ in the strings being compared (within first len words).

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

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

function strstr(var s1, s2 : string) : word;

Description

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

The function returns a number indicating the position of the first occurrence of s2 in s1; if no string was found, the function returns 0xFFFF. If s2 is a null string, the function returns 0xFFFF.

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

res := strstr(txt,txt_sub);

strcspn

Prototype

function strcspn(var s1, s2 : string) : word;

Description

The function searches the string s1 for any of the characters in the string s2.

The function returns the index of the first character located in s1 that matches any character in s2. If the first character in s1 matches a character in s2, a value of 0 is returned. If there are no matching characters in s1, the length of the string is returned (not including the terminating null character).

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

res := strcspn(txt_sub,txt);

strpbrk

Prototype

function strpbrk(var s1, s2 : string) : word;

Description

The function searches s1 for the first occurrence of any character from the string s2. The null terminator is not included in the search. The function returns an index of the matching character in s1. If s1 contains no characters from s2, the function returns 0xFFFF.

Example
txt := 'mikroElektronika';
txt_sub := 'mikr';

res := strpbrk(txt_sub,txt);

strrchr

Prototype

function strrchr(var s : string; ch : byte) : word;

Description

The function searches the string s for the last occurrence of the character ch. The null character terminating s is not included in the search. The function returns an index of the last ch found in s; if no matching character was found, the function returns 0xFFFF.

Example
txt := 'mikroElektronika';

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

ltrim

Prototype

procedure ltrim(var astring : string);

Description

The procedure trims the leading spaces of the string.

Example
txt := '  mikroE';

ltrim(txt);  // trims the leading 2 spaces of the 'txt' string

rtrim

Prototype

procedure rtrim(var astring : string);

Description

The procedure trims the trailing spaces of the string.

Example
txt := 'mikroE  ';

rtrim(txt);  // trims the trailing 2 spaces of the 'txt' string and adds terminating null character to the result

strappendpre

Prototype

procedure strappendpre(letter: char; var s1 : string);

Description

The procedure appends character at the beginning of the string.

Example
txt := 'ikroE';

strappendpre('m',txt);  // adds letter 'm' at the beginning of the 'txt' string

strappendsuf

Prototype

procedure strappendsuf(var s1 : string; letter : char);

Description

The procedure appends character at the end of the string.

Example
txt := 'mikro';

strappendsuf('E',txt);  // adds letter 'E' at the end of the 'txt' string

length

Prototype

function length(var s: string) : word;

Description

The function returns length of passed string.

Example
txt := 'mikroE';

res = length(txt);  // calculates and returns the length of the 'txt' string
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