From WikiChip
Difference between revisions of "mirc/string manipulation"
< mirc

m (added wikilinks)
(Replacement)
 
(14 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{mIRC Guide}}
+
{{mirc title|String Manipulation}}
 
'''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.
 
'''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 ==
 
== Basic String Operations ==
 
 
Since everything is a string in mSL, just assigning it to a variable is enough.
 
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>
 
<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.  
+
We often want to get the length of such string. The {{mirc|$len}} identifier can be used to get that.  
  
<syntaxhighlight lang="mIRC">echo -a $len(apples and oranges)
+
<syntaxhighlight lang="mIRC">//echo -a $len(apples and oranges)
;18</syntaxhighlight>
+
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:
+
It is often desired to join two strings together. Such operation is called a '''string concatenation'''. The {{mirc|$+}} operator can be used to concatenate two string together. For example:
  
<syntaxhighlight lang="mIRC">echo -a A $+ B
+
<syntaxhighlight lang="mIRC">//echo -a A $+ B
;AB</syntaxhighlight>
+
AB</syntaxhighlight>
  
 
It's important to note that both identifiers and variables can be substituted instead of A and B. For example:
 
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 {
 
<syntaxhighlight lang="mIRC">alias hello {
   var %x = Hello, World
+
   var %x = Hello World
 
   var %x = %x $+ !
 
   var %x = %x $+ !
 
   echo -a %x
 
   echo -a %x
 
}</syntaxhighlight>
 
}</syntaxhighlight>
  
The output after executing the above code (/hello) is "Hello, World!"
+
The output after executing the above code (/hello) is "Hello World!"
  
 
== Substrings ==
 
== 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.
 
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() ===
 
=== $left() and $right() ===
 
+
The first two identifiers you should be familiar with are the {{mIRC|$left}} and {{mIRC|$right}} identifiers which can be used to return the left or right most part of the original string respectably. Their syntax is:
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>)
 
<syntaxhighlight lang="mIRC">$left(<string>, <length>)
 
$right(<string>, <length>)</syntaxhighlight>
 
$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.
+
$left always return text starting from the very left side while {{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:
+
If the length specified is a positive number, {{mIRC|$left}} and {{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)
 
<syntaxhighlight lang="mIRC">//echo -a $left(abcdefg, 4) $right(abcdefg, 4)
Line 47: Line 44:
 
;Right: abc|defg|</syntaxhighlight>
 
;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:
+
If the length specified is a negative number, {{mirc|$left}} and {{mirc|$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)
 
<syntaxhighlight lang="mIRC">//echo -a $left(abcdefg, -4) $right(abcdefg, -4)
Line 62: Line 59:
  
 
=== $mid() ===
 
=== $mid() ===
 
+
{{mirc|$left}}() and {{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 {{mirc|$mid}}() identifier is a more powerful alternative. {{mirc|$mid}}() has the following syntax:  
[[$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>)
 
<syntaxhighlight lang="mIRC">$mid(<string>, <start>)
Line 78: Line 74:
  
 
== Case Transformation ==
 
== Case Transformation ==
 
+
The {{mirc|$islower}} and {{mirc|$isupper}} identifiers can be used to determine if a string is entirely made up of uppercase or lowercase letters ({{mIRC|$true}}), or else they return {{mIRC|$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.
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 {
 
<syntaxhighlight lang="mIRC">alias case_example {
Line 97: Line 92:
  
 
=== $lower() and $upper() ===
 
=== $lower() and $upper() ===
 
+
The {{mirc|$lower}}() and {{mirc|$upper}}() identifiers can be used to transform the entire string into uppercase or lowercase letters. For example:
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)
 
<syntaxhighlight lang="mIRC">//echo -a $upper(HeLlO tHeRe)
Line 109: Line 103:
  
 
== Searching ==
 
== 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:
 
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:
  
Line 115: Line 108:
 
$pos(<string>, <substring>, <occurrence>)</syntaxhighlight>
 
$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.  
+
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, {{mirc|$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.  
+
'''Note:''' {{mirc|$poscs}} is a case-sensitive version of {{mirc|$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:
 
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:
Line 129: Line 122:
 
Which will print "2".
 
Which will print "2".
  
'''Note:''' $countcs is a case-sensitive version of $count; it has the same syntax.
+
'''Note:''' {{mirc|$countcs}} is a case-sensitive version of {{mirc|$count}}; it has the same syntax.
  
 
== Substring Replacement and Removal ==
 
== Substring Replacement and Removal ==
  
 
=== Replacement ===
 
=== Replacement ===
 +
There are two built-in string replacement identifiers, {{mirc|$replace}} and {{mirc|$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.
  
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:
+
The syntax for both of them is:
  
 
<syntaxhighlight lang="mIRC">$replace(<string>, <substring>, <replacement>[, <substring2>, <replacement2>, ...])
 
<syntaxhighlight lang="mIRC">$replace(<string>, <substring>, <replacement>[, <substring2>, <replacement2>, ...])
Line 159: Line 155:
 
2 3 4 5</pre>
 
2 3 4 5</pre>
  
'''Note:''' $replacecs/$replacexcs are case-sensitive versions of $replace/$replacex; it has the same syntax.
+
An example of replacing ALL occurances can be seen in:
 +
 
 +
<syntaxhighlight lang="mIRC">//echo -s $replace(This is a test of the replace function, $chr(32), .)</syntaxhighlight>
 +
 
 +
which will output (in this case to the status window [-s]):
 +
<pre>This.is.a.test.of.the.replace.function</pre>
 +
 
 +
$replacex will provide the same in this case.
 +
 
 +
'''Note:''' {{mirc|$replacecs}}/{{mirc|$replacexcs}} are case-sensitive versions of {{mirc|$replace}}/{{mirc|$replacex}}; it has the same syntax.
  
 
=== Substring Removal ===
 
=== Substring Removal ===
 
 
$remove is an identifier that can remove all occurrences of the substrings from the string. The syntax is:
 
$remove is an identifier that can remove all occurrences of the substrings from the string. The syntax is:
  
Line 177: Line 181:
 
== Miscellaneous Identifiers ==
 
== Miscellaneous Identifiers ==
  
Two more identifiers you should be aware of are $str() and $strip().
+
Two more identifiers you should be aware of are {{mirc|$str}}() and {{mirc|$strip}}().
  
 
=== $str() ===
 
=== $str() ===
 
 
$str returns the same exact string repeated N amount of times. The syntax is:
 
$str returns the same exact string repeated N amount of times. The syntax is:
  
Line 194: Line 197:
  
 
=== $strip() ===
 
=== $strip() ===
 
 
The $strip identifier can remove control codes from a string. The syntax for it is:
 
The $strip identifier can remove control codes from a string. The syntax for it is:
  
Line 209: Line 211:
 
* m = use messages option settings
 
* m = use messages option settings
  
[[Category:mIRC]]
+
== Using {{mirc|Token Manipulation}} ==
 +
Whilst the {{mirc|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:
 +
 
 +
<syntaxhighlight lang="mIRC">//echo -a # $+ $gettok($gettok(Why not join #superheros now?,2,35),1,32)
 +
#superheros</syntaxhighlight>
 +
 
 +
[[Category:mIRC|string manipulation]]

Latest revision as of 13: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