diff --git a/content/en/docs/2023.11/Reference/Blocks/Text/find-text/_index.md b/content/en/docs/2023.11/Reference/Blocks/Text/find-text/_index.md new file mode 100644 index 000000000..e04585aac --- /dev/null +++ b/content/en/docs/2023.11/Reference/Blocks/Text/find-text/_index.md @@ -0,0 +1,5 @@ +--- +title: "Find Text" +linkTitle: "Find Text" +description: "Find text in another text" +--- diff --git a/content/en/docs/2023.11/Reference/Blocks/Text/find-text/find-all-text-block.md b/content/en/docs/2023.11/Reference/Blocks/Text/find-text/find-all-text-block.md new file mode 100644 index 000000000..017e28955 --- /dev/null +++ b/content/en/docs/2023.11/Reference/Blocks/Text/find-text/find-all-text-block.md @@ -0,0 +1,578 @@ +--- +title: "Find All Text" +linkTitle: "Find All Text" +description: "Finds all occurrences of a text in a given text." +--- +{{< figure src="/blocks/text-find-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Text.FindText.FindAllTextBlock)

+ +## Description + +Finds all occurrences of [Text To Find][TextToFind Property] in a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to match the [Text To Find][TextToFind Property] input. + +## Examples + +### Find all occurrences of Text To Find (Ordinal) + +This example will find all occurrences of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [List][]<[Match][]> value | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Matches` will be set to the following: + +```json +[ + { + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } + } +] +``` + +*** + +### Find all occurrences of Text To Find (Ordinal Ignore Case) + +This example will find all occurrences of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [List][]<[Match][]> value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Matches` will be updated to the following: + +```json +[ + { + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } + }, + { + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } + } +] +``` + +*** + +### Find all occurrences that match the pattern in Text To Find + +This example will find all occurrences of text that match a pattern containing `"?he"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "?he", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "?he", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [List][]<[Match][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` and `"the"` that matches the pattern `"?he"`. Therefore, the variable `($)Matches` will be set to the following: + +```json +[ + { + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } + }, + { + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } + } +] +``` + +*** + +### Find all occurrences that match the regex in Text To Find + +This example will find all occurrences of text that match the regex `"^The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "^The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "^The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [List][]<[Match][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` at the start of the sentence that matches the regex `"^The"`. Therefore, the variable `($)Matches` will be set to the following: + +```json +[ + { + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } + } +] +``` + +*** + +### Find all occurrences that start with and end with a Text To Find in Text + +This example will find all occurrences of text that start with `"The"` and end with `"jumps"` from `"The quick brown fox jumps over the lazy dog."`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "The", "contains": "", "endsWith": "jumps"}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "The", contains: "", endsWith:"jumps")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [List][]<[Match][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains 1 occurrence starting with `"The"` and ending with `"jumps"`, which is `"The quick brown fox jumps"` Therefore, the variable `($)Matches` will be set to the following: + +```json +[ + { + "Value": "The quick brown fox jumps", + "Index": 0, + "Length": 25, + "Groups": { + "0": { + "Value": "The quick brown fox jumps", + "Index": 0, + "Length": 25, + "Captures": [ + { + "Value": "The quick brown fox jumps", + "Index": 0, + "Length": 25 + } + ] + }, + "startsWith": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "endsWith": { + "Value": "jumps", + "Index": 20, + "Length": 5, + "Captures": [ + { + "Value": "jumps", + "Index": 20, + "Length": 5 + } + ] + } + } + } +] +``` + +*** + +### Find all occurrences that start with and end with a Text To Find in Text (Null contains) + +This example will find all occurrences of text that start with `"The"`, contains `null` and ends with `"jumps"` from `"The quick brown fox jumps over the lazy dog. The dog woke up and tried to bite the fox. The fox jumps to get away."`. To clarify, this [Text To Find][TextToFind Property] input is searching for matches of `"Thejumps"` exactly in [Text][Text Property]. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog. The dog woke up and tried to bite the fox. The fox jumps to get away."` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "The", "contains": null, "endsWith": "jumps"}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "The", contains: null, endsWith:"jumps")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Matches][Matches Property] | `($)Matches`, with no value | `($)Matches` is a variable that will be set to an [List][]<[Match][]> value | + +#### Result + +`"The quick brown fox jumps over the lazy dog. The dog woke up and tried to bite the fox. The fox jumps to get away."` has 0 occurrences starting with `"The"` and ending with `"jumps"`, as [Contains][] being `null` will require an exact match for [Text to Find][TextToFind Property] in [Text][Text Property]. Therefore, the variable `($)Matches` will be set to the following: + +```json +[] +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to find all occurrences of [Text To Find][TextToFind Property] in. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] search query to find all occurrences of in [Text][Text Property]. This property contains all of the information in relation to the conditions for a valid match; these are: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Find][TextToFind Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.Net Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [Text To Find][TextToFind Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Matches + +The [List][]<[Match][]> containing all valid matches found for the [Text To Find][TextToFind Property] search query. + +| | | +|--------------------|---------------------------| +| Data Type | [List][]<[Match][]> | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Matches` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when the execution time of any search done to populate the [Matches][Matches Property] property exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to find in, so no operation is performed. + +### Null or empty Text To Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`) there is nothing to find, so no operation is performed, and [Matches][Matches Property] is set to an empty [List][]<[Match][]>. + +### Null or empty property of Text To Find + +If at least one, but not all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), then that section of the query is not included as a specific [Group][] in the returned [Match][]; see [Find all occurrences that start with and end with a Text To Find in Text][]. +There exist two special cases involving the [Contains][] nested property of [Text To Find][TextToFind Property]; see below. + +#### Empty contains property of Text To Find + +If the [Contains][] nested property of [Text To Find][TextToFind Property] is empty (i.e. `""`), and both the [StartsWith][] and [EndsWith][] nested properties are not null, then a valid match will be one starting with [StartsWith][], and ending with [EndsWith][], including of any content between the two groups; see [Find all occurrences that start with and end with a Text To Find in Text][]. + +#### Null contains property of Text To Find + +If the [Contains][] nested property of [Text To Find][TextToFind Property] is `null`, and both the [StartsWith][] and [EndsWith][] nested properties are not null, then a valid match will be one starting with [StartsWith][], and ending with [EndsWith][], with no content between the two groups, i.e. an exact match only; see [Find all occurrences that start with and end with a Text To Find in Text (Null contains)][]. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Matches Property]: {{< ref "#matches" >}} +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Find all occurrences that start with and end with a Text To Find in Text]: {{}} +[Find all occurrences that start with and end with a Text To Find in Text (Null contains)]: {{}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Match]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Match.MainDoc" >}} +[Group]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Group.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2023.11/Reference/Blocks/Text/find-text/find-text-block.md b/content/en/docs/2023.11/Reference/Blocks/Text/find-text/find-text-block.md new file mode 100644 index 000000000..ceea73cdc --- /dev/null +++ b/content/en/docs/2023.11/Reference/Blocks/Text/find-text/find-text-block.md @@ -0,0 +1,614 @@ +--- +title: "Find Text" +linkTitle: "Find Text" +description: "Finds the specified occurrence of a text in a given text." +--- +{{< figure src="/blocks/text-find-block-icon.png" alt="Icon" class="block-icon" >}} + +# {{% param title %}} + +

(Cortex.Blocks.Text.FindText.FindTextBlock)

+ +## Description + +Finds the specified [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in a given [Text][Text Property]. + +[Search Options][SearchOptions Property] can be specified to choose whether to use a ContainsText, PatternMatching or Regex search to match the [Text To Find][TextToFind Property] input. + +## Examples + +### Find the specified Occurrence of Text To Find (Ordinal) + +This example will find the first occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `0` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +As this example is performing a [case-sensitive, culture-insensitive][Ordinal] comparison of text, `"The quick brown fox jumps over the lazy dog"` only contains the text `"The"` once; `"the"` has a different case so does not match. Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } +} +``` + +*** + +### Find the specified Occurrence of Text To Find (Ordinal Ignore Case) + +This example will find the second occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } +} +``` + +*** + +### Find the last occurrence of Text To Find + +This example will find the last occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `-1` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. As we are looking for [Occurrence][Occurrence Property] `-1`, we choose the last occurrence, and therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "the", + "Index": 31, + "Length": 3, + "Groups": { + "0": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + }, + "contains": { + "Value": "the", + "Index": 31, + "Length": 3, + "Captures": [ + { + "Value": "the", + "Index": 31, + "Length": 3 + } + ] + } + } +} +``` + +*** + +### Find an invalid occurrence of Text To Find + +This example will find the third occurrence of `"The"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `2` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.OrdinalIgnoreCase` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +As this example is performing a [case-insensitive, culture-insensitive][OrdinalIgnoreCase] comparison of text, `"The quick brown fox jumps over the lazy dog"` contains the text `"The"` twice; the first occurrence is `"The"` and the second occurrence is `"the"`. As we are looking for [Occurrence][Occurrence Property] `2`, and there are only 2 matches, there is not a valid match. Therefore, the variable `($)Match` will be set to the following: + +```json +null +``` + +*** + +### Find the specified Occurrence that matches the pattern in Text To Find + +This example will find the first occurrence of text that match a pattern containing `"?he"` in `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "?he", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "?he", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `0` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.PatternMatching` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` and `"the"` that matches the pattern `"?he"`. Of these, `"The"` is found first in the [Text][Text Property]. Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } +} +``` + +*** + +### Find the specified Occurrence that matches the regex in Text To Find + +This example will find the first occurrence of text that match the regex `"^The"` from `"The quick brown fox jumps over the lazy dog"`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "", "contains": "^The", "endsWith": ""}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "", contains: "^The", endsWith:"")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `0` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.Regex` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains `"The"` at the start of the sentence that matches the regex `"^The"`. Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "The", + "Index": 0, + "Length": 3, + "Groups": { + "0": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "contains": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + } + } +} +``` + +*** + +### Find the specified Occurrence that starts with and ends with a Text To Find in Text + +This example will find the first occurrence of text that starts with `"The"` and ends with `"jumps"` from `"The quick brown fox jumps over the lazy dog."`. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog"` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "The", "contains": "", "endsWith": "jumps"}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "The", contains: "", endsWith:"jumps")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `0` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog"` contains 1 occurrence starting with `"The"` and ending with `"jumps"`, which is `"The quick brown fox jumps"` Therefore, the variable `($)Match` will be set to the following: + +```json +{ + "Value": "The quick brown fox jumps", + "Index": 0, + "Length": 25, + "Groups": { + "0": { + "Value": "The quick brown fox jumps", + "Index": 0, + "Length": 25, + "Captures": [ + { + "Value": "The quick brown fox jumps", + "Index": 0, + "Length": 25 + } + ] + }, + "startsWith": { + "Value": "The", + "Index": 0, + "Length": 3, + "Captures": [ + { + "Value": "The", + "Index": 0, + "Length": 3 + } + ] + }, + "endsWith": { + "Value": "jumps", + "Index": 20, + "Length": 5, + "Captures": [ + { + "Value": "jumps", + "Index": 20, + "Length": 5 + } + ] + } + } +} +``` + +*** + +### Find the specified Occurrence that starts with and ends with a Text To Find in Text (Null contains) + +This example will find the first occurrence of text that start with `"The"`, contains `null` and ends with `"jumps"` from `"The quick brown fox jumps over the lazy dog."`. To clarify, this [Text To Find][TextToFind Property] input is searching for matches of `"Thejumps"` exactly in [Text][Text Property]. + +It performs a [case-sensitive, culture-insensitive][Ordinal] comparison of text. + +#### Properties + +| Property | Value | Notes | +|--------------------|---------------------------|------------------------------------------| +| [Text][Text Property] | `($)Text`, with value `"The quick brown fox jumps over the lazy dog."` | `($)Text` is a variable of type [String][] | +| [Text To Find][TextToFind Property] | `($)TextToFind`, with value `{"startsWith": "The", "contains": null, "endsWith": "jumps"}`

In this example `($)TextToFind` has been set up using the following [Expression][]:

`new TextToFind(startsWith: "The", contains: null, endsWith:"jumps")` | `($)TextToFind` is a variable of type [TextToFind][] | +| [Occurrence][Occurrence Property] | `($)Occurrence`, with value `0` | `($)Occurrence` is a variable of type [Int32][] | +| [Search Options][SearchOptions Property] | `($)SearchOptions`, with value `SearchOptions.ContainsText` | `($)SearchOptions` is a variable of type [SearchOptions][] | +| [Comparison Type][ComparisonType Property] | `($)ComparisonType`, with value `StringComparison.Ordinal` | `($)ComparisonType` is a variable of type [StringComparison][] | +| [Match][Match Property] | `($)Match`, with no value | `($)Match` is a variable that will be set to an [Match][] value | + +#### Result + +`"The quick brown fox jumps over the lazy dog."` has 0 occurrences starting with `"The"` and ending with `"jumps"`, as [Contains][] being `null` will require an exact match for [Text to Find][TextToFind Property] in [Text][Text Property]. Therefore, the variable `($)Match` will be set to the following: + +```json +null +``` + +*** + +## Properties + +### Text + +The [Text][Text Property] to find the specified occurrence of [Text To Find][TextToFind Property] in. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Property Type | [InputOutput][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Text` with no value | + +### Text To Find + +The [Text To Find][TextToFind Property] search query to find the specified occurrence of in [Text][Text Property]. This property contains all of the information in relation to the conditions for a valid match; these are: + +* [Starts With][StartsWith] +* [Contains][Contains] +* [Ends With][EndsWith] + +| | | +|--------------------|---------------------------| +| Data Type | [TextToFind][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `TextToFind` with the value shown below: | + +```json +{ + "StartsWith":"", + "Contains":"", + "EndsWith":"", +} +``` + +### Occurrence + +The [Occurrence][Occurrence Property] of [Text To Find][TextToFind Property] in [Text][Text Property]. + +For information about [supported values][Occurrences] for the [Occurrence][Occurrence Property] property and examples of how it can be used, please see [Occurrences][]. + +| | | +|--------------------|---------------------------| +| Data Type | [Int32][] | +| Property Type | [Input][] | +| Is [Advanced][] | `false` | +| Default Editor | [Literal][] | +| Default Value | `0` | + + +### Search Options + +[Search Options][SearchOptions Property] can be specified to choose whether [Text To Find][TextToFind Property] should be interpreted as a ContainsText, PatternMatching or Regex search: + +* `SearchOptions.ContainsText` matches text exactly; as long as the [Text][Text Property] contains the text specified in [Text To Find][TextToFind Property] it will be considered a match. +* `SearchOptions.PatternMatching` allows wildcard text matching using [Pattern Matching Syntax][]: + * `*` wildcard character can be used to match `0` or more characters. + * `?` wildcard character can be used to match `0` or `1` character. + * All other characters are treated as a literal character. +* `SearchOptions.Regex` allows regex text matching using [.NET Regex Syntax][Regex Syntax]. + +Please note that with `SearchOptions.ContainsText` overlapping matches are detected (e.g. searching for `"aa"` in `"aaa"` matches `"aa"` at index `0` and `"aa"` at index `1`). With `SearchOptions.Regex` only `"aa"` at index `0` will be matched. + +| | | +|--------------------|---------------------------| +| Data Type | [SearchOptions][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `ContainsText` | + +### Comparison Type + +The [Comparison Type][ComparisonType Property] specifying the rules used to match occurrences of [Text To Find][TextToFind Property] in [Text][Text Property]. + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +| | | +|--------------------|---------------------------| +| Data Type | [StringComparison][] | +| Property Type | [Input][] | +| Is [Advanced][] | `true` | +| Default Editor | [Literal][] | +| Default Value | `Ordinal` | + +### Match + +The [Match][] containing the valid match found for the [Text To Find][TextToFind Property] search query. + +| | | +|--------------------|---------------------------| +| Data Type | [Match][] | +| Property Type | [Output][] | +| Is [Advanced][] | `false` | +| Default Editor | [Variable][] | +| Default Value | `($)Match` with no value | + +## Exceptions + +The exceptions thrown by the block can be found below: + +| Name | Description | +|----------|----------| +| [ArgumentException][] | Thrown when [Comparison Type][ComparisonType Property] is not one of the specified [StringComparison][] types (e.g. `(StringComparison)10`). | +| | Thrown when [Search Options][SearchOptions Property] is not one of the specified [SearchOptions][] types (e.g. `(SearchOptions)10`). | +| [RegexMatchTimeoutException][] | Thrown when the execution time of any search done to populate the [Match][Match Property] property exceeds the [BlockTimeout][], or `60` seconds if that is undefined. | +| [RegexParsingFailedException][] | Thrown when [Search Options][SearchOptions Property] is `SearchOptions.Regex` and [TextToFind][TextToFind Property] has a property which is not a valid regex (e.g. `(`). | + +## Remarks + +### Comparison Types + +For information about the [supported values][ComparisonTypes] for the [Comparison Type][ComparisonType Property] property and examples of how it is determined whether two pieces of text match, please see [Equality][]. + +### Null or empty Text + +If [Text][Text Property] is `null` or empty (i.e. `""`) there is nothing to find in, so no operation is performed and [Match][Match Property] is set to `null`. + +### Null or empty Text To Find + +If all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`) there is nothing to find, so no operation is performed, and [Match][Match Property] is set to `null`. + +### Null or empty property of Text To Find + +If at least one, but not all properties of [Text To Find][TextToFind Property] are `null` or empty (i.e. `""`), then that section of the query is not included as a specific [Group][] in the returned [Match][]; see [Find the specified Occurrence that starts with and ends with a Text To Find in Text][]. +There exist two special cases involving the [Contains][] nested property of [Text To Find][TextToFind Property]; see below. + +#### Empty contains property of Text To Find + +If the [Contains][] nested property of [Text To Find][TextToFind Property] is empty (i.e. `""`), and both the [StartsWith][] and [EndsWith][] nested properties are not null, then a valid match will be one starting with [StartsWith][], and ending with [EndsWith][], including any content between the two groups; see [Find the specified Occurrence that starts with and ends with a Text To Find in Text][]. + +#### Null contains property of Text To Find + +If the [Contains][] nested property of [Text To Find][TextToFind Property] is `null`, and both the [StartsWith][] and [EndsWith][] nested properties are not null, then a valid match will be one starting with [StartsWith][], and ending with [EndsWith][], with no content between the two groups, i.e. an exact match only; see [Find the specified Occurrence that starts with and ends with a Text To Find in Text (Null contains)][]. + +### Known Limitations + +If [Search Options][SearchOptions Property] is set to `SearchOptions.Regex` or `SearchOptions.PatternMatching` and [Comparison Type][ComparisonType Property] is set to `StringComparison.CurrentCulture`, some characters such as `æ` that is equivalent to `ae` may not evaluate as equal. + +[Match Property]: {{< ref "#match" >}} +[Occurrence Property]:{{}} +[Text Property]: {{< ref "#text" >}} +[TextToFind Property]: {{< ref "#text-to-find" >}} +[SearchOptions Property]: {{< ref "#search-options" >}} +[ComparisonType Property]: {{< ref "#comparison-type" >}} +[Find the specified Occurrence that starts with and ends with a Text To Find in Text]: {{}} +[Find the specified Occurrence that starts with and ends with a Text To Find in Text (Null contains)]: {{}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Occurrences]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Occurrences.MainDoc" >}} +[Equality]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.MainDoc" >}} +[ComparisonTypes]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.MainDoc" >}} +[Ordinal]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.Ordinal" >}} +[OrdinalIgnoreCase]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.Equality.ComparisonTypes.OrdinalIgnoreCase" >}} +[Pattern Matching Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.PatternMatchingSyntax.MainDoc" >}} +[Regex Syntax]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.RegexSyntax.MainDoc" >}} + +[RegexParsingFailedException]: {{< url path="Cortex.Reference.Exceptions.Text.Regex.RegexParsingFailedException.MainDoc" >}} + +[ArgumentException]: {{< url path="MSDocs.DotNet.Api.System.ArgumentException" >}} +[RegexMatchTimeoutException]: {{< url path="MSDocs.DotNet.Api.System.Text.RegularExpressions.RegexMatchTimeoutException" >}} + +[Group]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Group.MainDoc" >}} +[Int32]: {{< url path="Cortex.Reference.DataTypes.Numbers.Int32.MainDoc" >}} +[List]: {{< url path="Cortex.Reference.DataTypes.Collections.List.MainDoc" >}} +[Match]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Match.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} +[StringComparison]: {{< url path="Cortex.Reference.DataTypes.Text.StringComparison.MainDoc" >}} +[SearchOptions]: {{< url path="Cortex.Reference.DataTypes.Text.SearchOptions.MainDoc" >}} + +[TextToFind]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.MainDoc">}} +[StartsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.StartsWith">}} +[Contains]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.Contains">}} +[EndsWith]: {{< url path="Cortex.Reference.DataTypes.Text.TextToFind.EndsWith">}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} +[BlockTimeout]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.CommonProperties.BlockTimeoutProperty" >}} diff --git a/content/en/docs/2023.11/Reference/Concepts/working-with/collections/occurrences.md b/content/en/docs/2023.11/Reference/Concepts/working-with/collections/occurrences.md index 7e277e889..ceec95a19 100644 --- a/content/en/docs/2023.11/Reference/Concepts/working-with/collections/occurrences.md +++ b/content/en/docs/2023.11/Reference/Concepts/working-with/collections/occurrences.md @@ -15,6 +15,7 @@ TODO - How are they accessed? - Positive or Negative int properties on blocks that operate on single items - Difference between occurrence and indexes +- specified occurrence ## Positive Occurrences diff --git a/content/en/docs/2023.11/Reference/data-types/text/regex/_index.md b/content/en/docs/2023.11/Reference/data-types/text/regex/_index.md new file mode 100644 index 000000000..8bde0833f --- /dev/null +++ b/content/en/docs/2023.11/Reference/data-types/text/regex/_index.md @@ -0,0 +1,6 @@ +--- +title: "Regex" +linkTitle: "Regex" +description: "Used to represent Regex data types" +weight: 1 +--- \ No newline at end of file diff --git a/content/en/docs/2023.11/Reference/data-types/text/regex/capturedetails.md b/content/en/docs/2023.11/Reference/data-types/text/regex/capturedetails.md new file mode 100644 index 000000000..326f21377 --- /dev/null +++ b/content/en/docs/2023.11/Reference/data-types/text/regex/capturedetails.md @@ -0,0 +1,37 @@ +--- +title: "CaptureDetails" +linkTitle: "CaptureDetails" +description: "Used to represent a single capture for a given group" +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Regex.CaptureDetails)

+ +{{< workinprogress >}} + +## Summary + +## Properties + +### Index + +### Value + +### Length + +## Remarks + +### Create a CaptureDetails + +### Property Editor Support + +### Known Limitations + +## See Also + +### Related Data Types + +### Related Concepts + +### External Documentation diff --git a/content/en/docs/2023.11/Reference/data-types/text/regex/group.md b/content/en/docs/2023.11/Reference/data-types/text/regex/group.md new file mode 100644 index 000000000..b88c623ae --- /dev/null +++ b/content/en/docs/2023.11/Reference/data-types/text/regex/group.md @@ -0,0 +1,39 @@ +--- +title: "Group" +linkTitle: "Group" +description: "Used to represent a regex match group. It contains all of the captures for a given group pattern." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Regex.Group)

+ +{{< workinprogress >}} + +## Summary + +## Properties + +### Value + +### Index + +### Length + +### Captures + +## Remarks + +### Create a Group + +### Property Editor Support + +### Known Limitations + +## See Also + +### Related Data Types + +### Related Concepts + +### External Documentation diff --git a/content/en/docs/2023.11/Reference/data-types/text/regex/match.md b/content/en/docs/2023.11/Reference/data-types/text/regex/match.md new file mode 100644 index 000000000..ffa46e477 --- /dev/null +++ b/content/en/docs/2023.11/Reference/data-types/text/regex/match.md @@ -0,0 +1,39 @@ +--- +title: "Match" +linkTitle: "Match" +description: "Used to represent a regex match. It contains all of the groups found in the regex pattern." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.Regex.Match)

+ +{{< workinprogress >}} + +## Summary + +## Properties + +### Value + +### Index + +### Length + +### Groups + +## Remarks + +### Create a Match + +### Property Editor Support + +### Known Limitations + +## See Also + +### Related Data Types + +### Related Concepts + +### External Documentation diff --git a/content/en/docs/2023.11/Reference/data-types/text/texttofind.md b/content/en/docs/2023.11/Reference/data-types/text/texttofind.md new file mode 100644 index 000000000..607cb1ab1 --- /dev/null +++ b/content/en/docs/2023.11/Reference/data-types/text/texttofind.md @@ -0,0 +1,137 @@ +--- +title: "TextToFind" +linkTitle: "TextToFind" +description: "Used to represent a search query for finding text." +--- + +# {{% param title %}} + +

(Cortex.DataTypes.Text.TextToFind)

+ +## Summary + +The `TextToFind` data type is used to represent a search query for finding text.

It specifies what a valid [match][Match] should start, contain and end with. + +| | | +|-|-| +| **Category:** | Text | +| **Name:** | `TextToFind` | +| **Full Name:** | `Cortex.DataTypes.Text.TextToFind` | +| **Alias:** | N/A | +| **Description:** | A text to find in another text. | +| **Default Value:** | `null` | +| **Can be used as:** | `TextToFind` | +| **Can be cast to:** | N/A | + +## Properties + +### Starts With + +[Starts With][StartsWith Property] is used to define the [String][] a valid match should start with. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +### Contains + +[Contains][Contains Property] is used to define the [String][] a valid match should contains between [Starts With][StartsWith Property] and [Ends With][EndsWith Property]. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `false` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +### Ends With + +[Ends With][EndsWith Property] is used to define the [String][] a valid match should end with. + +| | | +|--------------------|---------------------------| +| Data Type | [String][] | +| Is [Advanced][] | `true` | +| Default Editor | [Expression][] | +| Default Value | [String][] with value `$@""` | + +## Remarks + +### Create a TextToFind + +The following table shows some of the ways that a `TextToFind` can be created. + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use a `TextToFind` constructor | `new TextToFind(startsWith: "the", contains: "quick", endsWith: "fox")`| `{"StartsWith":"the", "Contains":"quick", "EndsWith":"fox"}` | Expression | || + +A `TextToFind` can also be created using the Literal Editor by filling in the necessary values for the following properties: + +| Property | Data Type | Example | Notes | +|-|-|-|-| +| `StartsWith` | `String` | `"the"` | [Starts With][StartsWith Property] defines the string a valid match should start with. | +| `Contains` | `String` | `"quick"` | [Contains][Contains Property] defines the string a valid match should contain. | +| `EndsWith` | `String` | `"fox"` | [Ends With][EndsWith Property] defines the string a valid match should end with. | + +### Convert TextToFind to Text + +| Method | Example | Result | Editor Support | Notes | +|-|-|-|-|-| +| Use `Convert Object To Json` block | where `Object` property has a value of `{"StartsWith":"the", "Contains":"quick", "EndsWith":"fox"}` | `""{\r\n \"StartsWith\": \"the\",\r\n \"Contains\": \"quick\",\r\n \"EndsWith\": \"fox\"\r\n}""` | N/A | See [Convert Object To Json][] | + +### Property Editor Support + +- The Expression Editor is available for [Input][] properties where the data type is `TextToFind`. +- The Literal Editor is available for [Input][] properties where the data type is `TextToFind`. +- The Variable Editor is available for [Input][], [InputOutput][] and [Output][] properties where the data type is `TextToFind`. + +### Known Limitations + +None + +## See Also + +### Related Data Types + +* [String][] + +### Related Concepts + +* [Working with Text][] + +### External Documentation + +None + +[Contains Property]: {{< ref "#contains" >}} +[EndsWith Property]: {{< ref "#ends-with" >}} +[StartsWith Property]: {{< ref "#starts-with" >}} + +[Input]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Input" >}} +[InputOutput]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.InputOutput" >}} +[Output]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.WhatIsABlockProperty.Output" >}} + +[Char]: {{< url path="Cortex.Reference.DataTypes.Text.Char.MainDoc" >}} +[Match]: {{< url path="Cortex.Reference.DataTypes.Text.Regex.Match.MainDoc" >}} +[String]: {{< url path="Cortex.Reference.DataTypes.Text.String.MainDoc" >}} + +[System.String]: {{< url path="MSDocs.DotNet.Api.System.String.MainDoc" >}} +[String.Concat]: {{< url path="MSDocs.DotNet.Api.System.String.Concat" >}} +[String Concatenation Operator]: {{< url path="MSDocs.DotNet.Api.System.String.ConcatOperator" >}} +[String Interpolation]: {{< url path="MSDocs.DotNet.Api.System.String.StringInterpolation" >}} +[String.Format]: {{< url path="MSDocs.DotNet.Api.System.String.Format" >}} +[String.Insert]: {{< url path="MSDocs.DotNet.Api.System.String.Insert" >}} +[String.Join]: {{< url path="MSDocs.DotNet.Api.System.String.Join" >}} + +[Literal]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.LiteralEditor.MainDoc" >}} +[Variable]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.VariableEditor.MainDoc" >}} +[Expression]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.PropertyEditors.ExpressionEditor.MainDoc" >}} + +[Advanced]: {{< url path="Cortex.Reference.Concepts.Fundamentals.Blocks.BlockProperties.AdvancedProperties.MainDoc" >}} + +[Convert Object To Json]: {{< url path="Cortex.Reference.Blocks.Json.ConvertJson.ConvertObjectToJson.MainDoc" >}} + +[Working with Text]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Text.MainDoc" >}} diff --git a/content/static/2023.11/blocks/text-find-block-icon.png b/content/static/2023.11/blocks/text-find-block-icon.png new file mode 100644 index 000000000..912fbd735 Binary files /dev/null and b/content/static/2023.11/blocks/text-find-block-icon.png differ diff --git a/data/urls.toml b/data/urls.toml index fe64ab68a..f7eb5df1a 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -938,6 +938,24 @@ [Cortex.Reference.Blocks.Text.DecodeText.DecodeText] MainDoc = "/docs/reference/blocks/text/decode-text/decode-text-block" KnownLimitations = "/docs/reference/blocks/text/decode-text/decode-text-block/#known-limitations" + [Cortex.Reference.Blocks.Text.FindText] + MainDoc = "/docs/reference/blocks/text/find-text/" + [Cortex.Reference.Blocks.Text.FindText.FindTextBlock] + MainDoc = "/docs/reference/blocks/text/find-text/find-text-block/" + [Cortex.Reference.Blocks.Text.FindText.FindAllTextBlock] + MainDoc = "/docs/reference/blocks/text/find-text/find-all-text-block/" + [Cortex.Reference.Blocks.Text.FindAndRemoveText] + MainDoc = "/docs/reference/blocks/text/find-and-remove-text/" + [Cortex.Reference.Blocks.Text.FindAndRemoveText.FindAndRemoveTextBlock] + MainDoc = "/docs/reference/blocks/text/find-and-remove-text/find-and-remove-text-block" + [Cortex.Reference.Blocks.Text.FindAndRemoveText.FindAndRemoveAllTextBlock] + MainDoc = "/docs/reference/blocks/text/find-and-remove-text/find-and-remove-all-text-block" + [Cortex.Reference.Blocks.Text.FindAndReplaceText] + MainDoc = "/docs/reference/blocks/text/find-and-replace-text/" + [Cortex.Reference.Blocks.Text.FindAndReplaceText.FindAndReplaceTextBlock] + MainDoc = "/docs/reference/blocks/text/find-and-replace-text/find-and-replace-text-block" + [Cortex.Reference.Blocks.Text.FindAndReplaceText.FindAndReplaceAllTextBlock] + MainDoc = "/docs/reference/blocks/text/find-and-replace-text/find-and-replace-all-text-block" [Cortex.Reference.Blocks.Text.FormatText] MainDoc = "/docs/reference/blocks/text/format-text/" [Cortex.Reference.Blocks.Text.FormatText.FormatTextWithValues] @@ -1676,6 +1694,14 @@ MainDoc = "/docs/reference/data-types/text/encryptedtext" [Cortex.Reference.DataTypes.Text.IFormatProvider] MainDoc = "/docs/reference/data-types/text/iformatprovider" + [Cortex.Reference.DataTypes.Text.Regex] + MainDoc = "/docs/reference/data-types/text/regex" + [Cortex.Reference.DataTypes.Text.Regex.Match] + MainDoc = "/docs/reference/data-types/text/regex/match" + [Cortex.Reference.DataTypes.Text.Regex.Group] + MainDoc = "/docs/reference/data-types/text/regex/group" + [Cortex.Reference.DataTypes.Text.Regex.CaptureDetails] + MainDoc = "/docs/reference/data-types/text/regex/capturedetails" [Cortex.Reference.DataTypes.Text.SearchOptions] MainDoc = "/docs/reference/data-types/text/searchoptions" [Cortex.Reference.DataTypes.Text.String] @@ -1689,6 +1715,11 @@ MainDoc = "/docs/reference/data-types/text/stringcomparison" [Cortex.Reference.DataTypes.Text.StringSplitOptions] MainDoc = "/docs/reference/data-types/text/stringsplitoptions" + [Cortex.Reference.DataTypes.Text.TextToFind] + MainDoc = "/docs/reference/data-types/text/texttofind" + StartsWith = "/docs/reference/data-types/text/texttofind/#starts-with" + Contains = "/docs/reference/data-types/text/texttofind/#contains" + EndsWith = "/docs/reference/data-types/text/texttofind/#ends-with" [Cortex.Reference.DataTypes.Text.TextDecodingErrorCode] MainDoc = "/docs/reference/data-types/text/textdecodingerrorcode" [Cortex.Reference.DataTypes.Text.TextEncodingFormat]