A1 notation

About

This library is for working with A1 notations such as "A1" or "A1:B2". The library exported as a UMD module.

Install

npm i @flighter/a1-notation -d

Or

yarn add @flighter/a1-notation

Download

With object: ES5(76 KB), ES5.min(26 KB), ESNext(21 KB), ESNext.min(6 KB), UMD(21 KB)

Without object: ES5(68 KB), ES5.min(23 KB), ESNext(16 KB), ESNext.min(4 KB), UMD(16 KB)

What is the difference?

• "with object" or "without object"? A1 constructor can take an object as an argument - it's a version "with object". So, "without object" is when a constructor can't take an object as an argument.
• converter 1 or converter 2? The difference is in the algorithm of convertation. You can compare the first method with the second method.
• "ES5" or "ESNext"? ES5 has already converted to ES5 standard with all needed polyfills. ESNext uses the original syntax of the code.
• "UMD"? UMD - Unified Module Definition, more in Google.
• ".min"? Minified version.
• Default version in npm is UMD ESNext "with object". This version is not transpiled and minified, so you need to transpile and minify it.

Initialization

importA1from'@flighter/a1-notation';// orconstA1=require('@flighter/a1-notation');

Methods

Note: A1 string could be represented in any register. A1 === a1, A1:B2 === a1:b2 === A1:b2 === a1:B2

staticisValid

// static isValid(a1: string): boolean/** * Checks A1 notation. */// ExampleA1.isValid('A1');// trueA1.isValid('A1:B2');// trueA1.isValid('aaaaa');// false

staticgetCol

// static getCol(a1: string, converter: 1 | 2 = 1): number/** * Converts the first column letter from A1 to number. */// ExampleA1.getCol('A1');// 1A1.getCol('A1:B2');// 1A1.getCol('aaaaa');// Error

staticgetLastCol

// static getLastCol(a1: string, converter: 1 | 2 = 1): number/** * Converts the last column letter from A1 to number. */// ExampleA1.getLastCol('A1');// 1A1.getLastCol('A1:B2');// 2A1.getLastCol('aaaaa');// Error

statictoCol

// static toCol(col: number): string/** * Converts number to column letter in A1. */// ExampleA1.toCol(1);// 'A'A1.toCol('A1');// Error

staticgetRow

// static getRow(a1: string): number/** * Converts the first row string to number. */// ExampleA1.getRow('A1');// 1A1.getRow('A1:B2');// 1A1.getRow('aaaaa');// Error

staticgetLastRow

// static getLastRow(a1: string): number/** * Converts the last row string to number. */// ExampleA1.getLastRow('A1');// 1A1.getLastRow('A1:B2');// 1A1.getLastRow('aaaaa');// Error

statictoRow

// static toRow(row: number): string/** * Converts number to row string in A1. */// ExampleA1.toRow(1);// '1'A1.toRow('A1');// Error

staticgetWidth

// static getWidth(a1: string, converter: 1 | 2 = 1): number/** * Returns columns count. */// ExampleA1.getWidth('A1');// 1A1.getWidth('A1:B2');// 2A1.getWidth('aaaaa');// Error

staticgetHeight

// static getHeight(a1: string): number/** * Returns rows count. */// ExampleA1.getHeight('A1');// 1A1.getHeight('A1:B2');// 2A1.getHeight('aaaaa');// Error

constructor

