Common Utilities

comb includes a lot of function that are used commonly when developing application. Here we'll go over a few of the most commonly used ones.

is* functions

comb includes a number of is function to test if something is of the type.

• isDefined : test if the arguments is defined.
• isUndefined
• isNull
• isUndefinedOrNull
• isArguments
• isObject
• isHash
• isBoolean
• isDate
• isEmpty
• isFunction
• isInstanceOf
• isNumber
• isPromiseLike
• isRegExp
• isString

String utilities

format

Formats a string with the specified format.

// "Hello, World";                                                                                                     
comb.string.format("%s, %s", ["Hello", "World"]);

//"     Hello, World     "
comb.string.format("%[ 10]s, %[- 10]s", ["Hello", "World"])                               

//"apple!!!!!, ####orange,    bananas and watermelon"
comb.string.format("%-!10s, %#10s, %10s and %-10s", "apple", "orange", "bananas", "watermelons")                 

//"+1, -2, 0000000001, 2000000000, +3########, 1000000000"             
comb.string.format("%+d, %+d, %10d, %-10d, %-+#10d, %10d", 1,-2, 1, 2, 3, 100000000000)                                         

//formats in local time
//7:32 PM 
comb.string.format("%[h:mm a]D", [date])

//format in UTC
//12:32 PM
comb.string.format("%[h:mm a]Z", [date])

//When using object formats they must be in an array otherwise                
//format will try to interpolate the properties into the string.              

//'{"a":"b"}'
comb.string.format("%j", [{a : "b"}])                                                     

//'{\n "a": "b"\n},\n{\n    "a": "b"\n}'                                                            
comb.string.format("%1j, %4j", [{a : "b"}, {a : "b"}])    

