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

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

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

RequireJS example:

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

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

`
var amdloader=require("amd-loader");
var stringTrimFunctions=require("../stringTrimFunctions.js");

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

##A note on replacement procesing 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 - 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.

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/"
`


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