// constructor(object: options) - in version "with object"// constructor(range: string)// constructor(rangeStart: string, rangeEnd: string)// constructor(col: number, row: number)// constructor(col: number, row: number, nRows: number)// constructor(col: number, row: number, nRows: number, nCols: number)/** * options: * { * colStart?: string | number, * rowStart?: string | number, * colEnd?: string | number, * rowEnd?: string | number, * a1Start?: string, * a1End?: string, * nCols?: number,// how many cols in total (cols length) * nRows?: number,// how many rows in total (rows length) * converter?: 1 | 2, * } */// Example (supported now):newA1('A1');// A1:A1newA1('A1:B2');// A1:B2newA1('A1','B2');// A1:B2newA1(1,1);// A1:A1newA1(1,1,2);// A1:A2newA1(1,1,2,2);// A1:B2// A1:A1newA1({a1Start: 'A1',});// A1:B2newA1({a1Start: 'A1',a1End: 'B2',});// A1:A1newA1({colStart: 'A',rowStart: '1',});// A1:A1newA1({colStart: 1,rowStart: 1,});// A1:A2newA1({colStart: 1,rowStart: 1,nRows: 2,});// A1:B1newA1({colStart: 1,rowStart: 1,nCols: 2,});// A1:B2newA1({colStart: 1,rowStart: 1,nRows: 2,nCols: 2,});// A1:B1newA1({colStart: 'A',rowStart: '1',colEnd: 'B',});// A1:B1newA1({colStart: 1,rowStart: 1,colEnd: 2,});// A1:A2newA1({colStart: 'A',rowStart: '1',rowEnd: '2',});// A1:A2newA1({colStart: 1,rowStart: 1,rowEnd: 2,});// A1:B2newA1({colStart: 'A',rowStart: '1',colEnd: 'B',rowEnd: '2',});// A1:B2newA1({colStart: 1,rowStart: 1,colEnd: 2,rowEnd: 2,});

get

// get(): string/** * Returns string in A1 notation. */// ExamplenewA1('A1').get();// 'A1'newA1('A1:B2').get();// 'A1:B2'

toString

// toString(): string/** * Returns string in A1 notation. */// ExamplenewA1('A1').toString();// 'A1'newA1('A1:B2').toString();// 'A1:B2'

toJSON

// toJSON(): result/** * result: * { * colStart: number, * rowStart: number, * colEnd: number, * rowEnd: number, * a1: string, * rowsCount: number, * colsCount: number, * } *//** * Returns a full information about range. */// ExamplenewA1('A1').toJSON();/** * { * colStart: 1, * rowStart: 1, * colEnd: 1, * rowEnd: 1, * a1: 'A1', * rowsCount: 1, * colsCount: 1, * } */newA1('A1:B2').toJSON();/** * { * colStart: 1, * rowStart: 1, * colEnd: 2, * rowEnd: 2, * a1: 'A1:B2', * rowsCount: 2, * colsCount: 2, * } */

getCol

// getCol(): number/** * Returns the first column. */// ExamplenewA1('A1').getCol();// 1newA1('A1:B2').getCol();// 1

getLastCol

// getLastCol(): number/** * Returns the last column. */// ExamplenewA1('A1').getLastCol();// 1newA1('A1:B2').getLastCol();// 2

getRow

// getRow(): number/** * Returns the first row. */// ExamplenewA1('A1').getRow();// 1newA1('A1:B2').getRow();// 1

getLastRow

// getLastRow(): number/** * Returns the last row. */// ExamplenewA1('A1').getLastRow();// 1newA1('A1:B2').getLastRow();// 2

getWidth

// getWidth(): number/** * Returns columns count. */// ExamplenewA1('A1').getWidth();// 1newA1('A1:B2').getWidth();// 2

getHeight

// getHeight(): number/** * Returns rows count. */// ExamplenewA1('A1').getHeight();// 1newA1('A1:B2').getHeight();// 2

copy

// copy(): A1/** * Returns a copy of this object. */// ExamplenewA1('A1').copy();// instance of A1newA1('A1:B2').copy();// instance of A1

addX

// addX(count: number): this/** * Adds N cells to range along the x-axis. * if count >= 0 - adds to right. * if count < 0 - adds to left. *//* +---+---+---+ | 1 | 2 | 3 | count < 0 +---+---+---+ count >= 0<------------- | 4 | 5 | 6 | -------------> +---+---+---+ | 7 | 8 | 9 | +---+---+---+ */// ExamplenewA1('A1').addX(1);// A1:B1newA1('A1:B2').addX(-1);// A1:B2newA1('C1:E1').addX(-1);// B1:E1

addY

