Documentation

Coordinate

Helper class to manipulate cell coordinates.

Columns indexes and rows are always based on 1, not on 0. This match the behavior that Excel users are used to, and also match the Excel functions COLUMN() and ROW().

Table of Contents

A1_COORDINATE_REGEX  = '/^(?<col>\$?[A-Z]{1,3})(?<row>\$?\d{1,7})$/i'
DEFAULT_RANGE  = 'A1:A1'
Default range variable constant.
absoluteCoordinate()  : string
Make string coordinate absolute.
absoluteReference()  : string
Make string row, column or cell coordinate absolute.
buildRange()  : string
Build range from coordinate strings.
columnIndexFromString()  : int
Column index from string.
coordinateFromString()  : mixed
Coordinate from string.
coordinateIsRange()  : bool
Checks if a Cell Address represents a range of cells.
extractAllCellReferencesInRange()  : array<string|int, mixed>
Extract all cell references in range, which may be comprised of multiple cell ranges.
getRangeBoundaries()  : array<string|int, mixed>
Calculate range boundaries.
indexesFromString()  : array<string|int, mixed>
Get indexes from a string coordinates.
mergeRangesInCollection()  : array<string|int, mixed>
Convert an associative array of single cell coordinates to values to an associative array of cell ranges to values. Only adjacent cell coordinates with the same value will be merged. If the value is an object, it must implement the method getHashCode().
rangeBoundaries()  : array<string|int, mixed>
Calculate range boundaries.
rangeDimension()  : array<string|int, mixed>
Calculate range dimension.
splitRange()  : array<string|int, mixed>
Split range into coordinate strings.
stringFromColumnIndex()  : string
String from column index.
getCellBlocksFromRangeString()  : array<string|int, array<string|int, mixed>>
Get the individual cell blocks from a range string, removing any $ characters.
getReferencesForCellBlock()  : array<string|int, mixed>
Get all cell references for an individual cell block.
processRangeSetOperators()  : array<string|int, mixed>
sortCellReferenceArray()  : array<string|int, mixed>
validateRange()  : void
Check that the given range is valid, i.e. that the start column and row are not greater than the end column and row.

Constants

A1_COORDINATE_REGEX

public mixed A1_COORDINATE_REGEX = '/^(?<col>\$?[A-Z]{1,3})(?<row>\$?\d{1,7})$/i'

DEFAULT_RANGE

Default range variable constant.

public string DEFAULT_RANGE = 'A1:A1'

Methods

absoluteCoordinate()

Make string coordinate absolute.

public static absoluteCoordinate(string $cellAddress) : string
Parameters
$cellAddress : string

e.g. 'A1'

Return values
string

Absolute coordinate e.g. '$A$1'

absoluteReference()

Make string row, column or cell coordinate absolute.

public static absoluteReference(string $cellAddress) : string
Parameters
$cellAddress : string

e.g. 'A' or '1' or 'A1' Note that this value can be a row or column reference as well as a cell reference

Return values
string

Absolute coordinate e.g. '$A' or '$1' or '$A$1'

buildRange()

Build range from coordinate strings.

public static buildRange(array<string|int, mixed> $range) : string
Parameters
$range : array<string|int, mixed>

Array containing one or more arrays containing one or two coordinate strings

Return values
string

String representation of $pRange

columnIndexFromString()

Column index from string.

public static columnIndexFromString(string $columnAddress) : int
Parameters
$columnAddress : string

eg 'A'

Return values
int

Column index (A = 1)

coordinateFromString()

Coordinate from string.

public static coordinateFromString(string $cellAddress) : mixed
Parameters
$cellAddress : string

eg: 'A1'

Return values
mixed

coordinateIsRange()

Checks if a Cell Address represents a range of cells.

public static coordinateIsRange(string $cellAddress) : bool
Parameters
$cellAddress : string

eg: 'A1' or 'A1:A2' or 'A1:A2,C1:C2'

Return values
bool

Whether the coordinate represents a range of cells

extractAllCellReferencesInRange()

Extract all cell references in range, which may be comprised of multiple cell ranges.

public static extractAllCellReferencesInRange(string $cellRange) : array<string|int, mixed>
Parameters
$cellRange : string

Range: e.g. 'A1' or 'A1:C10' or 'A1:E10,A20:E25' or 'A1:E5 C3:G7' or 'A1:C1,A3:C3 B1:C3'

