line-column

  

Node module to convert efficiently index to/from line-column in a string.

Install

npm install line-column

Usage

$3

Returns a LineColumnFinder instance for given string str.

#### Options

| Key | Description | Default |
| ------- | ----------- | ------- |
| origin | The origin value of line number and column number | 1 |

$3

This is just a shorthand for lineColumn(str).fromIndex(index).

$3

Find line and column from index in the string.

Parameters:

- index - number Index in the string. (0-origin)

Returns:

- { line: x, col: y } Found line number and column number.
- null if the given index is out of range.

$3

Find index from line and column in the string.

Parameters:

- line - number Line number in the string.
- column - number Column number in the string.

or

- { line: x, col: y } - Object line and column numbers in the string.
A key name column can be used instead of col.

or

- [ line, col ] - Array line and column numbers in the string.

Returns:

- number Found index in the string.
- -1 if the given line or column is out of range.

Example

``js
var lineColumn = require("line-column");

var testString = [
"ABCDEFG\n", // line:0, index:0
"HIJKLMNOPQRSTU\n", // line:1, index:8
"VWXYZ\n", // line:2, index:23
"日本語の文字\n", // line:3, index:29
"English words" // line:4, index:36
].join(""); // length:49

lineColumn(testString).fromIndex(3) // { line: 1, col: 4 }
lineColumn(testString).fromIndex(33) // { line: 4, col: 5 }
lineColumn(testString).toIndex(1, 4) // 3
lineColumn(testString).toIndex(4, 5) // 33

// Shorthand of .fromIndex (compatible with find-line-column)
lineColumn(testString, 33) // { line:4, col: 5 }

// Object or Array is also acceptable
lineColumn(testString).toIndex({ line: 4, col: 5 }) // 33
lineColumn(testString).toIndex({ line: 4, column: 5 }) // 33
lineColumn(testString).toIndex([4, 5]) // 33

// You can cache it for the same string. It is so efficient. (See benchmark)
var finder = lineColumn(testString);

finder.fromIndex(33) // { line: 4, column: 5 }
finder.toIndex(4, 5) // 33

// For 0-origin line and column numbers
var oneOrigin = lineColumn(testString, { origin: 0 });

oneOrigin.fromIndex(33) // { line: 3, column: 4 }
oneOrigin.toIndex(3, 4) // 33
`

Testing

npm test

Benchmark

The popular package find-line-column provides the same "index to line-column" feature.

Here is some benchmarking on line-column vs find-line-column. You can run this benchmark by npm run benchmark. See benchmark/ for the source code.

`
long text + line-column (not cached) x 72,989 ops/sec ±0.83% (89 runs sampled)
long text + line-column (cached) x 13,074,242 ops/sec ±0.32% (89 runs sampled)
long text + find-line-column x 33,887 ops/sec ±0.54% (84 runs sampled)
short text + line-column (not cached) x 1,636,766 ops/sec ±0.77% (82 runs sampled)
short text + line-column (cached) x 21,699,686 ops/sec ±1.04% (82 runs sampled)
short text + find-line-column x 382,145 ops/sec ±1.04% (85 runs sampled)
`

As you might have noticed, even not cached version of line-column is 2x - 4x faster than find-line-column, and cached version of line-column is remarkable 50x - 380x faster.

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature`
5. Submit a pull request :D

License

MIT (See LICENSE)