Documentation

Coordinate
in package

AbstractYes

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

Constants

A1_COORDINATE_REGEX  = '/^(?<col>\$?[A-Z]{1,3})(?<row>\$?\d{1,7})$/i'
DEFAULT_RANGE  = 'A1:A1'
Default range variable constant.
FULL_REFERENCE_REGEX  = '/^(?:(?<worksheet>[^!]*)!)?(?<localReference>(?<firstCoordinate>[$]?[A-Z]{1,3}[$]?\d{1,7})(?:\:(?<secondCoordinate>[$]?[A-Z]{1,3}[$]?\d{1,7}))?)$/i'

Methods

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()  : array{0: string, 1: string}
Convert string coordinate to [0 => int column index, 1 => int row index].
coordinateIsInsideRange()  : bool
Check if coordinate is inside a range.
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{0: int, 1: int, 2: string}
Convert string coordinate to [0 => int column index, 1 => int row index, 2 => string column string].
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.
resolveUnionAndIntersection()  : string
Get all cell references applying union and intersection.
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.
validateReferenceAndGetData()  : array<string|int, mixed>
Check if cell or range reference is valid and return an array with type of reference (cell or range), worksheet (if it was given) and the coordinate or the first coordinate and second coordinate if it is a range.

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'

FULL_REFERENCE_REGEX

public mixed FULL_REFERENCE_REGEX = '/^(?:(?<worksheet>[^!]*)!)?(?<localReference>(?<firstCoordinate>[$]?[A-Z]{1,3}[$]?\d{1,7})(?:\:(?<secondCoordinate>[$]?[A-Z]{1,3}[$]?\d{1,7}))?)$/i'

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(int|string $cellAddress) : string
Parameters
$cellAddress : int|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|null $columnAddress) : int
Parameters
$columnAddress : string|null

eg 'A'

Return values
int —

Column index (A = 1)

coordinateFromString()

Convert string coordinate to [0 => int column index, 1 => int row index].

public static coordinateFromString(string $cellAddress) : array{0: string, 1: string}
Parameters
$cellAddress : string

eg: 'A1'

Return values
array{0: string, 1: string} —

Array containing column and row (indexes 0 and 1)

coordinateIsInsideRange()

Check if coordinate is inside a range.

public static coordinateIsInsideRange(string $range, string $coordinate) : bool
Parameters
$range : string

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

$coordinate : string

Cell coordinate (e.g. A1)

Return values
bool —

true if coordinate is inside range

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()

Convert string coordinate to [0 => int column index, 1 => int row index, 2 => string column string].

public static indexesFromString(string $coordinates) : array{0: int, 1: int, 2: string}
Parameters
$coordinates : string

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

Return values
array{0: int, 1: int, 2: string} —

Array containing column and row index, and column string

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)

resolveUnionAndIntersection()

Get all cell references applying union and intersection.

public static resolveUnionAndIntersection(string $cellBlock[, string $implodeCharacter = ',' ]) : string
Parameters
$cellBlock : string

A cell range e.g. A1:B5,D1:E5 B2:C4

$implodeCharacter : string = ','
Return values
string —

A string without intersection operator. If there was no intersection to begin with, return original argument. Otherwise, return cells and/or cell ranges in that range separated by comma.

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|numeric-string $columnIndex) : string
Parameters
$columnIndex : int|numeric-string

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

validateReferenceAndGetData()

Check if cell or range reference is valid and return an array with type of reference (cell or range), worksheet (if it was given) and the coordinate or the first coordinate and second coordinate if it is a range.

private static validateReferenceAndGetData(string $reference) : array<string|int, mixed>
Parameters
$reference : string

Coordinate or Range (e.g. A1:A1, B2, B:C, 2:3)

Return values
array<string|int, mixed> —

reference data


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results