# StringTools

A **StringTools** object provides several utility methods for encoding and decoding strings. For example, you can use a **StringTools** object to Base64-encode a chunk of data, or decode a UTF-8 encoded message header.

You can obtain a **StringTools** object using the [**DOpusFactory**](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/dopusfactory)**.StringTools** method.

| Method Name                                                          | **Arguments**                                                                                                                                                                                                                   | Return Type                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Decode                                                               | <p><<a href="blob"><strong>Blob</strong></a>:source> or \<string:source><br>\<string:format></p>                                                                                                                                | <p><em>string</em> or<br><a href="blob"><strong>Blob</strong></a></p> | <p>Decodes an encoded string or data.</p><p>You can provide either a <a href="blob"><strong>Blob</strong></a> object or a string as the <em>source</em> to decode. Depending on the value of the <em>format</em> argument, either a string or a <a href="blob"><strong>Blob</strong></a> is returned. Valid formats are:</p><p>If decoding UTF-8 or UTF-16 (via <strong>"auto"</strong> or <strong>"utf-8"</strong>, etc.), any byte-order-mark (BOM) will be skipped if one exists at the beginning of the input data.</p><p>If <em>format</em> is not specified the default is <strong>auto</strong>. Otherwise, <em>format</em> must be set to one of the above keywords or a valid code-page name (e.g. <strong>"gb2312"</strong>, <strong>"utf-8"</strong>), or a Windows code-page ID (e.g. <strong>936</strong>, <strong>65001</strong>). The source will be decoded using the specified code-page and a string is returned.</p> |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **base64**                                                           | The source will be *Base64*-decoded, and a [**Blob**](https://github.com/Chaoses-Ib/DirectoryOpus/blob/main/Manual/reference/scripting_reference/scripting_objects/blob/README.md) is returned.                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **quoted**                                                           | The source will be *Quoted-printable*-decoded, and a [**Blob**](https://github.com/Chaoses-Ib/DirectoryOpus/blob/main/Manual/reference/scripting_reference/scripting_objects/blob/README.md) is returned.                       |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **utf-8**                                                            | The source will be converted from UTF-8 to a native string.                                                                                                                                                                     |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| <p><strong>utf-16</strong><br><strong>utf-16-le</strong></p>         | The source will be converted from UTF-16 Little Endian to a native string.                                                                                                                                                      |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **utf-16-be**                                                        | The source will be converted from UTF-16 Big Endian to a native string.                                                                                                                                                         |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **auto**                                                             | Special handling is invoked to decode a MIME-encoded email subject (e.g. one beginning with **=?**), and a string is returned if identified. It will also detect UTF-8 or UTF-16 encoded data if it has a BOM at the beginning. |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| Encode                                                               | <p><<a href="blob"><strong>Blob</strong></a>:source> or \<string:source><br>\<string:format></p>                                                                                                                                | <p><em>string</em> or<br><a href="blob"><strong>Blob</strong></a></p> | <p>Encodes a string or data.</p><p>You can provide either a <a href="blob"><strong>Blob</strong></a> object or a string as the <em>source</em> to decode. Depending on the value of the <em>format</em> argument, either a string or a <a href="blob"><strong>Blob</strong></a> is returned. Valid formats are:</p><p>Otherwise, <em>format</em> must be set to a valid code-page name (e.g. <strong>"gb2312"</strong>, <strong>"utf-8"</strong> etc.), or a Windows code-page ID (e.g. <strong>936</strong>, <strong>65001</strong>). The source will be encoded using the specified code-page and a <a href="blob"><strong>Blob</strong></a> is returned.</p>                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **base64**                                                           | The source will be *Base64*-encoded, and a string is returned.                                                                                                                                                                  |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **quoted**                                                           | The source will be *Quoted-printable*-encoded, and a string is returned.                                                                                                                                                        |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **utf-8**                                                            | The source will be converted to UTF-8 without a byte-order-mark (BOM).                                                                                                                                                          |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **utf-8 bom**                                                        | The source will be converted to UTF-8 with a BOM at the start.                                                                                                                                                                  |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| <p><strong>utf-16</strong><br><strong>utf-16-le</strong></p>         | The source will be converted to UTF-16 Little Endian without a BOM.                                                                                                                                                             |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| <p><strong>utf-16 bom</strong><br><strong>utf-16-le bom</strong></p> | The source will be converted to UTF-16 Little Endian with a BOM.                                                                                                                                                                |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **utf-16-be**                                                        | The source will be converted to UTF-16 Big Endian without a BOM.                                                                                                                                                                |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **utf-16-be bom**                                                    | The source will be converted to UTF-16 Big Endian with a BOM.                                                                                                                                                                   |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| IsASCII                                                              | \<string:input>                                                                                                                                                                                                                 | *bool*                                                                | <p>Tests the input string to see if it only contains characters that can be represented in ASCII.</p><p>If the result is false, the string is not safe to save into a text file unless you use a Unicode format such as UTF-8.</p><p>This check is not affected by locales or codepages. Instead, it tests whether the string consists of only 7-bit ASCII characters, such that no characters will be lost or modified if you save the string to a text file and then load it back on any other computer.</p>                                                                                                                                                                                                                                                                                                                                                                                                                          |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| LanguageStr                                                          | <p>\<string:name> or<br>\<int:id></p>                                                                                                                                                                                           | *string*                                                              | <p>Returns a translated string in the currently selected language. Mainly needed for internal use.</p><p>The currently defined strings are:</p><p>\<string:name> \[\<string:flags>]</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | *string* | <p>Strips any illegal filename characters from the supplied string.</p><p>The optional flags are:</p><p>\<string:input></p> | *string* | <p>Returns a copy of the input string with any diacritics (accent symbols) removed. For example, "á" would be converted to "a".</p><p>This function uses the same rules that are used by the "ignore diacritics" options for pattern matching throughout Opus.</p> |
| ID                                                                   | English language string                                                                                                                                                                                                         |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| FavoritesBar                                                         | Favorites Bar                                                                                                                                                                                                                   |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| FindResults                                                          | Find Results                                                                                                                                                                                                                    |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| CopySelection                                                        | Copy Selection                                                                                                                                                                                                                  |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| CopyAll                                                              | Copy All                                                                                                                                                                                                                        |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
|                                                                      |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
|                                                                      |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| MakeLegal                                                            |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
|                                                                      |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **f**                                                                | forward slashes: convert separators to `/` instead of `\`                                                                                                                                                                       |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **n**                                                                | name instead of path: replace separators with `_` (implies **s**)                                                                                                                                                               |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| **s**                                                                | subdirectory mode: replace `:` with `;` and remove `\\` from UNC paths                                                                                                                                                          |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
|                                                                      |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
|                                                                      |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| RemoveDiacritics                                                     |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| Truncate                                                             | \<string:input> or *object*:[Path](https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/path) \<int:length> \[\<int:type>]                                                       | *string*                                                              | <p>Truncates the specified input string to the requested number of characters.</p><p>The optional <em>type</em> argument specifies the truncation type. Valid values are:</p><p>If not specified, the default is <strong>2</strong> if <em>input</em> is a <a href="path">Path</a> object, otherwise the default is <strong>0</strong>.</p><p>If the input value is a <a href="path">Path</a> and middle truncation is selected, the function takes path separators into account correctly.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
|                                                                      |                                                                                                                                                                                                                                 |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| 0                                                                    | truncate on the right                                                                                                                                                                                                           |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| 1                                                                    | truncate on the left                                                                                                                                                                                                            |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |
| 2                                                                    | truncate in the middle                                                                                                                                                                                                          |                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |          |                                                                                                                             |          |                                                                                                                                                                                                                                                                    |

|   |                        |
| - | ---------------------- |
| 0 | truncate on the right  |
| 1 | truncate on the left   |
| 2 | truncate in the middle |

|                  |                                                                        |   |
| ---------------- | ---------------------------------------------------------------------- | - |
| **f**            | forward slashes: convert separators to `/` instead of `\`              |   |
| **n**            | name instead of path: replace separators with `_` (implies **s**)      |   |
| **s**            | subdirectory mode: replace `:` with `;` and remove `\\` from UNC paths |   |
|                  |                                                                        |   |
|                  |                                                                        |   |
| RemoveDiacritics |                                                                        |   |

| ID            | English language string |   |
| ------------- | ----------------------- | - |
| FavoritesBar  | Favorites Bar           |   |
| FindResults   | Find Results            |   |
| CopySelection | Copy Selection          |   |
| CopyAll       | Copy All                |   |
|               |                         |   |
|               |                         |   |
| MakeLegal     |                         |   |

| **base64**                                                           | The source will be *Base64*-encoded, and a string is returned.           |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **quoted**                                                           | The source will be *Quoted-printable*-encoded, and a string is returned. |
| **utf-8**                                                            | The source will be converted to UTF-8 without a byte-order-mark (BOM).   |
| **utf-8 bom**                                                        | The source will be converted to UTF-8 with a BOM at the start.           |
| <p><strong>utf-16</strong><br><strong>utf-16-le</strong></p>         | The source will be converted to UTF-16 Little Endian without a BOM.      |
| <p><strong>utf-16 bom</strong><br><strong>utf-16-le bom</strong></p> | The source will be converted to UTF-16 Little Endian with a BOM.         |
| **utf-16-be**                                                        | The source will be converted to UTF-16 Big Endian without a BOM.         |
| **utf-16-be bom**                                                    | The source will be converted to UTF-16 Big Endian with a BOM.            |

| **base64**                                                   | The source will be *Base64*-decoded, and a [**Blob**](https://github.com/Chaoses-Ib/DirectoryOpus/blob/main/Manual/reference/scripting_reference/scripting_objects/blob/README.md) is returned.                                 |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **quoted**                                                   | The source will be *Quoted-printable*-decoded, and a [**Blob**](https://github.com/Chaoses-Ib/DirectoryOpus/blob/main/Manual/reference/scripting_reference/scripting_objects/blob/README.md) is returned.                       |
| **utf-8**                                                    | The source will be converted from UTF-8 to a native string.                                                                                                                                                                     |
| <p><strong>utf-16</strong><br><strong>utf-16-le</strong></p> | The source will be converted from UTF-16 Little Endian to a native string.                                                                                                                                                      |
| **utf-16-be**                                                | The source will be converted from UTF-16 Big Endian to a native string.                                                                                                                                                         |
| **auto**                                                     | Special handling is invoked to decode a MIME-encoded email subject (e.g. one beginning with **=?**), and a string is returned if identified. It will also detect UTF-8 or UTF-16 encoded data if it has a BOM at the beginning. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://chaoses-ib.gitbook.io/directory-opus/manual/reference/scripting_reference/scripting_objects/stringtools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.