String Manipulation

This page is going to cover a variety of the tools available for string manipulation in SIMPOL both basic and more advanced. A more comprehensive list of tools can be found in your Language Guide

We are going to be looking at two different sets of functions: included ‘intrinsic’ functions and members of the stringlib library

1. Intrinsic Functions
   a. .len()
   b. .instr()
   c. .tostr()
   d. .rstr()
   e. .lstr()
   f. .substr()
   g. .like1()
2. stringlib Library
   a. ltrim
   b. rtrim
   c. lpad()
   d. rpad()
   e. space()
   f. afterstr()
   g. beforestr()
   h. parsenext()

For this tutorial instead of creating one overall program, we are going to create a small example for each function it is, of course, possible, and recommended to combine these as you need them, an example of a more advanced use case can be found in our File IO tutorial here.

.len()

This funtion returns the length of a string. It can be used like so:

function main()
    string sLine
    integer iOutput

    sLine = " this is an example string, we are going to change aspects of this: "
    iOutput = .len(sLine)
end function iOutput

This should return 76 for this particular example string, we can confirm this length by pasting the string into a program like notepad++

.instr()

This function returns the position of the first instance of the search string, more usefully if the search string is not found zero is returned. This function allows you to do if-else logic with string contents, it is also useful in some later functions which require positions as parameters. The basic function use is like so:

function main()
  string sLine
  integer iOutput                   

  sLine = "     this is an example string, we are going to change aspects of this:     "
  iOutput = .instr(sLine,"example ")
end function iOutput

This should return for our example string: 17. As previously mentioned we can use this for logical statements, an example of this is:

function main()
  string sLine
  string sSearch
  string sOutput                   

  sLine = "     this is an example string, we are going to change aspects of this:     "
  sSearch = "example"

  if .instr(sLine,sSearch) == 0
    sOutput = "String: " + sSearch + "was not found"
  else
    sOutput = "Found: " + sSearch
  end if
end function sOutput

For our example it should return Found: example but if we were to search for a string that is not present, such as “SIMPOL” we would have the other output. N.B. the search strings are all case sensitive, if case sensitivity is not desired it is possible to convert a string to all upper case (.ucase) or lower case (.lcase).

.tostr()

This function turns a number into a string in any base from 2 to 36

function main()
  number nExample
  string sOutput
  
  nExample = 31415                  
  sOutput = .tostr(nExample,10)

end function sOutput

The output for this example should be the same number you put into it, as the conversion is not apparent in the console output. To prove the type conversion as an output you can use the function sOutput.type this should then output string

.rstr() and .lstr()

This pair of functions extracts characters from the left and right of the string. In our function we are gonna take the first and last 30 characters of our string and then output those 60 characters

function main()
  string sLine
  string sLeft
  string sRight
  string sOutput
  
  sLine = "     this is an example string, we are going to change aspects of this:     "
  sLeft = .lstr(sLine,30)
  sRight = .rstr(sLine,30)

  sOutput = sLeft + sRight
end function sOutput

This should output the following with our example string:" this is an example stringo change aspects of this: "

ltrim() and rtrim()

This is another pair of functions, this time they remove all spaces from the left and right of the string.

function main()
  string sLine
  string sOutput
  integer iBefore
  integer iAfter
  
  sLine = "     this is an example string, we are going to change aspects of this:     "
  iBefore = .len(sLine)
  sLine = ltrim(sLine)
  sLine = rtrim(sLine)
  iAfter = .len(sLine)
  sOutput = "Length before trim: " + .tostr(iBefore,10) + ". Length after trim: " + .tostr(iAfter,10)
end function sOutput

This makes use of several things we’ve already seen. We are first finding the length of our example string before we get rid of the blank spaces before and after using our ltrim and rtrim functions. Then we get the length after this happened. The last line makes use of the .tostr() function as well as the + to append various strings together to get a nicely formatted output: Length before trim: 76. Length after trim: 66

lpad, rpad and space

This group of functions is a more complex group of functions, it concerns itself with adding blank spaces to strings: lpad adds space (or any specified character) to the left of a string so as to make it a specified length. If the string however, is shorter than the specified length it will truncate it at that length, rpad does the exact same thing but on the right instead of the left. space is comparitively simple, it creates a string containing spaces. For this example we are going to expand on the last one, like so:

function main()
  string sLine
  string sLineAppend
  string sOutput
  
  sLine = "     this is an example string, we are going to change aspects of this:     "
  sLineAppend = "like adding things to the end of the string"
  sLine = ltrim(sLine)
  sLine = rtrim(sLine)
  sLine = lpad(sLine,.len(sLine) + 5,"-")
  sLineAppend = rpad(sLineAppend,.len(sLineAppend) + 5,"-")
  sOutput = sLine + space(5) + sLineAppend
end function sOutput

The code above trims our original string, as before. We then want to add five “-” to the beginning of the string, to do this we are going to make use of lpad. The length is going to have to be equal to the string length + 5, this is done using the following code:.len(sLine) + 5 as well as specify the replacement character as our symbol. We then want to do the exact same but to our second string. Finally we are going to append our two strings together but add spaces inbetween the two, this we’re going to do using the space function. The output for this should be as follows -----this is an example string, we are going to change aspects of this: like adding things to the end of the string-----

afterstr() & beforestr()

This pair of functions expands on .rstr(), .lstr() and .instr to trim before or after a search string. In our example we are going to trim before the comma, and after the word ‘change’.

function main()
  string sLine
  string sBefore
  string sAfter
  string sOutput
  
  sLine = " this is an example string, we are going to change aspects of this: "
  sBefore = beforestr(sLine,",")
  sAfter = afterstr(sLine,"change")
  sOutput = "Before ',': " + sBefore + ". After 'change': " + sAfter
end function sOutput

This function can be incredibly powerful when used correctly.

.substr()

This function extracts characters from a specified starting position

function main()
  string sLine
  string sSubstr
  string sOutput
  integer iPos
  integer iLen

  iPos = 20
  iLen = 10
  sLine = "     this is an example string, we are going to change aspects of this:     "
  sSubstr = .substr(sLine,iPos,iLen)
  sOutput = "Substring starting at position " + .tostr(iPos,10) + " with length of " + .tostr(iLen,10) + "is: " + sSubstr
end function sOutput

.like1()

This function attempts to find a pattern in a string. The matching occurs on a character by character basis and it is only considered a match if every character in the string matches the pattern and there are no excess characters. For more information on special matching patterns read this

function main()
  string sLine
  string sOutput
  sLine = "example@gmail.com"
  if .like1(sLine,"*?@?*.???") == .true
      sOutput = "Valid email address with a three letter domain name: " + .rstr(sLine,3)
  end if
end function sOutput

Our example here is a very basic email checker. The pattern looks for any number of characters (but there must be at least one) before the @ and again after it. After the full stop (period) it will attempt to find an address which has a three letter domain name. This is not the most comprehensive testing tool but it is a nice proof of concept for this tutorial

parsenext()

This function is an evolution of .substr it extracts a substr from given beginning and end characters.

function main()
  string sLine
  string sOutput

  sLine = "     this is an example string, we are going to change aspects of this:     "
  sOutput = parsenext(sLine,",",":")
end function sOutput

This function outputs exactly what is expected of it: we are going to change aspects of this it has cut off everything before the comma and everything after the colon

---

Intrinsic String Functions (Old)

stringlib (Old)