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

import A1 from '@flighter/a1-notation';
// or
const A1 = require('@flighter/a1-notation');

Methods

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

static isValid

// static isValid(a1: string): boolean

/**
 * Checks A1 notation.
 */

// Example
A1.isValid('A1');   // true
A1.isValid('A1:B2');// true
A1.isValid('aaaaa');// false

static getCol

// static getCol(a1: string, converter: 1 | 2 = 1): number

/**
 * Converts the first column letter from A1 to number.
 */

// Example
A1.getCol('A1');   // 1
A1.getCol('A1:B2');// 1
A1.getCol('aaaaa');// Error

static getLastCol

// static getLastCol(a1: string, converter: 1 | 2 = 1): number

/**
 * Converts the last column letter from A1 to number.
 */

// Example
A1.getLastCol('A1');   // 1
A1.getLastCol('A1:B2');// 2
A1.getLastCol('aaaaa');// Error

static toCol

// static toCol(col: number): string

/**
 * Converts number to column letter in A1.
 */

// Example
A1.toCol(1);   // 'A'
A1.toCol('A1');// Error

static getRow

// static getRow(a1: string): number

/**
 * Converts the first row string to number.
 */

// Example
A1.getRow('A1');   // 1
A1.getRow('A1:B2');// 1
A1.getRow('aaaaa');// Error

static getLastRow

// static getLastRow(a1: string): number

/**
 * Converts the last row string to number.
 */

// Example
A1.getLastRow('A1');   // 1
A1.getLastRow('A1:B2');// 1
A1.getLastRow('aaaaa');// Error

static toRow

// static toRow(row: number): string

/**
 * Converts number to row string in A1.
 */

// Example
A1.toRow(1);   // '1'
A1.toRow('A1');// Error

static getWidth

// static getWidth(a1: string, converter: 1 | 2 = 1): number

/**
 * Returns columns count.
 */

// Example
A1.getWidth('A1');   // 1
A1.getWidth('A1:B2');// 2
A1.getWidth('aaaaa');// Error

static getHeight

// static getHeight(a1: string): number

/**
 * Returns rows count.
 */

// Example
A1.getHeight('A1');   // 1
A1.getHeight('A1:B2');// 2
A1.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):
new A1('A1');       // A1:A1
new A1('A1:B2');    // A1:B2
new A1('A1', 'B2'); // A1:B2
new A1(1, 1);       // A1:A1
new A1(1, 1, 2);    // A1:A2
new A1(1, 1, 2, 2); // A1:B2
// A1:A1
new A1({
  a1Start:  'A1',
});
// A1:B2
new A1({
  a1Start:  'A1', a1End:   'B2',
});
// A1:A1
new A1({
  colStart: 'A', rowStart: '1',
});
// A1:A1
new A1({
  colStart:  1,  rowStart:  1,
});
// A1:A2
new A1({
  colStart:  1,  rowStart:  1,  nRows:   2,
});
// A1:B1
new A1({
  colStart:  1,  rowStart:  1,  nCols:   2,
});
// A1:B2
new A1({
  colStart:  1,  rowStart:  1,  nRows:   2,  nCols:   2,
});
// A1:B1
new A1({
  colStart: 'A', rowStart: '1', colEnd: 'B',
});
// A1:B1
new A1({
  colStart:  1,  rowStart:  1,  colEnd:  2,
});
// A1:A2
new A1({
  colStart: 'A', rowStart: '1', rowEnd: '2',
});
// A1:A2
new A1({
  colStart:  1,  rowStart:  1,  rowEnd:  2,
});
// A1:B2
new A1({
  colStart: 'A', rowStart: '1', colEnd: 'B', rowEnd: '2',
});
// A1:B2
new A1({
  colStart:  1,  rowStart:  1,  colEnd:  2,  rowEnd:  2,
});

get

// get(): string

/**
 * Returns string in A1 notation.
 */

// Example
new A1('A1').get();   // 'A1'
new A1('A1:B2').get();// 'A1:B2'

toString

// toString(): string

/**
 * Returns string in A1 notation.
 */