//"Hello, World"                                                                 
comb.string.format("{hello}, {world}", {hello : "Hello", world : "World")                 


//applesssss, ####orange,    bananas and watermelon      
comb.string.format("{[-s10]apple}, {[%#10]orange}, {[10]banana} and {[-10]watermelons}", {
    apple:"apple",
    orange:"orange",
    banana:"bananas",
    watermelons:"watermelons"
});

• String Formats %[options]s
  • - : left justified
  • Char : padding character Excludes d,j,s
  • Number : width
• Number Formats %[options]d
  • - : left justified
  • + : signed number
  • Char : padding character Excludes d,j,s
  • Number : width
• Object Formats %[options]j
  • Number : spacing for object properties.
• Date Options %[format]D or %[format]Z. See comb.date.format for formatting options.

style

Styles a string for terminal output.

//style a string red                      
comb.string.style('myStr', 'red');        
//style a string red and bold             
comb.string.style('myStr', ['red', bold]);

The style options include

• bold
• bright
• italic
• underline
• inverse
• crossedOut
• blink
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• redBackground
• greenBackground
• yellowBackground
• blueBackground
• magentaBackground
• cyanBackground
• whiteBackground
• grey
• black

Others

• pad
• toArray
• truncate
• multiply

Array utilities

avg

Averages an array of numbers.

comb.array.avg([1,2,3]); //2

compact

Compacts an array removing null or undefined objects from the array.

var x;
comb.array.compact([1,null,null,x,2]) => [1,2]
comb.array.compact([1,2]) => [1,2]

difference

Finds the difference of the two arrays.

comb.array.difference([1,2,3], [2,3]); //[1]
comb.array.difference(["a","b",3], [3]); //["a","b"]

flatten

Flatten multiple arrays into a single array

comb.array.flatten([1,2], [2,3], [3,4]) => [1,2,2,3,3,4]
comb.array.flatten([1,"A"], [2,"B"], [3,"C"]) => [1,"A",2,"B",3,"C"]

intersect

Finds the intersection of arrays.

comb.array.intersect([1,2], [2,3], [2,3,5]) => [2]
comb.array.intersect([1,2,3], [2,3,4,5], [2,3,5]) => [2,3]
comb.array.intersect([1,2,3,4], [2,3,4,5], [2,3,4,5]) => [2,3,4]
comb.array.intersect([1,2,3,4,5], [1,2,3,4,5], [1,2,3]) => [1,2,3]
comb.array.intersect([[1,2,3,4,5],[1,2,3,4,5],[1,2,3]]) => [1,2,3]

max

Finds that max value of an array. If a second argument is provided and it is a function it will be used as a comparator function. If the second argument is a string then it will be used as a property look up on each item.

comb.array.max([{a : 1}, {a : 2}, {a : -2}], "a"); //{a : 2}
comb.array.max([{a : 1}, {a : 2}, {a : -2}], function(a,b){
     return a.a - b.a
}); //{a : 2}

min

Finds that min value of an array. If a second argument is provided and it is a function it will be used as a comparator function. If the second argument is a string then it will be used as a property look up on each item.

comb.array.min([{a : 1}, {a : 2}, {a : -2}], "a"); //{a : -2}
comb.array.min([{a : 1}, {a : 2}, {a : -2}], function(a,b){
     return a.a - b.a
}); //{a : -2}

sort

Allows the sorting of an array based on a property name instead. This can also act as a sort that does not change the original array. NOTE: this does not change the original array!

comb.array.sort([{a : 1}, {a : 2}, {a : -2}], "a"); //[{a : -2}, {a : 1}, {a : 2}];

removeDuplicates

Removes duplicates from an array.

comb.array.removeDuplicates([1,1,1]) => [1]
comb.array.removeDuplicates([1,2,3,2]) => [1,2,3]

sum

Finds the sum of an array

comb.array.sum([1,2,3]) => 6

toArray

Converts anything to an array. Useful if you want to covert a hash into an array.

comb.array.toArray({a : "b", b : "c"}) => [["a","b"], ["b","c"]];
comb.array.toArray("a") => ["a"]
comb.array.toArray(["a"]) =>  ["a"];
comb.array.toArray() => [];
comb.array.toArray("a", {a : "b"}) => ["a", ["a", "b"]];

union

Finds the union of two arrays

comb.array.union(['a','b','c'], ['b','c', 'd']) => ["a", "b", "c", "d"]
comb.array.union(["a"], ["b"], ["c"], ["d"], ["c"]) => ["a", "b", "c", "d"]

zip

Zips multiple arrays into a single array.

var a = [ 4, 5, 6 ], b = [ 7, 8, 9 ]

comb.array.zip([1], [2], [3]) => [[ 1, 2, 3 ]]);
comb.array.zip([1,2], [2], [3]) => [[ 1, 2, 3 ],[2, null, null]]
comb.array.zip([1,2,3], a, b) => [[1, 4, 7],[2, 5, 8],[3, 6, 9]]
comb.array.zip([1,2], a, b) => [[1, 4, 7],[2, 5, 8]]
comb.array.zip(a, [1,2], [8]) => [[4,1,8],[5,2,null],[6,null,null]]

Number utilities

round

Rounds a number to the specified places.

comb.number.round(10.000009, 2); //10
comb.number.round(10.000009, 5); //10.00001
comb.number.round(10.0009, 3); //10.001
comb.number.round(10.0009, 2); //10
comb.number.round(10.0009, 3); //10.001

roundCeil

Rounds a number to the specified places, rounding up.

comb.number.roundCeil(10.000001, 2); //10.01
comb.number.roundCeil(10.000002, 5); //10.00001
comb.number.roundCeil(10.0003, 3); //10.001
comb.number.roundCeil(10.0004, 2); //10.01
comb.number.roundCeil(10.0005, 3); //10.001
comb.number.roundCeil(10.0002, 2); //10.01

Date utilities

add

Adds a specified interval and amount to a date

var dtA = new Date(2005, 11, 27);
comb.date.add(dtA, "year", 1); //new Date(2006, 11, 27);
comb.date.add(dtA, "years", 1) //new Date(2006, 11, 27);

dtA = new Date(2000, 0, 1);
comb.date.add(dtA, "quarter", 1); //new Date(2000, 3, 1);
comb.date.add(dtA, "quarters", 1); //new Date(2000, 3, 1);

