String Library

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

Library Functions

memchr
memcmp
memcpy
memmove
memset
strcat
strcat2
strchr
strcmp
strcpy
strlen
strncat
strncpy
strspn
strncmp
strstr
strcspn
strpbrk
strrchr
ltrim
rtrim
strappendpre
strappendsuf
length

memchr

Prototype

Prototype	sub function memchr(dim p as ^byte, dim ch as byte, dim n as word) as word
Description	The function locates the first occurrence of the byte `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

sub function memchr(dim p as ^byte, dim ch as byte, dim n as word) as word

Description

The function locates the first occurrence of the byte 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

Prototype	sub function memcmp(dim p1, p2 as ^byte, dim n as word) as 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'

sub function memcmp(dim p1, p2 as ^byte, dim n as word) as 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

Prototype	sub procedure memcpy(dim p1, p2 as ^byte, dim nn as 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

sub procedure memcpy(dim p1, p2 as ^byte, dim nn as 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

Prototype	sub procedure memmove(dim p1, p2, as ^byte, dim nn as 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

sub procedure memmove(dim p1, p2, as ^byte, dim nn as 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

Prototype	sub procedure memset(dim p as ^byte, dim character as byte, dim n as 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",

sub procedure memset(dim p as ^byte, dim character as byte, dim n as 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	sub procedure strcat(dim byref s1, s2 as 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	sub procedure strcat2(dim byref l, s1, s2 as 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	dim txt as string[16] txt_sub as string[5] l as string[21] strcat2(l, txt, txt_sub) ' routine will adjoin strings txt and txt_sub and place the result into l

strchr

Prototype

Prototype	sub function strchr(dim byref s as string, dim ch as byte) as 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

sub function strchr(dim byref s as string, dim ch as byte) as 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

Prototype	sub function strcmp(dim byref s1, s2 as string) as 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

sub function strcmp(dim byref s1, s2 as string) as 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	sub procedure strcpy(dim byref s1, s2 as 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	sub function strlen(dim byref s as string) as 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	sub procedure strncat(dim byref s1, s2 as string, dim size as 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	sub procedure strncpy(dim byref s1, s2 as string, dim size as 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

Prototype	sub function strspn(dim byref s1, s2 as string) as 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

sub function strspn(dim byref s1, s2 as string) as 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

Prototype	sub function strncmp(dim byref s1, s2 as string, dim len as byte) as 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

sub function strncmp(dim byref s1, s2 as string, dim len as byte) as 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

Prototype	sub function strstr(dim byref s1, s2 as string) as 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)

sub function strstr(dim byref s1, s2 as string) as 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

Prototype	sub function strcspn(dim byref s1, s2 as string) as 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)

sub function strcspn(dim byref s1, s2 as string) as 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	sub function strpbrk(dim byref s1, s2 as string) as 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	sub function strrchr(dim byref s as string, dim ch as byte) as 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	sub procedure ltrim(dim byref astring as 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	sub procedure rtrim(dim byref astring as 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	sub procedure strappendpre(dim letter as char, dim byref s1 as 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	sub procedure strappendsuf(dim byref s1 as string, dim letter as 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	sub function length(dim byref s as string) as word
Description	The function returns length of passed string.
Example	txt = "mikroE" res = length(txt) ' calculates and returns the length of the 'txt' string

Want more examples and libraries?
Find them on