Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:pipeline:general_information:string_data [2024/07/17 15:46] – created sgranger
+++ visual3d:documentation:pipeline:general_information:string_data [2024/10/04 15:36] (current) – Initial rework - the page is still missing string function descriptions. wikisysop
@@ Line 1: / Line 1: @@
-====== String Data ======
+===== String Data =====
-==== Contents ====
+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.
-  * [[#Syntax|1 Syntax]]
+=== Literal String Data ===
-  * [[#Modify|2 Modify]]
-  * [[#Parsing|3 Parsing]]
-    * [[#Parsing_String_Data_(more...)|3.1 Parsing String Data (more...)]]
-    * [[#String_Left|3.2 String_Left]]
-    * [[#String_Right|3.3 String_Right]]
-    * [[#String_Mid|3.4 String_Mid]]
-    * [[#String_Length|3.5 String_Length]]
-    * [[#String_Find|3.6 String_Find]]
-    * [[#String_Reverse_Find|3.7 String_Reverse_Find]]
-    * [[#String_To_Lower|3.8 String_To_Lower]]
-    * [[#String_To_Upper|3.9 String_To_Upper]]
-    * [[#To_String|3.10 To_String]]
-    * [[#Example:_Extract_text_(more...)|3.11 Example: Extract text (more...)]]
+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.
-=== Syntax ===
+<code>
+Set_Pipeline_Parameter_From_Expression
+/PARAMETER_NAME=TEST_STRING
+/EXPRESSION="A123456789"
+/AS_INTEGER=FALSE
+;
+</code>
-Quotes are to be used around string data in an expression to differentiate it from variable names. ie; subject_name="John Smith". Parameters in the pipeline that are strings, are not quoted (i.e.; EXPRESSION is a string, but you don't need quotes around it). Within EXPRESSION, our expression parser parses the variables, data and operators out of the expression. Data can be doubles or strings. If it is a string, Visual3D has no way to recognize the difference between a string and a variable name reference, except to quote the string data.
+The result of this command is
-For example, there is a problem with the following evaluate_expression:
+<code>
+::TEST_STRING = A123456789
+</code>
-**Evaluate_Expression**
+=== 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:
-**Evaluate_Expression**
+<code>
+Evaluate_Expression
 /EXPRESSION=(&::HandChoice&="LEFT")
 /RESULT_NAME=TEST_4
 ! /RESULT_TYPE=DERIVED
 ! /RESULT_FOLDER=PROCESSED
-**;**
+;
-Currently, the operators are only parsed as a single character, so the use of "/=" (not equals) cannot be used yet. You can do NOT(item1=item2) in order to process a not equals currently, but this will change shortly to allow "/=", "!=" cannot be used because the "!" is our start comment character for the pipeline commands.
+</code>
-=== Modify ===
+=== Negation ===
-=== Parsing ===
+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.
-Given a pipeline parameter that is a string. For internal reasons, the string cannot be a number, or it will be interpreted as a number.
+In order to negate an expression you can use the syntax "NOT(item1=item2)".
-There are 3 commands that extract a portion of a string.
+==== 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_LENGTH(string)
 STRING_FIND(string, substring, start)
-**NOTE:** When referencing strings, the string should be surrounded by quotes. This identifies to Visual3D that you are referencing a string, and not a file name etc.
-\\
+and one command for measuring the string:
+STRING_LENGTH(string)
-== Parsing String Data (more...) ==
+=== String_Left ===
-**Set_Pipeline_Parameter_From_Expression**
-/PARAMETER_NAME=TEST_STRING
-/EXPRESSION="A123456789"
-/AS_INTEGER=FALSE
-**;**
-The result is
-::TEST_STRING = A123456789
+<code>
-== String_Left ==
+Set_Pipeline_Parameter_From_Expression
-**Set_Pipeline_Parameter_From_Expression**
 /PARAMETER_NAME=TEST_LEFT
 /EXPRESSION=STRING_LEFT("&::TEST_STRING&",3)
 /AS_INTEGER=FALSE
-**;**
+;
-The result is
+</code>
+The result is:
+<code>
 ::TEST_LEFT = A12
-== String_Right ==
+</code>
-**Set_Pipeline_Parameter_From_Expression**
+=== String_Right ===
+<code>
+Set_Pipeline_Parameter_From_Expression
 /PARAMETER_NAME=TEST_RIGHT
 /EXPRESSION=STRING_RIGHT("&::TEST_STRING&",3)
 /AS_INTEGER=FALSE
-**;**
+;
-The result is
+</code>
+The result is:
+<code>
 ::TEST_RIGHT = 789
-== String_Mid ==
+</code>
+=== String_Mid ===
+Note that the two index parameters are zero-based for the STRING_MID function.
-**Set_Pipeline_Parameter_From_Expression**
+<code>
+Set_Pipeline_Parameter_From_Expression
 /PARAMETER_NAME=TEST_MID
 /EXPRESSION=STRING_MID("&::TEST_STRING&",3,3)
 /AS_INTEGER=FALSE
-**;**
+;
-The result is
+</code>
+The result is:
+<code>
 ::TEST_MID = 345
-//Note: For STRING_MID the number values are zero based//
+</code>
-== String_Length ==
+=== String_Find ===
-**Set_Pipeline_Parameter_From_Expression**
+<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
-**;**
+;
-The result is
+</code>
+The result is:
+<code>
 ::TEST_LENGTH = 10
-**Set_Pipeline_Parameter_From_Expression**
+</code>
+<code>
+Set_Pipeline_Parameter_From_Expression
 /PARAMETER_NAME=TEST_INDEX
 /EXPRESSION=STRING_FIND("&::TEST_STRING&",234,0)
 /AS_INTEGER=TRUE
-**;**
+;
-The result is
+</code>
+The result is:
+<code>
 ::TEST_INDEX = 2
-\\
+</code>
-== String_Find ==
-**Set_Pipeline_Parameter_From_Expression**
-/PARAMETER_NAME=TEST_INDEX
-/EXPRESSION=STRING_FIND("&::TEST_STRING&",234,5)
-/AS_INTEGER=TRUE
-**;**
-The result is
-::TEST_INDEX = -1
-== String_Reverse_Find ==
-== String_To_Lower ==
+=== String_To_Lower ===
+<code>
 !Converting To_Upper and To_Lower String Data (more...)
-**Set_Pipeline_Parameter_From_Expression**
+Set_Pipeline_Parameter_From_Expression
 /PARAMETER_NAME=TEST
 /EXPRESSION=STRING_TO_LOWER("XXXXXX")
 /AS_INTEGER=FALSE
-**;**
+;
-**Set_Pipeline_Parameter_From_Expression**
+Set_Pipeline_Parameter_From_Expression
 /PARAMETER_NAME=TEST
 /EXPRESSION=STRING_TO_UPPER("yyyyyyy")
 /AS_INTEGER=FALSE
-**;**
+;
-**Select_Active_File**
+Select_Active_File
 /FILE_NAME=GLOBAL
 ! /QUERY=
-**;**
+;
-**Create_Text_Data**
+Create_Text_Data
 /SIGNAL_FOLDER=SCOTT
 /SIGNAL_NAMES=NAME
@@ Line 163: / Line 197: @@
 ! /TEXT_FILE_NAME=
 ! /PROMPT_ON_EMPTY=TRUE
-**;**
+;
-**Evaluate_Expression**
+Evaluate_Expression
 /EXPRESSION=STRING_TO_UPPER(TEXT_DATA::SCOTT::NAME)
 ! /SIGNAL_TYPES=
@@ Line 173: / Line 208: @@
 /RESULT_NAME=SCOTT_UPPER
 ! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
-**;**
+;
-**Evaluate_Expression**
+Evaluate_Expression
 /EXPRESSION=STRING_TO_LOWER(TEXT_DATA::SCOTT::NAME)
 ! /SIGNAL_TYPES=
@@ Line 183: / Line 219: @@
 /RESULT_NAME=SCOTT_LOWER
 ! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
-**;**
+;
-== String_To_Upper ==
+</code>
-== To_String ==
+=== String_To_Upper ===
-== Example: Extract text (more...) ==
+To be completed...
-Given the following Text_Data loaded from a file store in a signal TEXT_DATA::SCOTT:TEST
+=== 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>
-Extract the name of the subject.
+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.
-**Set_Pipeline_Parameter_From_Expression**
+<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**
+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**
+Set_Pipeline_Parameter_From_Expression
 /PARAMETER_NAME=SUBJECT
 /EXPRESSION=String_Mid(TEXT_DATA::SCOTT::TEST,&::F1&,&::F2&)
 /AS_INTEGER=FALSE
-**;**
+;
-The resulting pipeline parameter contains "Scott"
+</code>