// addY(count: number): this/** * Adds N cells to range along the y-axis. * if count >= 0 - adds to bottom. * if count < 0 - adds to top. *//* ^ | count < 0 | +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+ | 7 | 8 | 9 | +---+---+---+ | | count >= 0 ˅ */// ExamplenewA1('A1').addY(1);// A1:A2newA1('A1:B2').addY(-1);// A1:B2newA1('A3:B4').addY(-1);// A2:B4

add

// add(countX: number, countY: number): this/** * Adds N cells to range along the x/y-axis. */// ExamplenewA1('A1').add(1,1);// A1:B2newA1('A1:B2').add(-1,-1);// A1:B2newA1('A3:B4').add(-1,-1);// A2:B4newA1('C3:E5').add(-1,-1);// B2:E5newA1('C3:E5').add(-1,1);// B3:E6newA1('C3:E5').add(1,-1);// C2:F5

removeX

// removeX(count: number): this/** * Removes N cells from range along the x-axis. * if count >= 0 - removes from right. * if count < 0 - removes from left. *//* +---+---+---+ | 1 | 2 | 3 | count < 0 +---+---+---+ count >= 0-------------> | 4 | 5 | 6 | <------------- +---+---+---+ | 7 | 8 | 9 | +---+---+---+ */// ExamplenewA1('A1').removeX(1);// A1:A1newA1('A1:B2').removeX(-1);// B1:B2newA1('B3:C4').removeX(-1);// C3:C4

removeY

// removeY(count: number): this/** * Removes N cells from range along the y-axis. * if count >= 0 - removes from bottom. * if count < 0 - removes from top. *//* | | count < 0 ˅ +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+ | 7 | 8 | 9 | +---+---+---+ ^ | count >= 0 | */// ExamplenewA1('A1').removeY(1);// A1:A1newA1('A1:B2').removeY(-1);// A2:B2newA1('B3:C4').removeY(-1);// B4:C4

remove

// remove(countX: number, countY: number): this/** * Removes N cells from range along the x/y-axis. */// ExamplenewA1('A1').remove(1,1);// A1:A1newA1('A1:B2').remove(-1,-1);// B2:B2newA1('A3:B4').remove(-1,-1);// B4:B4newA1('C3:E5').remove(-1,-1);// D4:E5newA1('C3:E5').remove(-1,1);// D3:E4newA1('C3:E5').remove(1,-1);// C4:D5

shiftX

// shiftX(offset: number): this/** * Shifts the range along the x-axis. * If offset >= 0 - shifts to right. * If offset < 0 - shifts to left. *//* +---+---+---+ <------------ | 1 | 2 | 3 | ------------> +---+---+---+ offset < 0 | 4 | 5 | 6 | offset >= 0 +---+---+---+ <------------ | 7 | 8 | 9 | ------------> +---+---+---+ */// ExamplenewA1('A1').shiftX(1);// B1:B1newA1('A1:B2').shiftX(-1);// A1:B2newA1('B3:C4').shiftX(-1);// A3:B4

shiftY

// shiftY(offset: number): this/** * Shifts the range along the y-axis. * If offset >= 0 - shifts to bottom. * If offset < 0 - shifts to top. *//* ^ ^ offset < 0 | | | | +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+ | 7 | 8 | 9 | +---+---+---+ | | offset >= 0 | | ˅ ˅ */// ExamplenewA1('A1').shiftY(1);// A2:A2newA1('A1:B2').shiftY(-1);// A1:B2newA1('B3:C4').shiftY(-1);// B2:C3

shift

// shift(offsetX: number, offsetY: number): this/** * Shifts the range along the x/y-axis. */// ExamplenewA1('A1').shift(1,1);// B2:B2newA1('A1:B2').shift(-1,-1);// A1:B2newA1('A3:B4').shift(-1,-1);// A2:B3newA1('C3:E5').shift(-1,-1);// B2:D4newA1('C3:E5').shift(-1,1);// B4:D6newA1('C3:E5').shift(1,-1);// D2:F4