Latest revision as of 12:07, 11 February 2019

String manipulation is the building block of many of today's utilities and algorithms. Everything from formatting and validation to analysis and manipulation requires heavy use of string manipulation. Fortunately for you, the language provides powerful string manipulation facilities.

Basic String Operations[edit]

Since everything is a string in mSL, just assigning it to a variable is enough.

var %x = This is an example string.

We often want to get the length of such string. The $len identifier can be used to get that.

//echo -a $len(apples and oranges)
18

It is often desired to join two strings together. Such operation is called a string concatenation. The $+ operator can be used to concatenate two string together. For example:

//echo -a A $+ B
AB

It's important to note that both identifiers and variables can be substituted instead of A and B. For example:

alias hello {
  var %x = Hello World
  var %x = %x $+ !
  echo -a %x
}

The output after executing the above code (/hello) is "Hello World!"

Substrings[edit]

A substring is a string that is part of a longer string. There are a number of built-in identifiers that can be used to retrieve a smaller portion of the original string.

$left() and $right()[edit]

The first two identifiers you should be familiar with are the $left and $right identifiers which can be used to return the left or right most part of the original string respectably. Their syntax is:

$left(<string>, <length>)
$right(<string>, <length>)

$left always return text starting from the very left side while $right always return text starting from the right side.

If the length specified is a positive number, $left and $right will return up to that many characters from their respective sides. For example:

//echo -a $left(abcdefg, 4) $right(abcdefg, 4)
;Left: |abcd|efg
;Right: abc|defg|

If the length specified is a negative number, $left and $right return the entire text minus that many characters from their respective sides. For example:

//echo -a $left(abcdefg, -4) $right(abcdefg, -4)
;Left: |abc|defg
;Right: abcd|efg|

Here is one last example before we move on:

echo -a $left(Hello There!, 5) $right(Hi World!, 6)

This gets the five left-most characters ("Hello") and the five right-most characters ("World!"). The final output is:

Hello World!

$mid()[edit]

$left() and $right() are great but they can get a little complicated if you want to get a substring from the middle of the string. For such cases, the $mid() identifier is a more powerful alternative. $mid() has the following syntax:

$mid(<string>, <start>)
$mid(<string>, <start>, <length>)

Start is the start of the substring from the left. A negative value indicates a start from the right. In both case, an optional length can be specified. A negative length can be used to remove that many characters from the end.

alias example {
  var %str = I have not failed. I've just found 10,000 ways that won't work.
  echo -a $mid(%str, 53, 10)
}

Will output "won't work".

Case Transformation[edit]

The $islower and $isupper identifiers can be used to determine if a string is entirely made up of uppercase or lowercase letters ($true), or else they return $false. The same functionality is also built into an if statement using the isupper and islower operators. The $upper and $lower identifiers perform case conversion on an entire string or a string character.

alias case_example {
  var %x = Some random line!
  echo -a %x = $isupper(%x) $islower(%x)
  var %x = $upper(%x)
  echo -a %x = $isupper(%x) $islower(%x)
  var %x = $lower(%x)
  echo -a %x = $isupper(%x) $islower(%x)
}

Will generate the following output:

Some random line! = $false $false
SOME RANDOM LINE! = $true $false
some random line! = $false $true

$lower() and $upper()[edit]

The $lower() and $upper() identifiers can be used to transform the entire string into uppercase or lowercase letters. For example:

//echo -a $upper(HeLlO tHeRe)
//echo -a $lower(HeLlO tHeRe)

Will produce:

HELLO THERE
hello there

Searching[edit]

There are a number of identifiers that can be used to search for a substring within a string. The first one is the $pos identifier which has the following syntax:

$pos(<string>, <substring>)
$pos(<string>, <substring>, <occurrence>)

The first variation returns the position of the first instance of the substring. If the substring is found multiple times within the string, you can specify the Nth occurrence you want. If you specify 0 for the occurrence, $pos will return the total number of substring found within the string.

Note: $poscs is a case-sensitive version of $pos; it has the same syntax.

If you simply want to count the number of occurrences a list of substring is found in the string, you can use the $count identifier instead. It's syntax is as follows:

$count(<string>, <substring>[, <substring2>, ...])

Multiple substrings can be counted at once. Here is a simple example:

$count(Apples and Oranges, apple, orange)

Which will print "2".

Note: $countcs is a case-sensitive version of $count; it has the same syntax.

Substring Replacement and Removal[edit]

Replacement[edit]

There are two built-in string replacement identifiers, $replace and $replacex. The major difference between the two is that the later one will not apply replacement to any of the replaced strings.

It should be noted that both will replace ALL ocurrences of a substring within a string, not just the 1st encountered.

The syntax for both of them is:

$replace(<string>, <substring>, <replacement>[, <substring2>, <replacement2>, ...])
$replacex(<string>, <substring>, <replacement>[, <substring2>, <replacement2>, ...])

Let's start off with a small example:

echo -a $replace(Hello World!, world, there)

Which will print "Hello there!". Below is a simple example. Note the difference between $replace and $replacex.

alias rep {
  var %str = 1 2 3 4
  ; Each replacement will replace the previous one
  echo -a $replace(%str, 1, 2, 2, 3, 3, 4, 4 , 5)
  ; Exclusive replacements
  echo -a $replacex(%str, 1, 2, 2, 3, 3, 4, 4, 5)
}

Executing /rep will produce the following results:

5 5 5 5
2 3 4 5

An example of replacing ALL occurances can be seen in:

//echo -s $replace(This is a test of the replace function, $chr(32), .)

which will output (in this case to the status window [-s]):

This.is.a.test.of.the.replace.function

$replacex will provide the same in this case.

Note: $replacecs/$replacexcs are case-sensitive versions of $replace/$replacex; it has the same syntax.

Substring Removal[edit]

$remove is an identifier that can remove all occurrences of the substrings from the string. The syntax is:

$remove(<string>, <substring>[, <substring2>, <substring3>, ...])

A small example is:

//echo -a $remove(aa bb cc dd ee aa bb cc dd ee, bb, dd)

Produces:

aa cc ee aa cc ee

Miscellaneous Identifiers[edit]

Two more identifiers you should be aware of are $str() and $strip().

$str()[edit]

$str returns the same exact string repeated N amount of times. The syntax is:

$str(<string>, <N>)

For example:

//echo -a $str(Example, 10)

Produces:

ExampleExampleExampleExampleExampleExampleExampleExampleExampleExample

$strip()[edit]

The $strip identifier can remove control codes from a string. The syntax for it is:

;Removes all control codes (bold/underline/italics/color/reverse)
$strip(<string>)
;Removes any combination of control codes
$strip(<string>, buricmo)

• b = bold
• u = underline
• r = reverse
• i = italics
• c = color
• m = use messages option settings

Using Token Manipulation[edit]

Whilst the token manipulation functionality is designed to be used for maintaining lists of delimited tokens, they can also be used for string manipulation. For example, extracting a channel from a string can be done with:

//echo -a # $+ $gettok($gettok(Why not join #superheros now?,2,35),1,32)
#superheros