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

See Remarks to learn about patterns

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 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

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.

Patterns

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.

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

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