RangeBuilder

A builder used to construct `Range` objects from document elements.

```javascript
// Change the user's selection to a range that includes every table in the
// active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const rangeBuilder = documentTab.newRange();
const tables = documentTab.getBody().getTables();
for (let i = 0; i < tables.length; i++) {
  rangeBuilder.addElement(tables[i]);
}
doc.setSelection(rangeBuilder.build());
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/document/range-builder#addElement(Element)` | `https://developers.google.com/apps-script/reference/document/range-builder#` | Adds an entire `https://developers.google.com/apps-script/reference/document/element` to this `RangeBuilder`. |
| `https://developers.google.com/apps-script/reference/document/range-builder#addElement(Text,Integer,Integer)` | `https://developers.google.com/apps-script/reference/document/range-builder#` | Adds a partial `https://developers.google.com/apps-script/reference/document/text` element to this `RangeBuilder`. |
| `https://developers.google.com/apps-script/reference/document/range-builder#addElementsBetween(Element,Element)` | `https://developers.google.com/apps-script/reference/document/range-builder#` | Adds two entire elements, and all elements between them, to this `RangeBuilder`. |
| `https://developers.google.com/apps-script/reference/document/range-builder#addElementsBetween(Text,Integer,Text,Integer)` | `https://developers.google.com/apps-script/reference/document/range-builder#` | Adds two partial `https://developers.google.com/apps-script/reference/document/text` elements, and all elements between them, to the `RangeBuilder`. |
| `https://developers.google.com/apps-script/reference/document/range-builder#addRange(Range)` | `https://developers.google.com/apps-script/reference/document/range-builder#` | Adds the contents of another `Range` to this `RangeBuilder`. |
| `https://developers.google.com/apps-script/reference/document/range-builder#build()` | `https://developers.google.com/apps-script/reference/document/range` | Constructs a `Range` from the settings applied to the builder. |
| `https://developers.google.com/apps-script/reference/document/range-builder#getRangeElements()` | `https://developers.google.com/apps-script/reference/document/range-element` | Gets all elements in this `Range`, including any partial `https://developers.google.com/apps-script/reference/document/text` elements (for example, in the case of a selection that includes only part of a `Text` element). |

### Deprecated methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/document/range-builder#getSelectedElements()` | `https://developers.google.com/apps-script/reference/document/range-element` | Gets all elements that the user has selected in the open instance of the document, including any partially selected `https://developers.google.com/apps-script/reference/document/text` elements. |

## Detailed documentation

### `addElement(element)`

Adds an entire `https://developers.google.com/apps-script/reference/document/element` to this `RangeBuilder`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `element` | `https://developers.google.com/apps-script/reference/document/element` | the element to be added |

#### Return


`https://developers.google.com/apps-script/reference/document/range-builder#` --- this builder, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `addElement(textElement, startOffset, endOffsetInclusive)`

Adds a partial `https://developers.google.com/apps-script/reference/document/text` element to this `RangeBuilder`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textElement` | `https://developers.google.com/apps-script/reference/document/text` | the text element to be partially added |
| `startOffset` | `Integer` | the number of characters before the first character to be included (that is, the index of the first character in the range) |
| `endOffsetInclusive` | `Integer` | the number of characters before the last character to be included (that is, the index of the last character in the range) |

#### Return


`https://developers.google.com/apps-script/reference/document/range-builder#` --- this builder, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `addElementsBetween(startElement, endElementInclusive)`

Adds two entire elements, and all elements between them, to this `RangeBuilder`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `startElement` | `https://developers.google.com/apps-script/reference/document/element` | the first element to be added |
| `endElementInclusive` | `https://developers.google.com/apps-script/reference/document/element` | the last element to be added |

#### Return


`https://developers.google.com/apps-script/reference/document/range-builder#` --- this builder, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `addElementsBetween(startTextElement, startOffset, endTextElementInclusive, endOffsetInclusive)`

Adds two partial `https://developers.google.com/apps-script/reference/document/text` elements, and all elements between them, to the `RangeBuilder`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `startTextElement` | `https://developers.google.com/apps-script/reference/document/text` | the first text element to be partially added |
| `startOffset` | `Integer` | the number of characters before the first character of `startTextElement` to be included (that is, the index of the first character in the range) |
| `endTextElementInclusive` | `https://developers.google.com/apps-script/reference/document/text` | the last text element to be partially added |
| `endOffsetInclusive` | `Integer` | the number of characters before the last character of `endTextElementInclusive` to be included (that is, the index of the last character in the range) |

#### Return


`https://developers.google.com/apps-script/reference/document/range-builder#` --- this builder, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `addRange(range)`

Adds the contents of another `Range` to this `RangeBuilder`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `range` | `https://developers.google.com/apps-script/reference/document/range` | the range whose elements should be added |

#### Return


`https://developers.google.com/apps-script/reference/document/range-builder#` --- this builder, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

*** ** * ** ***

### `build()`

Constructs a `Range` from the settings applied to the builder.

#### Return


`https://developers.google.com/apps-script/reference/document/range` --- the newly constructed range

*** ** * ** ***

### `getRangeElements()`

Gets all elements in this `Range`, including any partial `https://developers.google.com/apps-script/reference/document/text` elements (for example, in the case
of a selection that includes only part of a `Text` element). To determine whether a
`Text` element is only partially included in the range, see `https://developers.google.com/apps-script/reference/document/range-element#isPartial()`.

#### Return


`https://developers.google.com/apps-script/reference/document/range-element` --- an array of elements, in the order they appear in the document

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`

## Deprecated methods

### `getSelectedElements()`


**Deprecated.** Renamed to `https://developers.google.com/apps-script/reference/document/range-builder#getRangeElements()`.

Gets all elements that the user has selected in the open instance of the document, including
any partially selected `https://developers.google.com/apps-script/reference/document/text`
elements.

#### Return


`https://developers.google.com/apps-script/reference/document/range-element` --- an array of selected or partially selected elements, in the order they appear in the
document

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/documents.currentonly`
- `https://www.googleapis.com/auth/documents`