String Data Type

The String data type holds one or more characters in a variable and is usually used to store and display text. Even though strings can hold alphanumeric values and therefore can sometimes store numerical characters, this does not mean it can be used to perform mathematical operations with them. Please see the entries for Integer and Decimal for more information on numerical data types.

If trying to add the strings of “11” and “5” together, for example, the result will not be “16” but rather “115”.

Conditionals

Contains

This will return true if the target strings contains the parameter string. Example:

<dcs.Var Name="TestVar1" Type="String" SetTo="hello world, sun is up" />

<dcs.If Target="$TestVar1" Contains="sun">
  <dc.Out>TestVar1 contains "sun"</dc.Out>
</dcs.If>

Output:

TestVar1 contains "sun"

In

This will return true if the target string can be found in the list in the parameter.

<dcs.Var Name="TestVar1" Type="String" SetTo="sun" />

<dcs.If Target="$TestVar1" In="car,sun,lime">
  <dc.Out>TestVar1 is in the list</dc.Out>
</dcs.If>

Output:

TestVar1 is in the list

Note: Currently, the only way to check if a variable is in a list is to use the list as the target. Please see List examples.

StartsWith

This will return true if the target string begins with the string in the parameter.

<dcs.Var Name="TestVar1" Type="String" SetTo="hello world, sun is up" />

<dcs.If Target="$TestVar1" StartsWith="hello">
  <dc.Out>TestVar1 starts with "hello"</dc.Out>
</dcs.If>

Output:

TestVar1 starts with "hello"

EndsWith

This will return true if the target string ends with the string in the parameter.

<dcs.Var Name="TestVar1" Type="String" SetTo="hello world, sun is up" />

<dcs.If Target="$TestVar1" EndsWith="is up">
  <dc.Out>TestVar1 ends with "is up"</dc.Out>
</dcs.If>

Output:

TestVar1 ends with "is up"

CaseInsensitive

Any of the previous conditionals ( Contains, In, StartsWith, EndsWith ) can be combined with the CaseInsensitive keyword. When set to true, this keyword makes it so the string ignores upper or lower case distinctions during comparison.

<dcs.Var Name="TestVar1" Type="String" SetTo="hello world, sun is up" />

<dcs.If Target="$TestVar1" Contains="Sun" CaseInsensitive="true">
  <dc.Out>TestVar1 contains "sun"</dc.Out>
</dcs.If>

Output:

TestVar1 contains "sun"

Operations

TODO

Lower

This operation will convert the entire target string to lower case.

<dcs.Var Name="TestVar1" Type="String" SetTo="hello World, sun is UP" />

<dcs.With Target="$TestVar1">
  <Lower />
</dcs.With>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello world, sun is up

Note that you could also perform this operation in the dcs.Var statement. The code below would produce the exact same output as above.

<dcs.Var Name="TestVar1" Type="String" SetTo="hello World, sun is UP">
  <Lower />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Upper

The inverse to Lower , this operation will convert the entire target string to upper case.

<dcs.Var Name="TestVar1" Type="String" SetTo="hello World, sun is UP">
  <Upper />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = HELLO WORLD, SUN IS UP

Set

The Set keyword is another way to set the value of a string variable outside of the original declaration.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World, sun is UP" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello World, sun is UP

This can also be combined with other operations. In the below code, the string value is set, then converted to all uppercase and then finally to all lowercase

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World, sun is UP" />
  <Upper />
  <Lower />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello world, sun is up

Format

The Format operation has a variety of uses; please see the Format doc (link here) for a full listing. In this example, the list TestVar2 is joined together with the * character instead of the standard comma.

TODO create Format document and link to it.

<dcs.Var Name="TestVar2" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
</dcs.Var>

<dcs.Var Name="TestVar1" Type="String">
  <Format Value="$TestVar2" Pattern="join:*"  />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = car*sun*lime

Note that formatting can be applied in the Stringify syntax, as below. Furthermore, multiple formats can be chained.

<dcs.Var Name="TestVar2" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
</dcs.Var>

