Core Function Find

Revision as of 23:52, 3 August 2014

Find( <string>, <needle>, <offset>, <plain>, <ignoreCase> )

Description

Search for a match in a string and return the match with its found position and length.

Parameters

string

The string to evaluate.

offset

Optional; The starting position of the search.

Default: 0

needle

The needle to search for.

(Can be a regular expression pattern)

If using a regular expression pattern it works pretty much like all regular expressions in Sputnik but there are some exceptions and some additional features.

You should read the regular expression page here to learn more about what patterns you can use in them.

Additional character classes for Find()

%a --- all letters. 
%c --- all control characters. 
%d --- all digits. 
%l --- all lowercase letters. 
%p --- all punctuation characters. 
%s --- all space characters. 
%u --- all uppercase letters. 
%w --- all alphanumeric characters. 
%x --- all hexadecimal digits. 
%z --- the character with hex representation 0x00 (null). 
%% --- a single '%' character.
%1 --- captured pattern 1.
%2 --- captured pattern 2 (and so on).

Important! - the uppercase versions of the above represent the complement of the class. eg. %U represents everything except uppercase letters, %D represents everything except digits.

plain

Optional; Flag to indicate if the operations should use regular expressions or not.

true = treat the needle as a regular expression
false = treat the needle as plain text

Default: true

ignoreCase

Optional; Flag to indicate if the operations should use regular expressions or not.

true = use case insensitive search
false = use case sensitive search

Default: false

Return Value

Success: Returns A array of the single match or an array of all arrayed captured.

Failure: Returns NULL.

Remarks

Will seek to return single captures as a single array.

Example

Search for raw text in a string (No patterns)

my $Test = "Hello cat world!";
printr Find($Test, "cat", 0, true);
// Prints
// Array
// (
//     [0] => cat
//     [1] => 6
//     [2] => 3
// )

Search for raw text in a string (No patterns) case insensitively

my $Test = "Hello cat world!";
printr Find($Test, "CAT", 0, true, true);
// Prints
// Array
// (
//     [0] => cat
//     [1] => 6
//     [2] => 3
// )

Search for raw text in a string but handle the result manually

my $Test = "the quick brown fox";
my List ($Text, $Pos, $Len) = Find($Test, "brown", 0, true);
say "Position: $Pos";
say "Length: $Len";
say "String: $Text";
// Prints
// Position: 10
// Length: 5
// String: brown

Use regular expressions to find it note it only returns the index and size when it cant find any group matches

my $Test = "Hello cat world!";
printr Find($Test, "cat");
// Prints
// Array
// (
//     [0] => 6
//     [1] => 3
// )

Another regular expression match with no groups

my $Test = "the quick brown fox";
printr Find($Test, "quick");
// Prints
// Array
// (
//     [0] => 4
//     [1] => 5
// )

A group capture regular expression this time

my $Test = "the quick brown fox";
printr Find($Test, "(%a+)");
// Prints
// Array
// (
//     [0] => the
//     [1] => 0
//     [2] => 3
// )

Another group capture regular expression this time

my $Test = "the quick brown fox";
printr Find($Test, "(%a+)", 10);
// Prints
// Array
// (
//     [0] => brown
//     [1] => 10
//     [2] => 5
// )

Another regular expression this time but we will handle the capture ourself

my $Test = "the quick brown fox";
my List ($Pos, $Len) = Find($Test, "%a+", 10);
say "Position: $Pos";
say "Length: $Len";
say "String: " . substr($Test, $Pos, $Len);
// Prints
// Position: 10
// Length: 5
// String: brown

What happens when no match is found with regular expressions

my $Test = "the quick brown fox";
printr vardump(Find($Test, "fruit"));
// Prints
// NULL

What happens when no match is found without regular expressions

my $Test = "the quick brown fox";
printr vardump(Find($Test, "fruit", 0, true));
// Prints
// NULL

More examples

my $Test = "You see dogs and dogs";
printr Find($Test, "You see (.*)");
// Prints
// Array
// (
//     [0] => dogs
//     [1] => 8
//     [2] => 4
// )

You can also refer to matched substrings (captures) later on in an expression:

my $Test = "You see dogs and dogs";
printr Find($Test, "You see (.*) and %1");
// Prints
// Array
// (
//     [0] => dogs
//     [1] => 8
//     [2] => 4
// )

As shown here when the matched substring is not found NULL is returned

my $Test = "You see dogs and cats";
printr vardump(Find($Test, "You see (.*) and %1"));
// Prints
// NULL

Another example of referring to matched substrings (captures) later on in an expression:

my $Test = "You sir see dogs and dogs = sir";
printr Find($Test, "You (.*) see (.*) and %2 = %1");
// Prints
// Array
// (
//     [1] => Array
//         (
//             [0] => sir
//             [1] => 4
//             [2] => 3
//         )
//     [2] => Array
//         (
//             [0] => dogs
//             [1] => 12
//             [2] => 4
//         )
// )