Primarily-text-type string functions

Text-type functions, as the name would imply, affect strings that contain text (where "text" means any combination of characters that are not strictly numbers). In all the functions below, *value* is any combination of text. Strings can also be utilized in the parameter, such as *{string<sn>}.set({string<text>}).*

Note: Most of these functions also apply to string that contain numbered values. The Number-type functions page covers functions that exclusively apply to number-type string; this page contains all other string functions.

 .set(value)

Sets the value of the string.

**Example:**

```
do {string<sn>}.set(true)
if {string<sn>}
  chat Successful
end

```

This series of events will output "Successful", because the string was set to *true.*

Also used to set strings after they have been modified by other string functions. If you are using a *.set()* function at the end of a series of string functions, you must insert a tilde into the parameter.

**Example:**

```
do {string<sn>}.add(5).divide(2).set(~)

```

## .save(value)

Similar to *.set()* in that it will change the value of a string, however it will also update the value in .minecraft\mods\ChatTriggers\strings.txt. Using *.set()* is advised if you do not want string.txt to constantly update.

## .equals(value)

Used with logic events. Tests if the string in question is equal to the value you are checking for. It will return *true* if the tested value matches the value of the string. Primarily used with if statements. *As of version 5.0, you can also use the == comparator in if statements.*

**Example:**

```
do {string<sn>}.set(Chat Triggers!)
if {string<sn>}.equals(Chat Triggers!)
  chat Success
end

```

This series of events will output "Success" because *{string<sn>}* was equal to *Chat Triggers!*.

## .startsWith(value)

Tests if the string starts with a given value. There is no limit as to how much of the string you can check for, but it checks the string from left to right.

**Example:**

```
do {string<sn>}.set(Today is a beautiful day)
if {string<sn>}.startsWith(T)
  chat String starts with "T"!
end
if {string<sn>}.startsWith(Today is )
  chat String starts with "Today is "!
end

```

This series of events will output both phrases: "*String starts with "T"!*" *and* "*String starts with "Today is "!*".

## .contains(value)

Tests if the string contains a given value. It will return true as long as the string contains *value* anywhere inside of the string, whether it be part of the string or all of it.

## .endsWith(value)

Similar to .startsWith(value), except that it checks from right to left rather than left to right.

## .replace(value1,value2)

One of the most useful functions in the mod. This function will check for *value1* inside of a string, and if found, replace it with *value2*.

**Example:**

```
do {string<sn>}.set(This is a string!)
if {string<sn>}.contains(string!)
  do {string<sn>}.replace(string!,very cool string!)
end
chat {string<sn>}

```

This series of events will output the phrase "This is a very cool string!" because the word "string!" was replaced with the phrase "very cool string!"

The .replace() function can also be used to delete certain phrases from strings. This is accomplished by omitting the second function argument.

**Example:**

```
do {string<sn>}.set(This is a string!)
chat {string<sn>}.replace(This is)

```

This will output " *a string!*", because the phrase "*This is*" was deleted by the .replace() function.

## .subString(value1,value2)

Returns a part of the string that is between *value1* and *value2*. The returned text does not include *value1* and *value2*.

**Example:**

```
do {string<sn>}.set(ChatTriggers is a cool Minecraft mod)
chat {string<sn>}.subString(ChatTriggers,Minecraft).replace( , &6)

```

This series of events will output the phrase " &6is &6a &6cool &6". When in-game, the color codes will automatically get converted to colors, therefore you will not actually see the "&6"'s, but rather just colored text.

The subString function also accepts numbers. A number in this function refers to the character numbers of the string. The following is the example above, but with numbers:

**Example:**

```
do {string<sn>}.set(ChatTriggers is a cool Minecraft mod)
chat {string<sn>}.subString(12,24).replace( , &6)

```

There are multiple tags that can be included in the function arguments:

* <include> or <i> - function output will include this endpoint
* <end> or <e> - gets the end of the string (the same as using *{string<sn>}.length()*)
* <start> or
 - gets the start of the string (the same as using 0)

## .trim()

Removes excess space characters. Excess in this sense means more than one, so any amount of consecutive space characters over one will be reduced to one. This function will also remove space characters at the very beginning and end of the string, regardless of the amount (even if it is only one).

**Example:**

```
do {string<sn>}.set( This      is   very                  fun  )
chat {string<sn>}.trim()

```

This series of events will output "This is very fun".

*Note: This function has no parameter.*

## .prefix(value) / .suffix(value)

These functions will prepend and append, respectively, text to the string. It is important to note that these functions do not save the prepended or appended text to the string, so if you need to save the string, you must include *.set(~)* after the function.

**Example:**

```
do {string<sn>}.set(Look! A string!)
chat {string<sn>}.prepend(Wow! )

```

This series of events will output the phrase "Wow! Look! A string!"

## .toUpper() / .toLower()

Returns the string in all upper case and lower case, respectively.

*Note: This function has no parameter.*

## .removeFormatting()

Removes all formatting codes in the string it is applied to. As a result, printing a string with this function will always result in completely white text.

**Alias:** .remForm()

*Note: This function has no parameter.*

## .capitalizeFirstWord() / .capitalizeAllWords()

Capitalizes either the first word of the string, or all words in a string, respectively.

**Example:**

```
do {string<sn>}.set(hello this is an example)
chat {string<sn>}.capitalizeAllWords()

```

This series of events will output the phrase "Hello This Is An Example"

*Note: This function has no parameter.*

## .ignoreEscape()

Prevents escaped characters from actually escaping. They will just output as normal text if the string is used in a chat event.

*Note: This function has no parameter.*

## .length()

Returns the number of characters in a given string.

Example:

```
do {string<sn>}.set(Functions are cool!)
chat {string<sn>}.length()

```

This series of events will output "19", because there are 19 characters in the string.

*Note: This function has no parameter.*

## .size()

Returns the size of the string in pixels across the user's screen. Useful for centering strings in the middle of a user's chat box.