Wondering what’s next for npm?Check out our public roadmap! »

    line-column
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/line-column package

    1.0.2 • Public • Published

    line-column

    Build Status Coverage Status npm version

    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.
      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

    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)

    Install

    npm i line-column

    DownloadsWeekly Downloads

    1,091,701

    Version

    1.0.2

    License

    MIT

    Last publish

    Collaborators

    • avatar