Add wrap function

Adds a line wrapping function that limits line length to a certain width
Added documentation and tests

README.markdown

@@ -269,6 +269,25 @@ lines("Hello\nWorld");
 // => ["Hello", "World"]
 ```
 
+#### wrap(str, options) => string
+
+Splits a line `str` (default '') into several lines of size `options.width` (default 75) using a `options.seperator` (default '\n'). If `options.trailingSpaces` is true, make each line at least `width` long using trailing spaces. If `options.cut` is true, create new lines in the middle of words. If `options.preserveSpaces` is true, preserve the space that should be there at the end of a line (only works if options.cut is false). 
+
+```javascript
+wrap("Hello World", { width:5 })
+// => "Hello\nWorld"
+
+wrap("Hello World", { width:6, seperator:'.', trailingSpaces: true })
+// => "Hello .World "
+
+wrap("Hello World", { width:5, seperator:'.', cut:true, trailingSpaces: true })
+// => "Hello. Worl.d    "
+
+wrap("Hello World", { width:5, seperator:'.', preserveSpaces: true })
+// => "Hello .World"
+
+```
+
 #### dedent(str, [pattern]) => string
 
 Dedent unnecessary indentation or dedent by a pattern.

index.js

@@ -74,6 +74,7 @@ s.levenshtein      = require('./levenshtein');
 s.toBoolean        = require('./toBoolean');
 s.exports          = require('./exports');
 s.escapeRegExp     = require('./helper/escapeRegExp');
+s.wrap             = require('./wrap');
 
 // Aliases
 s.strip     = s.trim;

tests/wrap.js

@@ -0,0 +1,35 @@
+var equal = require('assert').equal;
+var wrap = require('../wrap');
+
+test('#wrap', function(){
+
+	// without trailing spaces
+	equal(wrap("My name is", { width: 2, seperator:'.', cut:false, trailingSpaces:false } ), "My.name.is", 'works with width 2 and cut = false');
+	equal(wrap("My name is", { width: 2, seperator:'.', cut:true, trailingSpaces:false } ), "My. n.am.e .is", 'works with width 2 and cut = true');
+	equal(wrap("My name is", { width: 3, seperator:'.', cut:false, trailingSpaces:false } ), "My.name.is", 'works with width 3 and cut = true');
+	equal(wrap("My name is", { width: 3, seperator:'.', cut:true, trailingSpaces:false } ), "My .nam.e i.s", 'works with width 3 and cut = true');
+
+	// with trailing spaces
+	equal(wrap("My name is", { width: 2, seperator:'.', cut:false, trailingSpaces:true } ), "My.name.is", 'works with width 2 and cut = false and trailingSpaces = true');
+	equal(wrap("My name is", { width: 2, seperator:'.', cut:true, trailingSpaces:true } ), "My. n.am.e .is", 'works with width 2 and cut = true and trailingSpaces = true');
+	equal(wrap("My name is", { width: 3, seperator:'.', cut:false, trailingSpaces:true } ), "My .name.is ", 'works with width 3 and cut = true and trailingSpaces = true');
+	equal(wrap("My name is", { width: 3, seperator:'.', cut:true, trailingSpaces:true } ), "My .nam.e i.s  ", 'works with width 3 and cut = true and trailingSpaces = true');
+
+	// with preserveSpaces
+	equal(wrap('My name is', {width: 2, seperator:'.', cut:false, preserveSpaces:true }), 'My .name .is', 'preserve spaces keeps the space at the end of a line');
+	equal(wrap('My name is', {width: 3, seperator:'.', cut:false, preserveSpaces:true }), 'My .name .is', 'preserve spaces keeps the space at the end of a line');
+
+	// with preserveSpaces and trailingSpaces
+	equal(wrap('My name is', {width: 2, seperator:'.', cut:false, preserveSpaces:true, trailingSpaces:true }), 'My .name .is', 'preserve spaces takes precedence over trailing spaces');
+
+
+	// defaults
+	equal(wrap("My name is", { width: 3 } ), "My\nname\nis", 'Default parameters work');
+	equal(wrap("My name is"), "My name is", 'Default parameters work');
+	equal(wrap("", { width: 5 } ), "", 'Empty string');
+	equal(wrap("My name is", { width: 0 } ), "My name is", "Just return original line if width <= 0");
+	equal(wrap("My name is", { width: -1 } ), "My name is", "Just return original line if width <= 0");
+	equal(wrap(null, { width: 5 } ), "", 'null');
+	equal(wrap(undefined, { width: 5 } ), "", 'undefined');
+
+})

wrap.js

@@ -0,0 +1,100 @@
+// Wrap
+// wraps a string by a certain width
+
+makeString = require('./helper/makeString');
+
+module.exports = function wrap(str, options){
+	str = makeString(str);
+
+	options = options || {};
+
+	width = options.width || 75;
+	seperator = options.seperator || '\n';
+	cut = options.cut || false;
+	preserveSpaces = options.preserveSpaces || false;
+	trailingSpaces = options.trailingSpaces || false;
+
+	if(width <= 0){
+		return str;
+	}
+
+	else if(!cut){
+
+		words = str.split(" ");
+		result = "";
+		current_column = 0;
+
+		while(words.length > 0){
+
+			// if adding a space and the next word would cause this line to be longer than width...
+			if(1 + words[0].length + current_column > width){
+				//start a new line if this line is not already empty
+				if(current_column > 0){
+					// add a space at the end of the line is preserveSpaces is true
+					if (preserveSpaces){
+						result += ' ';
+						current_column++;
+					}
+					// fill the rest of the line with spaces if trailingSpaces option is true
+					else if(trailingSpaces){
+						while(current_column < width){
+							result += ' ';
+							current_column++;
+						}						
+					}
+					//start new line
+					result += seperator;
+					current_column = 0;
+				}
+			}
+
+			// if not at the begining of the line, add a space in front of the word
+			if(current_column > 0){
+				result += " ";
+				current_column++;
+			}
+
+			// tack on the next word, update current column, a pop words array
+			result += words[0];
+			current_column += words[0].length;
+			words.shift();
+
+		}
+
+		// fill the rest of the line with spaces if trailingSpaces option is true
+		if(trailingSpaces){
+			while(current_column < width){
+				result += ' ';
+				current_column++;
+			}						
+		}
+
+		return result;
+
+	}
+
+	else {
+
+		index = 0;
+		result = "";
+
+		// walk through each character and add seperators where appropriate
+		while(index < str.length){
+			if(index % width == 0 && index > 0){
+				result += seperator;
+			}
+			result += str.charAt(index);
+			index++;
+		}
+
+		// fill the rest of the line with spaces if trailingSpaces option is true
+		if(trailingSpaces){
+			while(index % width > 0){
+				result += ' ';
+				index++;
+			}						
+		}
+
+		return result;
+	}
+};