> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-language/reference/types/stringbuilder.md).

# stringbuilder

BoxLang first-class `StringBuilder` type.

Wraps `java.lang.StringBuilder` and exposes a fluent, mutable string-buffer API to BoxLang code. All positional parameters are *1-based* (BoxLang convention); the wrapper subtracts/adds 1 before delegating to the underlying buffer.

A `BoxStringBuilder` silently casts to `String` anywhere the runtime needs a string — via `ortus.boxlang.runtime.dynamic.casters.StringCasterStrict`. This allows all existing string BIFs and member methods to operate on an `sb` value without any explicit conversion.

Create instances via:

* Literal: `sb{"initial value"`} or `stringbuilder{"initial value"`} (Box parser only)
* BIF: `stringBuilderNew()` or `stringBuilderNew("initial", 128)`

## StringBuilder Methods

<details>

<summary><code>append(value=[any])</code></summary>

Appends the string representation of value to the end of the StringBuilder buffer.

### Method Signature

```
append(value=[any])
```

### Arguments

| Argument | Type  | Required | Description                             | Default |
| -------- | ----- | -------- | --------------------------------------- | ------- |
| `value`  | `any` | `true`   | The value to append. Coerced to string. |         |

</details>

<details>

<summary><code>clear()</code></summary>

Resets the StringBuilder buffer to empty.

### Method Signature

```
clear()
```

### Arguments

This function does not accept any arguments

</details>

<details>

<summary><code>contains(substring=[string])</code></summary>

No description available

### Method Signature

```
contains(substring=[string])
```

### Arguments

| Argument    | Type     | Required | Description | Default |
| ----------- | -------- | -------- | ----------- | ------- |
| `substring` | `string` | `true`   |             |         |

</details>

<details>

<summary><code>containsNoCase(substring=[string])</code></summary>

No description available

### Method Signature

```
containsNoCase(substring=[string])
```

### Arguments

| Argument    | Type     | Required | Description | Default |
| ----------- | -------- | -------- | ----------- | ------- |
| `substring` | `string` | `true`   |             |         |

</details>

<details>

<summary><code>delete(start=[integer], end=[integer])</code></summary>

Removes characters from start to end, both 1-based and inclusive.

### Method Signature

```
delete(start=[integer], end=[integer])
```

### Arguments

| Argument | Type      | Required | Description                             | Default |
| -------- | --------- | -------- | --------------------------------------- | ------- |
| `start`  | `integer` | `true`   | The 1-based start position (inclusive). |         |
| `end`    | `integer` | `true`   | The 1-based end position (inclusive).   |         |

</details>

<details>

<summary><code>endsWith(substring=[string])</code></summary>

No description available

### Method Signature

```
endsWith(substring=[string])
```

### Arguments

| Argument    | Type     | Required | Description | Default |
| ----------- | -------- | -------- | ----------- | ------- |
| `substring` | `string` | `true`   |             |         |

</details>

<details>

<summary><code>find(substring=[string], start=[integer])</code></summary>

No description available

### Method Signature

```
find(substring=[string], start=[integer])
```

### Arguments

| Argument    | Type      | Required | Description | Default |
| ----------- | --------- | -------- | ----------- | ------- |
| `substring` | `string`  | `true`   |             |         |
| `start`     | `integer` | `false`  |             | `1`     |

</details>

<details>

<summary><code>findNoCase(substring=[string], start=[integer])</code></summary>

No description available

### Method Signature

```
findNoCase(substring=[string], start=[integer])
```

### Arguments

| Argument    | Type      | Required | Description | Default |
| ----------- | --------- | -------- | ----------- | ------- |
| `substring` | `string`  | `true`   |             |         |
| `start`     | `integer` | `false`  |             | `1`     |

</details>

<details>

<summary><code>insert(position=[integer], value=[any])</code></summary>

Inserts value at the given 1-based position in the StringBuilder buffer.

### Method Signature

```
insert(position=[integer], value=[any])
```

### Arguments

| Argument   | Type      | Required | Description                                        | Default |
| ---------- | --------- | -------- | -------------------------------------------------- | ------- |
| `position` | `integer` | `true`   | The 1-based character position at which to insert. |         |
| `value`    | `any`     | `true`   | The value to insert. Coerced to string.            |         |

</details>

<details>

<summary><code>isEmpty()</code></summary>

Determine whether a given value is empty.

We check for emptiness of anything that can be casted to: Array, Struct, Query, or String.

### Method Signature

```
isEmpty()
```

### Arguments

This function does not accept any arguments

</details>

<details>

<summary><code>left(count=[integer])</code></summary>

No description available

### Method Signature

```
left(count=[integer])
```

### Arguments

| Argument | Type      | Required | Description | Default |
| -------- | --------- | -------- | ----------- | ------- |
| `count`  | `integer` | `true`   |             |         |

</details>

<details>

<summary><code>len()</code></summary>

Returns the absolute value of a number

### Method Signature

```
len()
```

### Arguments

This function does not accept any arguments

</details>

<details>

<summary><code>mid(start=[integer], count=[integer])</code></summary>

No description available

### Method Signature

```
mid(start=[integer], count=[integer])
```

### Arguments

| Argument | Type      | Required | Description | Default |
| -------- | --------- | -------- | ----------- | ------- |
| `start`  | `integer` | `true`   |             |         |
| `count`  | `integer` | `false`  |             |         |

</details>

<details>

<summary><code>prepend(value=[any])</code></summary>

Inserts the string representation of value at the beginning (position 1) of the buffer.

### Method Signature

```
prepend(value=[any])
```

### Arguments

