Editing mirc/string manipulation

{{mIRC Guide}}
'''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 ==

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

<syntaxhighlight lang="mIRC">var %x = This is an example string.</syntaxhighlight>

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

<syntaxhighlight lang="mIRC">echo -a $len(apples and oranges)
;18</syntaxhighlight>

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:

<syntaxhighlight lang="mIRC">echo -a A $+ B
;AB</syntaxhighlight>

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

<syntaxhighlight lang="mIRC">alias hello {
  var %x = Hello, World
  var %x = %x $+ !
  echo -a %x
}</syntaxhighlight>

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

== Substrings ==

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() ===

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

<syntaxhighlight lang="mIRC">$left(<string>, <length>)
$right(<string>, <length>)</syntaxhighlight>

$left always return text starting from the very left side while [[$right identifier - mIRC|$right]] always return text starting from the right side.

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

<syntaxhighlight lang="mIRC">//echo -a $left(abcdefg, 4) $right(abcdefg, 4)
;Left: |abcd|efg
;Right: abc|defg|</syntaxhighlight>

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:

<syntaxhighlight lang="mIRC">//echo -a $left(abcdefg, -4) $right(abcdefg, -4)
;Left: |abc|defg
;Right: abcd|efg|</syntaxhighlight>

Here is one last example before we move on:

<syntaxhighlight lang="mIRC">echo -a $left(Hello There!, 5) $right(Hi World!, 6)</syntaxhighlight>

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

<pre>Hello World!</pre>

=== $mid() ===

[[$left identifier - mIRC|$left()]] and [[$right identifier - mIRC|$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 identifier - mIRC|$mid()]] has the following syntax: 

<syntaxhighlight lang="mIRC">$mid(<string>, <start>)
$mid(<string>, <start>, <length>)</syntaxhighlight>

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.

<syntaxhighlight lang="mIRC">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)
}</syntaxhighlight>

Will output "won't work".

== Case Transformation ==

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.

<syntaxhighlight lang="mIRC">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)
}</syntaxhighlight>

Will generate the following output:

<pre>Some random line! = $false $false
SOME RANDOM LINE! = $true $false
some random line! = $false $true</pre>

=== $lower() and $upper() ===

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

<syntaxhighlight lang="mIRC">//echo -a $upper(HeLlO tHeRe)
//echo -a $lower(HeLlO tHeRe)</syntaxhighlight>

Will produce:

<pre>HELLO THERE
hello there</pre>

== Searching ==

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:

<syntaxhighlight lang="mIRC">$pos(<string>, <substring>)
$pos(<string>, <substring>, <occurrence>)</syntaxhighlight>

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:

<syntaxhighlight lang="mIRC">$count(<string>, <substring>[, <substring2>, ...])</syntaxhighlight>

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

<syntaxhighlight lang="mIRC">$count(Apples and Oranges, apple, orange)</syntaxhighlight>

Which will print "2".

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

== Substring Replacement and Removal ==

=== Replacement ===

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

<syntaxhighlight lang="mIRC">$replace(<string>, <substring>, <replacement>[, <substring2>, <replacement2>, ...])
$replacex(<string>, <substring>, <replacement>[, <substring2>, <replacement2>, ...])</syntaxhighlight>

Let's start off with a small example:

<syntaxhighlight lang="mIRC">echo -a $replace(Hello World!, world, there)</syntaxhighlight>

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

<syntaxhighlight lang="mIRC">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)
}</syntaxhighlight>

Executing /rep will produce the following results:

<pre>5 5 5 5
2 3 4 5</pre>

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

=== Substring Removal ===

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

<syntaxhighlight lang="mIRC">$remove(<string>, <substring>[, <substring2>, <substring3>, ...])</syntaxhighlight>

A small example is:

<syntaxhighlight lang="mIRC">//echo -a $remove(aa bb cc dd ee aa bb cc dd ee, bb, dd)</syntaxhighlight>

Produces:

<pre>aa cc ee aa cc ee</pre>

== Miscellaneous Identifiers ==

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

=== $str() ===

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

<syntaxhighlight lang="mIRC">$str(<string>, <N>)</syntaxhighlight>

For example:

<syntaxhighlight lang="mIRC">//echo -a $str(Example, 10)</syntaxhighlight>

Produces: 

<pre>ExampleExampleExampleExampleExampleExampleExampleExampleExampleExample</pre>

=== $strip() ===

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

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

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

[[Category:mIRC]]