Combiner.CombineTextByRanges
CombinerReturns a combiner function that places text values into fixed-width ranges within an output string.
Syntax
Combiner.CombineTextByRanges(ranges as list, optional template as nullable text) as functionParameters
| Name | Type | Required | Description |
|---|---|---|---|
ranges | list | Yes | A list of two-element lists {offset, length} specifying where and how wide each field is in the output. |
template | text | No | An optional template text used as the base output string. Defaults to a string of spaces. |
Return Value
function — A function that accepts a list of text values and fits each into the corresponding {offset, length} range in the output.
Remarks
Combiner.CombineTextByRanges is the inverse of Splitter.SplitTextByRanges. It returns a combiner function that, when called with a list of text values, places each value into the corresponding {offset, length} range in the output string.
Each {offset, length} pair specifies the starting character position and the width of the field. If a value is shorter than the field width, it is right-padded with spaces. If a value is longer than the field width, it is truncated to fit.
The optional template parameter provides the base string; any positions not covered by a range retain the template characters. If no template is provided, the output is filled with spaces.
This function is the structured counterpart of Combiner.CombineTextByPositions — use it when you need both positional and width control over each field.
Examples
Example 1: Place two values into fixed-width fields
Combiner.CombineTextByRanges({{0, 5}, {5, 5}})({"Hello", "World"})Result | |
|---|---|
| 1 | HelloWorld |
Example 2: Values padded to field width
Combiner.CombineTextByRanges({{0, 10}, {10, 10}})({"Alice", "Bob"})Result | |
|---|---|
| 1 | Alice Bob |
Example 3: Values truncated when too long for the field
Combiner.CombineTextByRanges({{0, 3}, {3, 3}})({"Hello", "World"})Result | |
|---|---|
| 1 | HelWor |
Example 4: Use with Table.CombineColumns to produce fixed-width output
Table.CombineColumns(
#table({"Code", "Name"}, {{"US", "United States"}}),
{"Code", "Name"},
Combiner.CombineTextByRanges({{0, 2}, {2, 15}}),
"Record"
)Record | |
|---|---|
| 1 | USUnited States |