<dcs.Var Name="TestVar1" Type="String" SetTo="{$TestVar2|join:*|upper:}"  />

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = CAR*SUN*LIME

Append/AppendLine

The Append operation will add the string in the value to the end of the targeted string.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World" />
  <Append Value=", " />
  <Append Value="sun is UP" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello world, sun is UP

The AppendLine operation can add a line break into the string.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World" />
  <AppendLine />
  <Append Value="sun is UP" />
</dcs.Var>

<dc.Out><dc.Markdown>TestVar1 = {$TestVar1}</dc.Markdown></dc.Out>

Output:

TestVar1 = hello world
sun is UP

Prepend

The Prepend operation will add the string in the value to the beginning of the targeted string.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World" />
  <Prepend Value=", " />
  <Prepend Value="sun is UP" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = sun is UP, hello World

Replace

The Replace operation will search the string for any instances of the character or characters found matching the Old value, and replace them with the New value.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hejjo Worjd, sun is UP" />
  <Replace Old="j" New="l" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello World, sun is UP

Instead of using a fixed value, we can use the Pattern attribute to pass in a RegEx pattern. In the below example, the operation finds and digits in the string (defined as the RegEx pattern '/d') and replaces them with the character 'D'. (For more information on RegEx patterns, please read documentation here )

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="Mike's SSN is 123-45-6789" />
  <Replace Pattern="\d" New="D" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = Mike's SSN is DDD-DD-DDDD

Substring

The Substring operation will return a portion of the original string. This portion can be defined a few different ways. The From attribute defines the starting position; it defaults to 0 (the starting point of the string) and can be omitted. The To attribute defines the ending point. Alternatively, the Length attribute can be used if a fixed ending point is not know.

The simple graphic below may help explain the way that strings are indexed. For example, accessing the string 'cat' from 1 to 3 will return 'at'.

–C—-A—-T—-
0—-1—-2—-3

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World, sun is UP" />
  <Substring From="6" To="11" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = World

The below example returns the same output but uses the Length attribute.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="hello World, sun is UP" />
  <Substring From="6" Length="5" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = World

FillCode

The FillCode operation generates a random string of characters, the length of which is defined by the Length attribute. This can be useful for creating secure email or text verification key requests.

<dcs.Var Name="TestVar1" Type="String">
  <FillCode Length="15" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = cJ5d2Xjc2ot269o

GenerateUuid

The GenerateUuid operation generates a 128-bit value, that is, for practical purposes, unique to any other number generated via a similar method. (Please see this link for further reading.) This can be used as unique IDs for a variety of purposes.

<dcs.Var Name="TestVar1" Type="String">
  <GenerateUuid />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = 48819565455149fda23ad730a03de1f7

Trim

The Trim operation removes any whitespace from the beginning and end of that target string, keeping the internal whitespace intact. Note in the following example, the whitespace inside the string has been left alone by the Trim operation and then converted to underscores by the Replace operation.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="   hello World, sun is UP   " />
  <Trim />
  <Replace Pattern="\s" New="_" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello_World,_sun_is_UP

TrimStart

The TrimStart operation is similar to Trim but only removes the leading whitespace. Note that the trailing whitespace in the below example has been converted to underscores.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="   hello World, sun is UP   " />
  <Trim />
  <Replace Pattern="\s" New="_" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = hello_World,_sun_is_UP___

TrimEnd

The TrimEnd operation is the inverse of TrimStart .

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="   hello World, sun is UP   " />
  <Trim />
  <Replace Pattern="\s" New="_" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = ___hello_World,_sun_is_UP

LeftPad

The LeftPad operation takes the target string, and adds the character set in the With attribute to the beginning or left of the string until it reaches the length defined in the Size attribute. If no character is specified in the With attribute, it will default to a single space.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="789" />
  <LeftPad Size="5" With="0" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = 00789

RightPad

The RightPad operation functions identically to LeftPad but adds the character to the end or right of the string.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="789" />
  <RightPad Size="5" With="0" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = 78900

Split

The Split operation does not modify the existing string, but rather creates a new List variable with a name defined in the Result attribute. The operation will break up the target string based on the character set in the Delim attribute (if not specified, it defaults to comma) and populates the new list with the sections of the string.