// Example
new A1('A1').toString();   // 'A1'
new A1('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.
 */

// Example
new A1('A1').toJSON();
/**
 * {
 *  colStart:  1,
 *  rowStart:  1,
 *  colEnd:    1,
 *  rowEnd:    1,
 *  a1:        'A1',
 *  rowsCount: 1,
 *  colsCount: 1,
 * }
 */
new A1('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.
 */

// Example
new A1('A1').getCol();   // 1
new A1('A1:B2').getCol();// 1

getLastCol

// getLastCol(): number

/**
 * Returns the last column.
 */

// Example
new A1('A1').getLastCol();   // 1
new A1('A1:B2').getLastCol();// 2

getRow

// getRow(): number

/**
 * Returns the first row.
 */

// Example
new A1('A1').getRow();   // 1
new A1('A1:B2').getRow();// 1

getLastRow

// getLastRow(): number

/**
 * Returns the last row.
 */

// Example
new A1('A1').getLastRow();   // 1
new A1('A1:B2').getLastRow();// 2

getWidth

// getWidth(): number

/**
 * Returns columns count.
 */

// Example
new A1('A1').getWidth();   // 1
new A1('A1:B2').getWidth();// 2

getHeight

// getHeight(): number

/**
 * Returns rows count.
 */

// Example
new A1('A1').getHeight();   // 1
new A1('A1:B2').getHeight();// 2

copy

// copy(): A1

/**
 * Returns a copy of this object.
 */

// Example
new A1('A1').copy();   // instance of A1
new A1('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 |
               +---+---+---+
 */

// Example
new A1('A1').addX(1);    // A1:B1
new A1('A1:B2').addX(-1);// A1:B2
new A1('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
                     ˅
 */

// Example
new A1('A1').addY(1);    // A1:A2
new A1('A1:B2').addY(-1);// A1:B2
new A1('A3:B4').addY(-1);// A2:B4

add

// add(countX: number, countY: number): this

/**
 * Adds N cells to range along the x/y-axis.
 */

// Example
new A1('A1').add(1, 1);     // A1:B2
new A1('A1:B2').add(-1, -1);// A1:B2
new A1('A3:B4').add(-1, -1);// A2:B4
new A1('C3:E5').add(-1, -1);// B2:E5
new A1('C3:E5').add(-1, 1); // B3:E6
new A1('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 |
               +---+---+---+
 */

// Example
new A1('A1').removeX(1);    // A1:A1
new A1('A1:B2').removeX(-1);// B1:B2
new A1('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
                     |
 */

// Example
new A1('A1').removeY(1);    // A1:A1
new A1('A1:B2').removeY(-1);// A2:B2
new A1('B3:C4').removeY(-1);// B4:C4

remove

// remove(countX: number, countY: number): this

/**
 * Removes N cells from range along the x/y-axis.
 */

// Example
new A1('A1').remove(1, 1);     // A1:A1
new A1('A1:B2').remove(-1, -1);// B2:B2
new A1('A3:B4').remove(-1, -1);// B4:B4
new A1('C3:E5').remove(-1, -1);// D4:E5
new A1('C3:E5').remove(-1, 1); // D3:E4
new A1('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 | ------------>
               +---+---+---+
 */

// Example
new A1('A1').shiftX(1);    // B1:B1
new A1('A1:B2').shiftX(-1);// A1:B2
new A1('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  |       |
                 ˅       ˅
 */

// Example
new A1('A1').shiftY(1);    // A2:A2
new A1('A1:B2').shiftY(-1);// A1:B2
new A1('B3:C4').shiftY(-1);// B2:C3

shift

// shift(offsetX: number, offsetY: number): this

/**
 * Shifts the range along the x/y-axis.
 */

// Example
new A1('A1').shift(1, 1);     // B2:B2
new A1('A1:B2').shift(-1, -1);// A1:B2
new A1('A3:B4').shift(-1, -1);// A2:B3
new A1('C3:E5').shift(-1, -1);// B2:D4
new A1('C3:E5').shift(-1, 1); // B4:D6
new A1('C3:E5').shift(1, -1); // D2:F4