| Argument | Type  | Required | Description                                          | Default |
| -------- | ----- | -------- | ---------------------------------------------------- | ------- |
| `value`  | `any` | `true`   | The value to insert at the start. Coerced to string. |         |

</details>

<details>

<summary><code>replace(start=[integer], end=[integer], value=[any])</code></summary>

Replaces characters from start to end (1-based, inclusive) with value.

### Method Signature

```
replace(start=[integer], end=[integer], value=[any])
```

### Arguments

| Argument | Type      | Required | Description                              | Default |
| -------- | --------- | -------- | ---------------------------------------- | ------- |
| `start`  | `integer` | `true`   | The 1-based start position (inclusive).  |         |
| `end`    | `integer` | `true`   | The 1-based end position (inclusive).    |         |
| `value`  | `any`     | `true`   | The replacement text. Coerced to string. |         |

</details>

<details>

<summary><code>reverse()</code></summary>

Reverses the contents of the StringBuilder buffer in place.

### Method Signature

```
reverse()
```

### Arguments

This function does not accept any arguments

</details>

<details>

<summary><code>right(count=[integer])</code></summary>

No description available

### Method Signature

```
right(count=[integer])
```

### Arguments

| Argument | Type      | Required | Description | Default |
| -------- | --------- | -------- | ----------- | ------- |
| `count`  | `integer` | `true`   |             |         |

</details>

<details>

<summary><code>startsWith(substring=[string])</code></summary>

No description available

### Method Signature

```
startsWith(substring=[string])
```

### Arguments

| Argument    | Type     | Required | Description | Default |
| ----------- | -------- | -------- | ----------- | ------- |
| `substring` | `string` | `true`   |             |         |

</details>

<details>

<summary><code>trim()</code></summary>

Strips leading and trailing whitespace from the buffer in place.

### Method Signature

```
trim()
```

### Arguments

This function does not accept any arguments

</details>

## Java Methods

> **Use at your own risk:** These are the public methods of the native Java class `java.lang.StringBuilder`, documented from the JDK 21 javadocs. They are not part of the BoxLang API, are not tested or supported by BoxLang, and may change between Java versions. Java methods with the same name as one of the BoxLang member functions above are not listed, as the BoxLang member function is called instead.

<details>

<summary><code>StringBuilder appendCodePoint(int codePoint)</code></summary>

</details>

<details>

<summary><code>int compareTo(StringBuilder another)</code></summary>

Compares two `StringBuilder` instances lexicographically. This method follows the same rules for lexicographical comparison as defined in the `java.lang.CharSequence) CharSequence.compare(this, another)` method.

For finer-grained, locale-sensitive String comparison, refer to `java.text.Collator`.

**Parameters:**

* `another` - the `StringBuilder` to be compared with

**Returns:** the value `0` if this `StringBuilder` contains the same character sequence as that of the argument `StringBuilder`; a negative integer if this `StringBuilder` is lexicographically less than the `StringBuilder` argument; or a positive integer if this `StringBuilder` is lexicographically greater than the `StringBuilder` argument.

</details>

<details>

<summary><code>StringBuilder deleteCharAt(int index)</code></summary>

</details>

<details>

<summary><code>int indexOf(String str)</code></summary>

Returns the index within this string of the first occurrence of the specified substring.

The returned index is the smallest value `k` for which:

```
this.toString().startsWith(str, k)
```

If no such value of `k` exists, then `-1` is returned.

**Parameters:**

* `str` - the substring to search for.

**Returns:** the index of the first occurrence of the specified substring, or `-1` if there is no such occurrence.

</details>

<details>

<summary><code>int indexOf(String str, int fromIndex)</code></summary>

Returns the index within this string of the first occurrence of the specified substring, starting at the specified index.

The returned index is the smallest value `k` for which:

```
k >= Math.min(fromIndex, this.length()) &&
                   this.toString().startsWith(str, k)
```

If no such value of `k` exists, then `-1` is returned.

**Parameters:**

* `str` - the substring to search for.
* `fromIndex` - the index from which to start the search.

**Returns:** the index of the first occurrence of the specified substring, starting at the specified index, or `-1` if there is no such occurrence.

</details>

<details>

<summary><code>int lastIndexOf(String str)</code></summary>

Returns the index within this string of the last occurrence of the specified substring. The last occurrence of the empty string "" is considered to occur at the index value `this.length()`.

The returned index is the largest value `k` for which:

```
this.toString().startsWith(str, k)
```

If no such value of `k` exists, then `-1` is returned.

**Parameters:**

* `str` - the substring to search for.

**Returns:** the index of the last occurrence of the specified substring, or `-1` if there is no such occurrence.

</details>

<details>

<summary><code>int lastIndexOf(String str, int fromIndex)</code></summary>

Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the specified index.

The returned index is the largest value `k` for which:

```
k <= Math.min(fromIndex, this.length()) &&
                   this.toString().startsWith(str, k)
```

If no such value of `k` exists, then `-1` is returned.

**Parameters:**

* `str` - the substring to search for.
* `fromIndex` - the index to start the search from.

**Returns:** the index of the last occurrence of the specified substring, searching backward from the specified index, or `-1` if there is no such occurrence.

</details>

<details>

<summary><code>StringBuilder repeat(CharSequence cs, int count)</code></summary>

</details>

<details>

<summary><code>StringBuilder repeat(int codePoint, int count)</code></summary>

</details>

<details>

<summary><code>String toString()</code></summary>

Returns a string representing the data in this sequence. A new `String` object is allocated and initialized to contain the character sequence currently represented by this object. This `String` is then returned. Subsequent changes to this sequence do not affect the contents of the `String`.

**Returns:** a string representation of this sequence of characters.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://boxlang.ortusbooks.com/boxlang-language/reference/types/stringbuilder.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.