===== String Data =====

String data is fundamentally different from time-varying signals and metrics so we have created a collection of string-specific functions within [[visual3d:documentation:pipeline:expressions:expressions_overview|Evaluate_Expression]] to allow common string manipulations to be accomplished within your pipeline scripts.

==== Syntax ====

Within Evaluate_Expression, the expression parser reads through the provided expression as one large string and parses out the specific variables, data and operators. Because Visual3D has no way to recognize the difference between a literal string and a variable name, it is necessary to use quotes around string data, e.g., subject_name="John Smith". String parameters in the pipeline are not quoted.

=== Literal String Data ===

Strings can be explicitly created within a pipeline script without having to be stored as a pipeline variable. To accomplish this, all that needs to be done is to use quotes.

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_STRING
/EXPRESSION="A123456789"
/AS_INTEGER=FALSE
;
</code>

The result of this command is

<code>
::TEST_STRING = A123456789
</code>

=== Concatenation ===
Literal string data must be explicitly concatenated with values from parameters. For example, there is a problem with the following Evaluate_Expression syntax:

<code>
Evaluate_Expression
/EXPRESSION=(::HandChoice="LEFT")
/RESULT_NAME=TEST_4
! /RESULT_TYPE=DERIVED
! /RESULT_FOLDER=PROCESSED
;
</code>

This uses a pipeline parameter in the middle of a string parameter (the EXPRESSION). Global parameters cannot be evaluated in the middle of a string, so to recognize that a pipeline parameter, you need to concatenate it into the expression as follows:

<code>
Evaluate_Expression
/EXPRESSION=(&::HandChoice&="LEFT")
/RESULT_NAME=TEST_4
! /RESULT_TYPE=DERIVED
! /RESULT_FOLDER=PROCESSED
;
</code>

=== Negation ===

Operators are only parsed as a single character, so the "/=" notation for "not equals" cannot be used. It is also not possible to use the "!=" notation for "not equals" either because the "!" character is dedicated to indicating when comments begin within pipeline scripts.

In order to negate an expression you can use the syntax "NOT(item1=item2)".

==== Modify ====

==== Parsing ====

Given a pipeline parameter that is a string, there are four commands that extract a portion of a string:

STRING_LEFT(string,index)
STRING_RIGHT(string,index)
STRING_MID(string,index1,index2)
STRING_FIND(string, substring, start)

and one command for measuring the string:

STRING_LENGTH(string)

=== String_Left ===

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_LEFT
/EXPRESSION=STRING_LEFT("&::TEST_STRING&",3)
/AS_INTEGER=FALSE
;
</code>

The result is:

<code>
::TEST_LEFT = A12
</code>

=== String_Right ===

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_RIGHT
/EXPRESSION=STRING_RIGHT("&::TEST_STRING&",3)
/AS_INTEGER=FALSE
;
</code>

The result is:

<code>
::TEST_RIGHT = 789
</code>

=== String_Mid ===

Note that the two index parameters are zero-based for the STRING_MID function.

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_MID
/EXPRESSION=STRING_MID("&::TEST_STRING&",3,3)
/AS_INTEGER=FALSE
;
</code>

The result is:

<code>
::TEST_MID = 345
</code>

=== String_Find ===

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_INDEX
/EXPRESSION=STRING_FIND("&::TEST_STRING&",234,5)
/AS_INTEGER=TRUE
;
</code>

Because the string we are searching for "5" is not in the string being searched, "234", the result is:

<code>
::TEST_INDEX = -1
</code>

=== String_Reverse_Find ===

To be completed...

=== String_Length ===

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_LENGTH
/EXPRESSION=STRING_LENGTH("&::TEST_STRING&")
/AS_INTEGER=TRUE
;
</code>

The result is:

<code>
::TEST_LENGTH = 10
</code>

<code>
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST_INDEX
/EXPRESSION=STRING_FIND("&::TEST_STRING&",234,0)
/AS_INTEGER=TRUE
;
</code>

The result is:

<code>
::TEST_INDEX = 2
</code>

=== String_To_Lower ===

<code>
!Converting To_Upper and To_Lower String Data (more...)

Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST
/EXPRESSION=STRING_TO_LOWER("XXXXXX")
/AS_INTEGER=FALSE
;

Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=TEST
/EXPRESSION=STRING_TO_UPPER("yyyyyyy")
/AS_INTEGER=FALSE
;

Select_Active_File
/FILE_NAME=GLOBAL
! /QUERY=
;

Create_Text_Data
/SIGNAL_FOLDER=SCOTT
/SIGNAL_NAMES=NAME
/TEXT_DATA=Hello World
! /TEXT_FILE_NAME=
! /PROMPT_ON_EMPTY=TRUE
;

Evaluate_Expression
/EXPRESSION=STRING_TO_UPPER(TEXT_DATA::SCOTT::NAME)
! /SIGNAL_TYPES=
! /SIGNAL_FOLDER=ORIGINAL
! /SIGNAL_NAMES=
/RESULT_TYPES=TEXT_DATA
/RESULT_FOLDERS=SCOTT
/RESULT_NAME=SCOTT_UPPER
! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
;

Evaluate_Expression
/EXPRESSION=STRING_TO_LOWER(TEXT_DATA::SCOTT::NAME)
! /SIGNAL_TYPES=
! /SIGNAL_FOLDER=ORIGINAL
/SIGNAL_NAMES=
/RESULT_TYPES=TEXT_DATA
/RESULT_FOLDERS=SCOTT
/RESULT_NAME=SCOTT_LOWER
! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
;
</code>

=== String_To_Upper ===

To be completed...

=== To_String ===

To be completed

==== Example: Extracting text ====

Given the following Text_Data loaded from a file,

<code>
Random Stuff <Subject>Scott</Subject> More Random Stuff
</code>

this example demonstrates how to store the desired string "<Subject>Scott</Subject>" into the [[visual3d:documentation:visual3d_signal_types:data_tree|data tree]] at TEXT_DATA::SCOTT:TEST.

<code>
!Extract the name of the subject.
Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=F1
/EXPRESSION=9+STRING_FIND(TEXT_DATA::SCOTT::TEST, "<Subject>", 0)
/AS_INTEGER=TRUE
;

Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=F2
/EXPRESSION=STRING_FIND(TEXT_DATA::SCOTT::TEST, "</Subject>", 0)-&::F1
/AS_INTEGER=TRUE
;

Set_Pipeline_Parameter_From_Expression
/PARAMETER_NAME=SUBJECT
/EXPRESSION=String_Mid(TEXT_DATA::SCOTT::TEST,&::F1&,&::F2&)
/AS_INTEGER=FALSE
;
</code>