dtA = new Date(2000, 0, 1);
comb.date.add(dtA, "month", 1); //new Date(2000, 1, 1);
comb.date.add(dtA, "months", 1); //new Date(2000, 1, 1);

dtA = new Date(2000, 0, 31);
comb.date.add(dtA, "month", 1); //new Date(2000, 1, 29);
comb.date.add(dtA, "months", 1); //new Date(2000, 1, 29);

dtA = new Date(2000, 0, 1);
comb.date.add(dtA, "week", 1); //new Date(2000, 0, 8);
comb.date.add(dtA, "weeks", 1); //new Date(2000, 0, 8);

dtA = new Date(2000, 0, 1);
comb.date.add(dtA, "day", 1); //new Date(2000, 0, 2);

dtA = new Date(2000, 0, 1);
comb.date.add(dtA, "weekday", 1); //new Date(2000, 0, 3);

dtA = new Date(2000, 0, 1, 11);
comb.date.add(dtA, "hour", 1); //new Date(2000, 0, 1, 12);

dtA = new Date(2000, 11, 31, 23, 59);
comb.date.add(dtA, "minute", 1); //new Date(2001, 0, 1, 0, 0);

dtA = new Date(2000, 11, 31, 23, 59, 59);
comb.date.add(dtA, "second", 1); //new Date(2001, 0, 1, 0, 0, 0);

dtA = new Date(2000, 11, 31, 23, 59, 59, 999);
comb.date.add(dtA, "millisecond", 1); //new Date(2001, 0, 1, 0, 0, 0, 0);

compare

Compares two dates

var d1 = new Date();
d1.setHours(0);
comb.date.compare(d1, d1); //0

var d1 = new Date();
d1.setHours(0);
var d2 = new Date();
d2.setFullYear(2005);
d2.setHours(12);
comb.date.compare(d1, d2, "date"); //1
comb.date.compare(d1, d2, "datetime"); //1

var d1 = new Date();
d1.setHours(0);
var d2 = new Date();
d2.setFullYear(2005);
d2.setHours(12);
comb.date.compare(d2, d1, "date"); //-1
comb.date.compare(d1, d2, "time"); //-1

difference

Finds the difference between two dates based on the specified interval

var dtA, dtB;

dtA = new Date(2005, 11, 27);
dtB = new Date(2006, 11, 27);
comb.date.difference(dtA, dtB, "year") => 1

dtA = new Date(2000, 1, 29);
dtB = new Date(2001, 2, 1);
comb.date.difference(dtA, dtB, "quarter") => 4
comb.date.difference(dtA, dtB, "month") => 13

dtA = new Date(2000, 1, 1);
dtB = new Date(2000, 1, 8);
comb.date.difference(dtA, dtB, "week") => 1

dtA = new Date(2000, 1, 29);
dtB = new Date(2000, 2, 1);
comb.date.difference(dtA, dtB, "day") => 1

dtA = new Date(2006, 7, 3);
dtB = new Date(2006, 7, 11);
comb.date.difference(dtA, dtB, "weekday") => 6

dtA = new Date(2000, 11, 31, 23);
dtB = new Date(2001, 0, 1, 0);
comb.date.difference(dtA, dtB, "hour") => 1

dtA = new Date(2000, 11, 31, 23, 59);
dtB = new Date(2001, 0, 1, 0, 0);
comb.date.difference(dtA, dtB, "minute") => 1

dtA = new Date(2000, 11, 31, 23, 59, 59);
dtB = new Date(2001, 0, 1, 0, 0, 0);
comb.date.difference(dtA, dtB, "second") => 1

dtA = new Date(2000, 11, 31, 23, 59, 59, 999);
dtB = new Date(2001, 0, 1, 0, 0, 0, 0);
comb.date.difference(dtA, dtB, "millisecond") => 1

format

Formats a date to the specidifed format string

var date = new Date(2006, 7, 11, 0, 55, 12, 345);

//"Friday, August 11, 2006"
comb.date.format(date, "EEEE, MMMM dd, yyyy"); 

//"8/11/06"
comb.date.format(date, "M/dd/yy"); 

//"6"
comb.date.format(date, "E"); 