Return values
array<string|int, mixed>

Array containing single cell references

getRangeBoundaries()

Calculate range boundaries.

public static getRangeBoundaries(string $range) : array<string|int, mixed>
Parameters
$range : string

Cell range, Single Cell, Row/Column Range (e.g. A1:A1, B2, B:C, 2:3)

Return values
array<string|int, mixed>

Range coordinates [Start Cell, End Cell] where Start Cell and End Cell are arrays [Column ID, Row Number]

indexesFromString()

Get indexes from a string coordinates.

public static indexesFromString(string $coordinates) : array<string|int, mixed>
Parameters
$coordinates : string

eg: 'A1', '$B$12'

Return values
array<string|int, mixed>

mergeRangesInCollection()

Convert an associative array of single cell coordinates to values to an associative array of cell ranges to values. Only adjacent cell coordinates with the same value will be merged. If the value is an object, it must implement the method getHashCode().

public static mergeRangesInCollection(array<string|int, mixed> $coordinateCollection) : array<string|int, mixed>

For example, this function converts:

[ 'A1' => 'x', 'A2' => 'x', 'A3' => 'x', 'A4' => 'y' ]

to:

[ 'A1:A3' => 'x', 'A4' => 'y' ]

Parameters
$coordinateCollection : array<string|int, mixed>

associative array mapping coordinates to values

Return values
array<string|int, mixed>

associative array mapping coordinate ranges to valuea

rangeBoundaries()

Calculate range boundaries.

public static rangeBoundaries(string $range) : array<string|int, mixed>
Parameters
$range : string

Cell range, Single Cell, Row/Column Range (e.g. A1:A1, B2, B:C, 2:3)

Return values
array<string|int, mixed>

Range coordinates [Start Cell, End Cell] where Start Cell and End Cell are arrays (Column Number, Row Number)

rangeDimension()

Calculate range dimension.

public static rangeDimension(string $range) : array<string|int, mixed>
Parameters
$range : string

Cell range, Single Cell, Row/Column Range (e.g. A1:A1, B2, B:C, 2:3)

Return values
array<string|int, mixed>

Range dimension (width, height)

splitRange()

Split range into coordinate strings.

public static splitRange(string $range) : array<string|int, mixed>
Parameters
$range : string

e.g. 'B4:D9' or 'B4:D9,H2:O11' or 'B4'

Return values
array<string|int, mixed>

Array containing one or more arrays containing one or two coordinate strings e.g. ['B4','D9'] or [['B4','D9'], ['H2','O11']] or ['B4']

stringFromColumnIndex()

String from column index.

public static stringFromColumnIndex(int $columnIndex) : string
Parameters
$columnIndex : int

Column index (A = 1)

Return values
string

getCellBlocksFromRangeString()

Get the individual cell blocks from a range string, removing any $ characters.

private static getCellBlocksFromRangeString(string $rangeString) : array<string|int, array<string|int, mixed>>

then splitting by operators and returning an array with ranges and operators.

Parameters
$rangeString : string
Return values
array<string|int, array<string|int, mixed>>

getReferencesForCellBlock()

Get all cell references for an individual cell block.

private static getReferencesForCellBlock(string $cellBlock) : array<string|int, mixed>
Parameters
$cellBlock : string

A cell range e.g. A4:B5

Return values
array<string|int, mixed>

All individual cells in that range

processRangeSetOperators()

private static processRangeSetOperators(array<string|int, mixed> $operators, array<string|int, mixed> $cells) : array<string|int, mixed>
Parameters
$operators : array<string|int, mixed>
$cells : array<string|int, mixed>
Return values
array<string|int, mixed>

sortCellReferenceArray()

private static sortCellReferenceArray(array<string|int, mixed> $cellList) : array<string|int, mixed>
Parameters
$cellList : array<string|int, mixed>
Return values
array<string|int, mixed>

validateRange()

Check that the given range is valid, i.e. that the start column and row are not greater than the end column and row.

private static validateRange(string $cellBlock, int $startColumnIndex, int $endColumnIndex, int $currentRow, int $endRow) : void
Parameters
$cellBlock : string

The original range, for displaying a meaningful error message

$startColumnIndex : int
$endColumnIndex : int
$currentRow : int
$endRow : int
Return values
void

Search results