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,19 @@ lines("Hello\nWorld");
 // => ["Hello", "World"]
 ```
 
+#### wrap(str, width, seperator, cut) => string
+
+Splits a line `str` (default '') into several lines of size `width` (default 75) using a `seperator` (default '\n').
+When `cut` (default false) is true, wrap will start a new line in the middle of a word.
+
+```javascript
+wrap("Hello World", 5)
+// => "Hello \nWorld"
+
+wrap("Hello World", 5, '.', true)
+// => "Hello. Worl.d"
+```
+
 #### 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,18 @@
+var equal = require('assert').equal;
+var wrap = require('../wrap');
+
+test('#wrap', function(){
+
+	equal(wrap("My name is", 2, '.', false), "My .name .is", 'works with width 2 and cut = false');
+	equal(wrap("My name is", 2, '.', true), "My. n.am.e .is", 'works with width 2 and cut = true');
+	equal(wrap("My name is", 3, '.', false), "My .name .is", 'works with width 3 and cut = true');
+
+	// defaults
+	equal(wrap("My name is", 3), "My \nname \nis", 'Default parameters work');
+	equal(wrap("My name is"), "My name is", 'Default parameters work');
+	equal(wrap("", 5), "", 'Empty string');
+	equal(wrap("My name is", 0), "My name is", "Just return original line if width <= 0")
+	equal(wrap(null, 5), "", 'null');
+	equal(wrap(undefined, 5), "", 'undefined');
+
+})

wrap.js

@@ -0,0 +1,55 @@
+// Wrap
+// wraps a string by a certain width
+
+makeString = require('./helper/makeString');
+
+module.exports = function wrap(str, width, seperator, cut){
+	str = makeString(str);
+	width = width || 75;
+	seperator = seperator || '\n';
+	cut = cut || false;
+	if(width <= 0){
+		return str;
+	}
+	else if(!cut){
+		words = str.split(" ");
+		for(var i = 0; i < words.length - 1; i++){
+			//preserve the spaces for all words except the last one
+			words[i] = words[i] + " ";
+		}
+		// now words looks like ['firstWord ', 'secondWord ', 'lastWord']
+
+		result = "";
+		current_column = 0;
+
+		while(words.length > 0){
+			// if adding the next word would cause this line to be longer than width...
+			if(words[0].length + current_column > width){
+				//start a new line if this line is not already empty
+				if(current_column > 0){
+					//start new line
+					result += seperator;
+					current_column = 0;
+				}
+			}
+			result += words[0];
+			current_column += words[0].length;
+			words.shift();
+		}
+		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++;
+		}
+		return result;
+	}
+};