//"12:55 AM"
comb.date.format(date, "h:m a"); 

//"12:55:12"
comb.date.format(date, 'h:m:s'); 

//"12:55:12.35"
comb.date.format(date, 'h:m:s.SS'); 

//"24:55:12.35"
comb.date.format(date, 'k:m:s.SS'); 

//"0:55:12.35"
comb.date.format(date, 'H:m:s.SS'); 

//"11082006"
comb.date.format(date, "ddMMyyyy");

Format specifiers include

• G Era designator Text AD
• y Year Year 1996; 96
• M Month in year Month July; Jul; 07
• w Week in year Number 27
• W Week in month Number 2
• D Day in year Number 189
• d Day in month Number 10
• E Day in week Text Tuesday; Tue
• a Am/pm marker Text PM
• H Hour in day (0-23) Number 0
• k Hour in day (1-24) Number 24
• K Hour in am/pm (0-11) Number 0
• h Hour in am/pm (1-12) Number 12
• m Minute in hour Number 30
• s Second in minute Number 55
• S Millisecond Number 978
• z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
• Z Time zone RFC 822 time zone -0800

parse

Parses a date string into a date object

var aug_11_2006 = new Date(2006, 7, 11, 0);
//all of the following will parse to aug_11_2006
 comb.date.parse("08/11/06", "MM/dd/yy");
 comb.date.parse("11Aug2006", 'ddMMMyyyy');
 comb.date.parse("Aug 11, 2006", "MMM dd, yyyy"); //aug_11_2006 
 comb.date.parse("August 11, 2006", "MMMM dd, yyyy"); //aug_11_2006
 comb.date.parse("Friday, August 11, 2006", "EEEE, MMMM dd, yyyy"); //aug_11_2006

Format specifiers include

• G Era designator Text AD
• y Year Year 1996; 96
• M Month in year Month July; Jul; 07
• w Week in year Number 27
• W Week in month Number 2
• D Day in year Number 189
• d Day in month Number 10
• E Day in week Text Tuesday; Tue
• a Am/pm marker Text PM
• H Hour in day (0-23) Number 0
• k Hour in day (1-24) Number 24
• K Hour in am/pm (0-11) Number 0
• h Hour in am/pm (1-12) Number 12
• m Minute in hour Number 30
• s Second in minute Number 55
• S Millisecond Number 978
• z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
• Z Time zone RFC 822 time zone -0800

ago and FromNow

comb also has the following methods as a convenience to adding time to Date.now()

• comb.secondsFromNow
• comb.secondsAgo
• comb.minutesFromNow
• comb.minutesAgo
• comb.hoursFromNow
• comb.hoursAgo
• comb.daysFromNow
• comb.daysAgo
• comb.monthsFromNow
• comb.monthsAgo
• comb.yearsFromNow
• comb.yearsAgo

Object utilities

merge

Merges objects together. This method will only change the frist object passed in.

var myObj = {};
comb.merge(myObj, {test : true});

myObj.test; //true

comb.merge(myObj, {test : false}, {test2 : false}, {test3 : "hello", test4 : "world"});
myObj.test; //false
myObj.test2; //false
myObj.test3; //"hello"
myObj.test4; //"world"

deepMerge

Merges objects together only overriding properties that are different.

var myObj = {my : {cool : {property1 : 1, property2 : 2}}};
comb.deepMerge(myObj, {my : {cool : {property3 : 3}}});

myObj.my.cool.property1; \\1
myObj.my.cool.property2; \\2
myObj.my.cool.property3; \\3

deepEqual

Determines if an two things are deep equal. This is a reimplementation of assert.deepEqual so you do not have to use a try/catch.

comb.deepEqual({a : 1, b : 2}, {a : 1, b : 2}); \\ true
comb.deepEqual({a : 1}, {a : 1, b : 2}); \\false

---

License

MIT https://github.com/C2FO/comb/raw/master/LICENSE

Meta

• Code: git clone git://github.com/C2FO/comb.git
• Website: http://c2fo.com
• Twitter: http://twitter.com/c2fo - 877.465.4045