Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

string-match-left-right

codsen115.4kMIT9.0.22TypeScript support: included

Match substrings on the left or right of a given index, ignoring whitespace

left, march, match, no-parsing, right, string, traverse, utility

readme

string-match-left-right

Match substrings on the left or right of a given index, ignoring whitespace

page on codsen.com page on npm page on github Downloads per month changelog MIT Licence

Install

This package is pure ESM. If you're not ready yet, install an older version of this program, 7.1.0 (npm i string-match-left-right@7.1.0).

npm i string-match-left-right

Quick Take

import { strict as assert } from "assert";

import {
  matchLeftIncl,
  matchRightIncl,
  matchLeft,
  matchRight,
} from "string-match-left-right";

// 3rd character is "d" because indexes start from zero.
// We're checking the string to the left of it, "bcd", inclusive of current character ("d").
// This means, "bcd" has to end with existing character and the other chars to the left
// must match exactly:
assert.equal(matchLeftIncl("abcdefghi", 3, ["bcd"]), "bcd");

// neither "ab" nor "zz" are to the left of 3rd index, "d":
assert.equal(matchLeft("abcdefghi", 3, ["ab", "zz"]), false);

// "def" is to the right of 3rd index (including it), "d":
assert.equal(matchRightIncl("abcdefghi", 3, ["def", "zzz"]), "def");

// One of values, "ef" is exactly to the right of 3rd index, "d":
assert.equal(matchRight("abcdefghi", 3, ["ef", "zz"]), "ef");

Documentation

Please visit codsen.com for a full description of the API.

Contributing

To report bugs or request features or assistance, raise an issue on GitHub.

Licence

MIT License.

Copyright © 2010-2025 Roy Revelt and other contributors.

ok codsen star

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

9.0.19 (2024-03-30)

Bug Fixes

  • rebase with optional chain (f4ae8fb)

9.0.0 (2022-12-01)

BREAKING CHANGES

  • Minimum supported Node version is v14.18; we're dropping v12 support

8.2.0 (2022-08-12)

Features

8.1.0 (2022-04-10)

Features

  • export defaults and version (405add5)

8.0.0 (2021-09-09)

Features

BREAKING CHANGES

  • programs now are in ES Modules and won't work with Common JS require()

7.1.0 (2021-05-24)

Features

  • config file based major bump blacklisting (e15f9bb)

7.0.9 (2021-04-11)

Reverts

  • Revert "chore: setup refresh" (23cf206)

7.0.0 (2021-02-27)

Fixed

  • if the first char was matched, don't tolerate any mismatches leading up to it (c482851)

Features

  • algorithm improvements to avoid false positives in too early matches (552df88)
  • opts.hungry (68b1c0f)

BREAKING CHANGES

  • This flag, disabled by default, prevents from too-eager matching in the beginning, wasting maxMismatches. To get old behaviour like before this release, set opts.hungry to true.

6.0.1 (2021-01-28)

Fixed

  • add testStats to npmignore (f3c84e9)

6.0.0 (2021-01-23)

Features

BREAKING CHANGES

  • there should be no API changes, but we're bumping major just in case

5.0.0 (2020-11-28)

Accidental version bump during migration to SourceHut. Sorry about that.

4.0.1 (2020-03-24)

Fixed

  • fix opts.firstMustMatch (195350b)

4.0.0 (2020-03-16)

Fixed

  • opts.maxMismatches higher than one (c0a416a)
  • add insurance against the variable being not string (e53f435)
  • fix opts.matchRight (ba40509)
  • fix maxMismatches (be34351)
  • fix the excessive skipping (e97899d)
  • insurance against undefined value (a0d5193)

Features

  • opts.maxMismatches (5288fe9)
  • case when character is omitted from the source and maxMismatches allows that (1b47eba)
  • merge marchForward and marchBackward into one, simplify the API (e873ee6)
  • opts.lastMustMatch (12ad597)
  • opts.skipWhitespace (6d9c847)
  • rebase to make twice as fast (4530b9f)
  • remove opts.skipInnerWhitespace (541c1c5)

BREAKING CHANGES

  • no more opts.relaxedApi - it's relaxed as much as possible by default, no emoji-related code

CHANGES

  • Remove anything emoji-related to make things run faster. Emoji can be of varying length and previous algorithm worked only for 2 character-long emojis only anyway. And there can be emoji as long as 8 characters.
  • Remove opts.relaxedApi - now it's always relaxed. Idea is, this is an internal library, if parent programs want to check something, let them do so.

3.11.0 (2019-08-08)

Features

  • second callback's argument returns empty string when EOL is reached (previously - undefined) (b480821)

3.10.0 (2019-01-20)

  • Various documentation and setup tweaks after we migrated to monorepo
  • Setup refresh: updated dependencies and all config files using automated tools

3.6.0 (2018-12-26)

  • Add EOL matching and code refresh (ca834a7)
  • Add opts.relaxedApi (f30626c)

