Core Function GSub

GSub( <string>, <pattern>, <repl>, <max> )

Description

Returns a copy of the string in which all occurrences of the pattern have been replaced by a replacement string (Or fills an array/callback function).

Parameters

string

The string to evaluate.

pattern

Go read the Patterns section on the Find( ) function to learn how to create and use patterns then come back here to put it to use on this function.

repl

Optional; Replacement

If repl is a String, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.

If repl is an Array, then the array is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.

If repl is a Function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.

Default: An empty string

max

Optional; Limits the maximum number of substitutions to occur.

For instance, when max is:

-1 = all occurrences of pattern is replaced (any negative value does this).
0 = nothing is replaced.
1 = only the first occurrence of pattern is replaced.

Return Value

Returns a copy of String in which all occurrences of the pattern have been replaced by a replacement string specified by repl, which may be a String, an Array, or a Function.

GSub() also returns, as its second value, the total number of substitutions made.

Remarks

This function is pretty much the same a the LUA String.GSub() however this one returns start position starting at 0 (LUA's starts at 1) and lowers the end position by 1, Also the Offset begins at 0 here where as in LUA it begins at 1.

This is because in Sputnik chars in a string start at 0 not 1.

@GSubCount

This function also sets the total number of substitutions made but it does not return it with called instead you must request this count yourself by calling the @GSubCount macro example:

say gsub("hello world", "(%w+)", "%1 %1");
say "Number of replacements: " . @GSubCount;
// Prints
// hello hello world world
// Number of replacements: 2

Note - This variable is created local scope and applies to you immediately like the regex @groups does so you must grab it right away since if you wait too long you risk losing it.

Did it really change it?

Replacing a with a?

say gsub("a", "a", "a");
say "Number of replacements: " . @GSubCount;
// Prints
// a
// Number of replacements: 1

This function actually counts replacing a value with the same text as a valid replacement.

In a sense, the @GSubCount is accurate if you count replacing "a" by "a" as a replacement.

Example

A basic example that also uses the @GSubCount

say gsub("hello world", "(%w+)", "%1 %1");
say "Number of replacements: " . @GSubCount;
// Prints
// hello hello world world
// Number of replacements: 2

say gsub("hello world", "%w+", "%0 %0", 1);
// Prints
// hello hello world

say gsub("hello world from Spuntik", "(%w+)%s*(%w+)", "%2 %1");
// Prints
// world hello Spuntik from

say gsub("hello Sputnik!", "(%a)", "%1-%1");
say "Count: " . @GSubCount;
// Prints
// h-he-el-ll-lo-o S-Sp-pu-ut-tn-ni-ik-k!
// Count: @GSubCount

Using gsub() to trim whitespace

my $s = "   		Hello    			";
say gsub($s, '^%s*(.-)%s*$', "%1");
say "Count: " . @GSubCount;
// Prints
// Hello
// Count: @GSubCount

Using a function as the replacement

// Find each word and uppercase it
my $string = 'lol is cat hehe, isnt it?';
say gsub($string, '(%w+)', function($s) { return uc($s); });
// Prints
// LOL IS CAT HEHE, ISNT IT?

Same as above but with condition

// Find each word and uppercase it
// but only if it contains a "t"
my $string = 'lol is cat hehe, isnt it?';
say gsub($string, '(%w+)', function($s) { return Contains($s, 't') ? uc($s) : null; });
// Prints
// lol is CAT hehe, ISNT IT?

Using a function as the replacement but note each capture becomes a new parameter in the function

my $string = 'lol is cat hehe, isnt it?';
say gsub($string, '(%w+) (%w+)', function($s, $t) { return "$t $s"; });
// Prints
// is lol hehe cat, it isnt?

Use gsub() a search + replace but allow for matching whole words only and not partial

my $source  = 'test testing this test of testicular footest testimation test';
my $find    = 'test';
my $replace = 'XXX';
// Replace any found match
say "Non-Whole Replace";
say ReplaceText($source, $find, $replace, false);
say "Whole Replace";
// Replace only whole matches (not something thats part of something else!)
say ReplaceText($source, $find, $replace, true);
// Prints:
// Non-Whole Replace
// XXX XXXing this XXX of XXXicular fooXXX XXXimation XXX
// Whole Replace
// XXX testing this XXX of testicular footest testimation XXX
 
function ReplaceText($source, $find, $replace, $wholeword)
{
	if( $wholeword )
		$find = '%f[%a]' . $find . '%f[%A]';
	return gsub($source, $find, $replace);
}

Fill an array with the captures

Global $results = array();
gsub("hello hi, again!", "(%a+)", function($w) { $results[] = $w; });
printr $results;
// Prints
// Array
// (
//     [0] => hello
//     [1] => hi
//     [2] => again
// )

If you provide an array with keys and values the keys will be checked against the captured matches and if its a match it will use the arrays value

Global $replacements = array( "name" => "T3Charmy", "code" => 1337 );
say gsub("Welcome #name, Your code for today is #code", "#(%a+)", $replacements);
// Prints
// Welcome T3Charmy, Your code for today is 1337

Of course if the given key is not found in the array it will use the captured match instead

Global $replacements = array( "name" => "T3Charmy", "code" => 1337 );
say gsub("Welcome #name, Code is #code and time is #time", "#(%a+)", $replacements);
// Prints
// Welcome T3Charmy, Code is 1337 and time is #time

Replace #tags in a string with Sputnik global variables

Global $name = "Sputnik";
Global $status = "great";
 
my $string = '#name is #status, isnt it?';
say gsub($string, '#(%w+)', function($s) { return "{\$$s}"; });
// Prints
// Sputnik is great, isnt it?

Replace $tags in a string with Sputnik global variables

Global $name = "Sputnik";
Global $status = "great";
 
my $string = '$name is $status, isnt it?';
say gsub($string, '$(%w+)', function($s) { return "{\$$s}"; });
// Prints
// Sputnik is great, isnt it?

Count "/" chars in a path using the following idiom

my $path = "/many/nested/directories";
gsub($path, "/");
say "Number: " . @GSubCount;
// Prints
// Number: 3

Count number of vowels

gsub("the quick brown fox", "[aeiou]");
say "Number of vowels: " . @GSubCount;
// Prints
// Number of vowels: 5