tdp-string-trim-functions

#TDPStringTrimFunctions

##Overview TDPStringTrimFunctions is a (very) small set of Javascript functions which extend the native String object to provide some enhanced trim capabilities. The functions are packaged into an AMD module which makes it easy to use with module/component managers such as RequireJS.

All three currently available functions are able to trim one or more strings of your choosing (not just whitespace like the standard String.trim()) from the left, the right or left and the right of a subject string.

These functions are nothing you couldn't do with a regexp but they're convenient to use and pretty readable so might be usable to others, hence them appearing here!

##Dependencies There are no code dependencies, you just need an AMD-capable module loader (see below). If you really want, you could chop out the functions from the AMD module define() and include them some other way.

The included tests use mocha, these tests are run automatically (in the NodeJS version) on Travis CI.

##Version Master branch (production): 0.3.2

##License TDPStringTrimFunctions is issued under a Creative Commons attribution share-alike license.
This means you can share and adapt the code provided you attribute the original author(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.

##Usage Because this module extends the native Javascript String object, once you include it, you can use these functions on any string. All functions in the library are chainable.

###Javascript Any module loader which supports AMD modules can be used, for example RequireJS, curl.js and the Dojo loader.

RequireJS example:

require(["TDPStringTrimFunctions.min"], function()
{
	var trimmedString="///Path/to/something/".trimChars("/");
	// Output: "Path/to/something"
}

###NodeJS A simple way to use AMD modules in NodeJS is amd-loader:

On your command line (assuming you have npm installed)

# npm install amd-loader tdp-string-trim-functions  

In your NodeJS script:

var amdloader=require("amd-loader");
var stringTrimFunctions=require("tdp-string-trim-functions");

var trimmedString="///Path/to/something/".trimChars("/");
// Output: "Path/to/something"

##A note on replacement processing and application order When multiple replacements are specified (i.e. charsToTrim is a multi-element array), replacements are made in the order they are specified in the array - 0th to Nth (left to right). Each replacement is applied only once i.e.

"abcabc123".leftTrimChars(["a","b","c"])

will result in output "abc123" rather than just "123" even if replaceMultipleOccurrences==true, this is because each replace is done in turn on the subject string, there is no recursion.

leftTrimChars() will replace characters from left to right in the subject string whereas rightTrimChars() will replace characters from right to left in the subject string. trimChars() will effectively first run a leftTrimChars() on all charsToTrim's supplied followed by a rightTrimChars() on all charsToTrim's supplied. This is mainly done for source code efficiency and may or may not be what is expected. You could chain up individual trims if this doesn't suit your need (or indeed you can fork this repo and change the code to suit your needs better).

##Functions provided ###leftTrimChars(charsToTrim, caseSensitive, replaceMultipleOccurrences) ####Overview Trims the specified characters from the left of the string and returns the resulting trimmed string. ####Parameters:

• charsToTrim: a String or array of strings to trim from the subject string. If an array is specified, each string in the array is trimmed in turn, going from left to right.
• caseSensitive: boolean (default: true) - true for case-sensitive operation, false for case-insensitive.
• replaceMultipleOccurrences: boolean (default: true) - true to replace multiple contiguous occurrences of the string(s), false to replace only the first.

####Returns This function returns the resulting, trimmed string.
Because the resulting string is returned, this function is fully chainable.

####Examples Note: module loading not shown

var subjectString="///Path/to/something/";

// Simple example with string charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences
subjectString.leftTrimChars("/");
// Output: "Path/to/something/"

// Simple example with array charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - same result as above
subjectString.leftTrimChars(["/"]);
// Output: "Path/to/something/"

// Example with array of 2 strings for charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - demonstrates default being case-sensitive (hence not replacing the "P" in "Path/...")
subjectString.leftTrimChars(["/", "p"]);
// Output: "Path/to/something/"

// Example with array of 2 strings for charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - demonstrates default being case-sensitive (hence replacing the "P" in "Path/...")
subjectString.leftTrimChars(["/", "P"]);
// Output: "ath/to/something/"

// Example with array of 2 strings for charsToTrim, false for caseSensitive &  default for replaceMultipleOccurrences (true)
subjectString.leftTrimChars(["/", "p"], false);
// Output: "ath/to/something/"

// Example with array of 2 strings for charsToTrim, true for caseSensitive & false for replaceMultipleOccurrences (hence only the first "/" being replaced)
subjectString.leftTrimChars("/", true, false);
// Output: "//Path/to/something/"

// #1 Demonstrating the significance of ordering of the array of strings in charsToTrim
subjectString.leftTrimChars(["/", "P", "a"]);
// Output: "th/to/something/"

// #2 Demonstrating the significance of ordering of the array of strings in charsToTrim
subjectString.leftTrimChars(["/", "a", "P"]);
// Output: "ath/to/something/"

// Demonstrating chaining
subjectString.trimChars("/").rightTrimChars("g");
// Output: "Path/to/somethin"

###rightTrimChars(charsToTrim, caseSensitive, replaceMultipleOccurrences) ####Overview Trims the specified characters from the right of the string and returns the resulting trimmed string. ####Parameters:

• charsToTrim: a String or array of strings to trim from the subject string. If an array is specified, each string in the array is trimmed in turn, going from left to right.
• caseSensitive: boolean (default: true) - true for case-sensitive operation, false for case-insensitive.
• replaceMultipleOccurrences: boolean (default: true) - true to replace multiple contiguous occurrences of the string(s), false to replace only the first.

####Returns This function returns the resulting, trimmed string.
Because the resulting string is returned, this function is fully chainable.

####Examples Note: module loading not shown

var subjectString="/Path/to/somethinG///";

// Simple example with string charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences
subjectString.rightTrimChars("/");
// Output: "/Path/to/somethinG"

// Simple example with array charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - same result as above
subjectString.rightTrimChars(["/"]);
// Output: "/Path/to/somethinG"

// Example with array of 2 strings for charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - demonstrates default being case-sensitive (hence not replacing the "P" in "Path/...")
subjectString.rightTrimChars(["/", "g"]);
// Output: "/Path/to/somethinG"

// Example with array of 2 strings for charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - demonstrates default being case-sensitive (hence replacing the "G" in ".../somethinG")
subjectString.rightTrimChars(["/", "G"]);
// Output: "/Path/to/somethin"

// Example with array of 2 strings for charsToTrim, false for caseSensitive &  default for replaceMultipleOccurrences (true)
subjectString.rightTrimChars(["/", "g"], false);
// Output: "/Path/to/somethin"

// Example with array of 2 strings for charsToTrim, true for caseSensitive & false for replaceMultipleOccurrences (hence only the first "/" being replaced)
subjectString.rightTrimChars("/", true, false);
// Output: "/Path/to/somethinG//"

// #1 Demonstrating the significance of ordering of the array of strings in charsToTrim
subjectString.rightTrimChars(["/", "G", "n"]);
// Output: "/Path/to/somethi"

// #2 Demonstrating the significance of ordering of the array of strings in charsToTrim
subjectString.rightTrimChars(["/", "n", "G"]);
// Output: "/Path/to/somethin"

###trimChars(charsToTrim, caseSensitive, replaceMultipleOccurrences, trimLeft, trimRight) ####Overview Trims the specified characters from the right of the string and returns the resulting trimmed string. ####Parameters:

• charsToTrim: a String or array of strings to trim from the subject string. If an array is specified, each string in the array is trimmed in turn, going from left to right.
• caseSensitive: boolean (default: true) - true for case-sensitive operation, false for case-insensitive.
• replaceMultipleOccurrences: boolean (default: true) - true to replace multiple contiguous occurrences of the string(s), false to replace only the first.
• trimLeft: boolean - provided because leftTrimChars and rightTrimChars both use this function internally so that we have a single functional codebase
• trimRight: boolean - provided because leftTrimChars and rightTrimChars both use this function internally so that we have a single functional codebase

####Returns This function returns the resulting, trimmed string.
Because the resulting string is returned, this function is fully chainable.

####Examples Note: module loading not shown

var subjectString="///Path/to/somethinG///";

// Simple example with string charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences
subjectString.trimChars("/");
// Output: "Path/to/somethinG"

// Simple example with array charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - same result as above
subjectString.trimChars(["/"]);
// Output: "Path/to/somethinG"

// Example with array of 2 strings for charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - demonstrates default being case-sensitive (hence not replacing the "P" in "Path/..." & the "G" in ".../somethinG")
subjectString.trimChars(["/", "p", "g"]);
// Output: "Path/to/somethinG"

// Example with array of 2 strings for charsToTrim and defaults for caseSensitive &  replaceMultipleOccurrences - demonstrates default being case-sensitive (hence replacing the "P" in "Path/..." & the "G" in ".../somethinG")
subjectString.trimChars(["/", "P", "G"]);
// Output: "ath/to/somethin"

// Example with array of 2 strings for charsToTrim, false for caseSensitive &  default for replaceMultipleOccurrences (true)
subjectString.trimChars(["/", "p", "g"], false);
// Output: "ath/to/somethin"

// Example with array of 2 strings for charsToTrim, true for caseSensitive & false for replaceMultipleOccurrences (hence only the first "/" being replaced)
subjectString.trimChars("/", true, false);
// Output: "//Path/to/somethinG//"

// #1 Demonstrating the significance of ordering of the array of strings in charsToTrim
subjectString.trimChars(["/", "P", "a", "G", "n"]);
// Output: "th/to/somethi"

// #2 Demonstrating the significance of ordering of the array of strings in charsToTrim
subjectString.trimChars(["/", "a", "P", "n", "G"]);
// Output: "ath/to/somethin"

##To do

• Improve tests:
  • Genericise tests
  • Reduce duplication (found issue with Mocha during initial attempts - need to assess whether this was due to incorrect usage or a Mocha feature/bug)
• Fix filed bugs