# Replace

Replaces occurrences of substring1 in a string with obj, in a specified scope.

The search is case-sensitive. Function returns original string with replacements made

## Method Signature

```
Replace(string=[string], substring1=[string], obj=[any], scope=[string])
```

### Arguments

| Argument     | Type     | Required | Description                                             | Default |
| ------------ | -------- | -------- | ------------------------------------------------------- | ------- |
| `string`     | `string` | `true`   | The string to search                                    |         |
| `substring1` | `string` | `true`   | The substring to search for                             |         |
| `obj`        | `any`    | `true`   | The string to replace substring1 with                   |         |
| `scope`      | `string` | `true`   | The scope to search in. Valid values are "one" or "all" | `one`   |

## Examples

### Replace uppercase 'U' with lowercase 'u'

Replace in Script Syntax

[Run Example](https://try.boxlang.io?code=eJxLTy0JS8xRsFUoSi3ISUxO1VBQcsqvyEnMS1fSUVAKBRGlSgqa1lzlRZklqS6luQUaCukQPZrWAEpOEnw%3D)

```java
getVal = replace( "Boxlang", "U", "u" );
writeDump( getVal );

```

Result: Boxlang

### Replace uppercase 'O' with lowercase 'o', but only once

Something similar in Tag Syntax

[Run Example](https://try.boxlang.io?code=eJxLSEiwSaqwKk4tUUhPLQlLzDFUsFUoSi3ISUxO1VBQcsqvyEnMS1fSUVDyBxH5YJafq5KCpoIdF0hnSmlugUJZYpGtkjLUAGUlfbuEhAQA3xIaeQ%3D%3D)

```java
<bx:set getVal1 = replace( "Boxlang", "O", "o", "ONE" ) >
<bx:dump var="#getVal1#"/>
```

Result: Boxlang

### Example using Callback Function

You can pass in a callback function to the third argument of the `replace` function

[Run Example](https://try.boxlang.io/?code=eJwtjcEKwjAMhs%2F2KX562mD4AuJheB34DLFUKdSsZAkyxHe3pbskfEm%2BP67YI6eAp3HQtDKs3GiLA2beUUg1Ck8d1i21i06rpBdGfN1JoppUr2uHgvHifk7iZllxhcSSKdS1n%2FEmBqFya4GY8tlP8MS19ueV5mXxLeMjSePdtJgOOOLq%2BA%2FPgDrf)

```java

public function upCase( Any pattern, Any position, Any orig ) {
	return uCase( pattern );
}
result = replace( "A man a plan a canal.", "an", upCase, "ALL" );
writeOutput( result );

```

Result: A mAN a plAN a cANal.

### Example with start argument (Replace lowercase 'o' with uppercase 'O' from the third position)

You can pass position to start searching in the string

[Run Example](https://try.boxlang.io/?code=eJxLTy0JSi1WsFUoSi3ISUxO1VBQ8skvS1Vwzs9JcSstzszPU9JRUMoHEf4gwtHHB0QZKyloWnOVF2WWpPqXlhSUlmgopENMAgoDADjeGJA%3D)

```java
getRes = replace( "Love Boxlang", "o", "O", "ALL", "3" );
writeOutput( getRes );

```

Result: Love Boxlang

### Additional Examples

```java
writeDump( replace( "xxabcxxabcxx", "abc", "def" ) );
writeDump( replace( "xxabcxxabcxx", "abc", "def", "All" ) );
writeDump( replace( "abc", "a", "b", "all" ) );
writeDump( replace( "a.b.c.d", ".", "-", "all" ) );
test = "camelcase CaMeLcAsE CAMELCASE";
test2 = Replace( test, "camelcase", "CamelCase", "all" );
writeDump( test2 );
replacer = ( Any find, Any index, Any input ) => {
	dump( var=arguments, label="replacement arguments" );
	return "-#index#-";
};
writeDump( var=replace( "one string, two strings, three strings", "string", replacer, "all" ), label="replace with a function" );
writeDump( var=replace( "one string, two strings, three strings", {
	"one" : 1,
	"two" : 2,
	"three" : 3,
	"string" : "txt",
	"text" : "string"
} ), label="replace via a struct" );
 // struct keys need to be quoted

```

## Related

* [Ascii](/boxlang-language/reference/built-in-functions/string/ascii.md)
* [CamelCase](/boxlang-language/reference/built-in-functions/string/camelcase.md)
* [Char](/boxlang-language/reference/built-in-functions/string/char.md)
* [CharsetDecode](/boxlang-language/reference/built-in-functions/string/charsetdecode.md)
* [CharsetEncode](/boxlang-language/reference/built-in-functions/string/charsetencode.md)
* [Compare](/boxlang-language/reference/built-in-functions/string/compare.md)
* [CompareNoCase](/boxlang-language/reference/built-in-functions/string/comparenocase.md)
* [Find](/boxlang-language/reference/built-in-functions/string/find.md)
* [FindNoCase](/boxlang-language/reference/built-in-functions/string/findnocase.md)
* [FindOneOf](/boxlang-language/reference/built-in-functions/string/findoneof.md)
* [Insert](/boxlang-language/reference/built-in-functions/string/insert.md)
* [JSStringFormat](/boxlang-language/reference/built-in-functions/string/jsstringformat.md)
* [Justify](/boxlang-language/reference/built-in-functions/string/justify.md)
* [KebabCase](/boxlang-language/reference/built-in-functions/string/kebabcase.md)
* [LCase](/boxlang-language/reference/built-in-functions/string/lcase.md)
* [Left](/boxlang-language/reference/built-in-functions/string/left.md)
* [ListReduce](/boxlang-language/reference/built-in-functions/string/listreduce.md)
* [LJustify](/boxlang-language/reference/built-in-functions/string/ljustify.md)
* [LTrim](/boxlang-language/reference/built-in-functions/string/ltrim.md)
* [Mid](/boxlang-language/reference/built-in-functions/string/mid.md)
* [ParagraphFormat](/boxlang-language/reference/built-in-functions/string/paragraphformat.md)
* [PascalCase](/boxlang-language/reference/built-in-functions/string/pascalcase.md)
* [QueryStringToStruct](/boxlang-language/reference/built-in-functions/string/querystringtostruct.md)
* [ReEscape](/boxlang-language/reference/built-in-functions/string/reescape.md)
* [ReFind](/boxlang-language/reference/built-in-functions/string/refind.md)
* [reFindNoCase](/boxlang-language/reference/built-in-functions/string/refindnocase.md)
* [ReMatch](/boxlang-language/reference/built-in-functions/string/rematch.md)
* [reMatchNoCase](/boxlang-language/reference/built-in-functions/string/rematchnocase.md)
* [RemoveChars](/boxlang-language/reference/built-in-functions/string/removechars.md)
* [RepeatString](/boxlang-language/reference/built-in-functions/string/repeatstring.md)
* [ReplaceList](/boxlang-language/reference/built-in-functions/string/replacelist.md)
* [ReplaceListNoCase](/boxlang-language/reference/built-in-functions/string/replacelistnocase.md)
* [ReplaceNoCase](/boxlang-language/reference/built-in-functions/string/replacenocase.md)
* [ReReplace](/boxlang-language/reference/built-in-functions/string/rereplace.md)
* [reReplaceNoCase](/boxlang-language/reference/built-in-functions/string/rereplacenocase.md)
* [Reverse](/boxlang-language/reference/built-in-functions/string/reverse.md)
* [Right](/boxlang-language/reference/built-in-functions/string/right.md)
* [RJustify](/boxlang-language/reference/built-in-functions/string/rjustify.md)
* [RTrim](/boxlang-language/reference/built-in-functions/string/rtrim.md)
* [Slugify](/boxlang-language/reference/built-in-functions/string/slugify.md)
* [SnakeCase](/boxlang-language/reference/built-in-functions/string/snakecase.md)
* [SpanExcluding](/boxlang-language/reference/built-in-functions/string/spanexcluding.md)
* [SpanIncluding](/boxlang-language/reference/built-in-functions/string/spanincluding.md)
* [SQLPrettify](/boxlang-language/reference/built-in-functions/string/sqlprettify.md)
* [StringBind](/boxlang-language/reference/built-in-functions/string/stringbind.md)
* [StringEach](/boxlang-language/reference/built-in-functions/string/stringeach.md)
* [StringEvery](/boxlang-language/reference/built-in-functions/string/stringevery.md)
* [StringFilter](/boxlang-language/reference/built-in-functions/string/stringfilter.md)
* [StringMap](/boxlang-language/reference/built-in-functions/string/stringmap.md)
* [StringReduce](/boxlang-language/reference/built-in-functions/string/stringreduce.md)
* [StringReduceRight](/boxlang-language/reference/built-in-functions/string/stringreduceright.md)
* [StringSome](/boxlang-language/reference/built-in-functions/string/stringsome.md)
* [StringSort](/boxlang-language/reference/built-in-functions/string/stringsort.md)
* [StripCR](/boxlang-language/reference/built-in-functions/string/stripcr.md)
* [Trim](/boxlang-language/reference/built-in-functions/string/trim.md)
* [TrueFalseFormat](/boxlang-language/reference/built-in-functions/string/truefalseformat.md)
* [UCase](/boxlang-language/reference/built-in-functions/string/ucase.md)
* [UCFirst](/boxlang-language/reference/built-in-functions/string/ucfirst.md)
* [Val](/boxlang-language/reference/built-in-functions/string/val.md)
* [Wrap](/boxlang-language/reference/built-in-functions/string/wrap.md)
* [YesNoFormat](/boxlang-language/reference/built-in-functions/string/yesnoformat.md)


---

# 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://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/string/replace.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.