3.5.0 (2018-12-04)

  • NEW! Now you can match against EOL - end of string (beginning or ending). Since you can't pass letters "EOL", you must pass them as an ES6 arrow function, () => "EOL". In all other aspects, the use is the same.
  • 🔧 Previously, opts.cb second argument, which means the rest of the string on particular side, depending on the method called, left or right, was giving empty string when there was nothing on that side. This, however looked inconsistent when all other callback values were undefined. Now, second opts.cb argument comes as undefined instead of empty string when there's nothing to return.
  • Implemented and released (but not documented) opts.strictApi was merged with opts.relaxedApi
  • Restored unit test coverage and ava linting

3.4.0 (2018-06-11)

  • migrated to BitBucket (to host repo + perform CI) and Codacy (for code quality audit)
  • dropped BitHound (RIP) and Travis
  • removed package-lock

3.3.0 (2018-05-16)

  • Add opts.relaxedApi

3.2.0 (2018-05-15)

  • Set up Prettier
  • Removed package.lock and .editorconfig
  • Wired Rollup to remove comments from non-dev builds. This means we can now leave the console.logs in the source code — Rollup will remove them from production code.
  • Unit tests are pointing at ES modules build, which means that code coverage is correct now, without Babel functions being missed
  • Removed DEBUG statements from the code
  • Added esm config to package.json which somehow enables CJS compat in ava.

3.1.1 (2018-03-06)

  • 🔧 Looks like the new callback feature was causing throws on certain cases. Not any more. Sorry about that. Very big release in coming soon with great new features. 👍

3.1.0 (2018-03-01)

  • Add the third argument, whatToMatch, can now be empty string. In such case, you have to provide callback and result will be calculated purely using the callback. It's handy when you want to perform complex matching, beyond "character is equal to" level. Personally, I reached this level and it's necessary for the feature I'm producing on the other package. It must be handy for everybody else too.

3.0.0 (2018-01-15)

  • Rewrote a lot of code, relieving us from all lodash dependencies.
  • opts.trimCharsBeforeMatching must be a string of single character or an array of single characters. Previously merged string of characters was accepted but now it's not accepted.

  • Callback cb now returns three arguments:

    1. char - the character just outside of the matched substring (as previously)
    2. theRemainderOfTheString - whole string outside of the matched substring (as previously)
    3. index - NEW - the index of the char.

    Index is handy in cases when you set trimming and it's not clear where exactly is the char located in the string. Also, from here you can easily calculate the index of the match - just substract its length from index.

Fixed

  • 🔧 I think matchLeftIncl previously was returning theRemainderOfTheString together with the matched substring (on the right of it). That's against the spec because the spec says "everything outside of the matched substring is given". But not including it. Sorry for this error. I'll bump the major just in case the correct behaviour breaks somebody's code.

2.0.0 (2017-12-21)

Changes

  • Let's say you want to check, does a string contain "something" to the right or to the left of somewhere in it (a given index). We allow "something" to be an array of strings. If those strings are of a varying length, how do you find out, what exactly did match from the "something" array and especially, how long it is? As a solution for that, I'm going to return a positive result not Boolean true which is meaningless, but actually the value of a matched string from "something". It is equally truthy but you can now query it further, like find its length.

Instructions to upgrade from 1.x

If you relied on the result being explicitly Boolean, true or false, prepare that truthy outcome now will be string. Just us double negation !! and you'll convert it to true. Or better, you can just use the truthy (string) result in the Boolean logic. It's truthy anyway.

  • opts.cbLeft and opts.cbRight were joined into one, opts.cb. Same behaviour, except there's less to think about. Just pass the callback function - it will be called with the substring which is on the left or right, depending if you called left-side (matchLeftIncl/matchLeft) or right-side (matchRightIncl/matchRight) method.

1.4.0 (2017-12-10)

Features

  • Stringifying of opts.trimCharsBeforeMatching now occurs only if element is not string.
  • Callbacks, opts.cbLeft and opts.cbRight, get second argument - whole substring of what's on that side. First argument it received is first character, second is whole substring (including first character).

I needed this when I was coding email-remove-unused-css and I was traversing the string. I wanted to check, do any of given heads are equal to what's on the right of the current character being traversed. For example, if there are Nunjucks variables in HTML, they would start with {{ and end with }}. I wanted email-remove-unused-css to ignore everything between such heads and tails (which can be customised to anything, to support any templating/programming languages).

1.3.0 (2017-11-23)

  • Add opts.trimCharsBeforeMatching

1.2.0 (2017-11-22)

  • Add opts.trimBeforeMatching

1.1.0 (2017-10-28)

  • Add opts.cbLeft
  • Add opts.cbRight

Often you want to check not only what's to the left or right of the certain index in the string, but also perform certain checks on what's even further to the left/right. For example, you have a piace of HTML, class= and you are an index which is at character =. You can use string-match-left-right to check, is class on the left using matchLeft. Which is fine. There's a gotcha though. You also need to check, what's further to the left of class= - is it a character, a space or something else? Because it might be that you looked for class attribute but matched superclass, an (imaginary) custom attribute!

Here comes in the callback functions.

They have to be callbacks because I can't predict what checks you will want to check on the outer-left and outer-right characters. Just pass your function and this library will feed them (the outer-left and outer-right characters) as arguments. You can then find out yourself what to do about it.

1.0.0 (2017-10-28)

  • First public release