133 lines
4.1 KiB
Markdown
133 lines
4.1 KiB
Markdown
# line-column
|
|
|
|
[](https://travis-ci.org/io-monad/line-column) [](https://coveralls.io/github/io-monad/line-column?branch=master) [](https://badge.fury.io/js/line-column)
|
|
|
|
Node module to convert efficiently index to/from line-column in a string.
|
|
|
|
## Install
|
|
|
|
npm install line-column
|
|
|
|
## Usage
|
|
|
|
### lineColumn(str, options = {})
|
|
|
|
Returns a `LineColumnFinder` instance for given string `str`.
|
|
|
|
#### Options
|
|
|
|
| Key | Description | Default |
|
|
| ------- | ----------- | ------- |
|
|
| `origin` | The origin value of line number and column number | `1` |
|
|
|
|
### lineColumn(str, index)
|
|
|
|
This is just a shorthand for `lineColumn(str).fromIndex(index)`.
|
|
|
|
### LineColumnFinder#fromIndex(index)
|
|
|
|
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.
|
|
|
|
### LineColumnFinder#toIndex(line, column)
|
|
|
|
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.<br>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](https://www.npmjs.com/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/](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)
|