The Delim attribute is a RegEx so special characters will need to be escaped, using the \ character. In the example below, we want to split up the string on the | character and so a \ is needed.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="rabbit|emu|donkey" />
  <Split Delim="\|" Result="TestVar2" />
</dcs.Var>

<dc.Out>TestVar2 = {$TestVar2}</dc.Out>

Output:

TestVar2 = [ "rabbit", "emu", "donkey" ]

IndexOf

The IndexOf operation returns the first index of the character defined in the Find attribute and assigns it to the variable named in Result . This can then be combined with other operations, such as SubString , to pass unknown or dynamic indices to those operations. In the example below, the first instance of the | character is found, and the first part of the string is reassigned to the initial variable and displayed.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="rabbit|emu|donkey" />
  <IndexOf Find="|" Result="TestVar2" />
  <Substring To="$TestVar2" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = rabbit

LastIndexOf

The LastIndexOf operation finds the last instance of a character defined in the Find attribute, the inverse of IndexOf . In the below example, the last instance of the | character is found and then the index is used with the Substring operation to obtain the last word in the first string. Note that the Inc operation is used to increase the index up one; otherwise the return value would include the | and be “|donkey”

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="rabbit|emu|donkey" />
  <LastIndexOf Find="|" Result="TestVar2" />
</dcs.Var>

<dcs.With Target="$TestVar2">
  <Inc />
</dcs.With>

<dcs.With Target="$TestVar1">
  <Substring From="$TestVar2" />
</dcs.With>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = donkey

HexEncode

The HexEncode operation converts the plaintext string into a hexadecimal value. This has a variety of uses in storage, data transfer, etc.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="rabbit|emu|donkey" />
  <HexEncode />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}</dc.Out>

Output:

TestVar1 = 7261626269747c656d757c646f6e6b6579

ParseJson

The ParseJson operation attempts to convert a string value into either a List or Record structure. It does not require the field or key portion of the record to be in quotes, and values that are strings can be either single or double quotes.

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="{ Name: 'andy', Age: 50 }" />
  <ParseJson Result="TestVar2" />
</dcs.Var>

<dc.Out>TestVar2 = {$TestVar2}</dc.Out>
<br/>
<dc.Out>TestVar2 Name = {$TestVar2.Name}</dc.Out>

Output:

TestVar2 = { "Age": 50, "Name": "andy" }
TestVar2 Name = andy

Markdown

The Markdown operation converts the raw string value into Markdown that the dC server can display. It has two modes, set in the Mode attribute - Safe mode can take raw HTML as input and display it properly; Unsafe mode assumes the input to be taken literally and will escape certain special character. Note that in the second example below, the < characters are converted to '<'

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="## Header" />
  <AppendLine />
  <Append Value="Copy here" />
  <AppendLine />
  <Append Value="- list a" />
  <AppendLine />
  <Append Value="- list b" />
  <AppendLine />
  <AppendLine />
  <Append Value="Final Copy <span style='color: red;'>here</span> and done." />
  <Markdown Mode="Safe" Result="TestVar2" />
</dcs.Var>

<dc.Out>TestVar2 = {$TestVar2}</dc.Out>

Output:

TestVar2 =

HEADER

Copy here

list a
list b

Final Copy here and done.

Markdown set to unsafe example:

<dcs.Var Name="TestVar1" Type="String">
  <Set Value="## Header" />
  <AppendLine />
  <Append Value="Copy here" />
  <AppendLine />
  <Append Value="- list a" />
  <AppendLine />
  <Append Value="- list b" />
  <AppendLine />
  <AppendLine />
  <Append Value="Final Copy <span style='color: red;'>here</span> and done." />
  <Markdown Mode="Unsafe" Result="TestVar2" />
</dcs.Var>

<dc.Out>TestVar2 = {$TestVar2}</dc.Out>

Output:

TestVar2 =

HEADER

Copy here

list a
list b

Final Copy < span style='color: red;'>here < /span> and done.

Summarize

Coming soon