Removed documentation for oneXXX and unXXX methods (not yet implementation), added...
[jquery.git] / src / jquery / jquery.js
index 7f7ef08..62010e2 100644 (file)
@@ -510,9 +510,9 @@ jQuery.fn = jQuery.prototype = {
 
                e = e || this;
                var t = "";
-               for ( var j = 0; j < e.length; j++ ) {
+               for ( var j = 0, el = e.length; j < el; j++ ) {
                        var r = e[j].childNodes;
-                       for ( var i = 0; i < r.length; i++ )
+                       for ( var i = 0, rl = r.length; i < rl; i++ )
                                if ( r[i].nodeType != 8 )
                                        t += r[i].nodeType != 1 ?
                                                r[i].nodeValue : jQuery.fn.text([ r[i] ]);
@@ -882,7 +882,7 @@ jQuery.fn = jQuery.prototype = {
                return this.pushStack(
                        t.constructor == Array &&
                        jQuery.map(this,function(a){
-                               for ( var i = 0; i < t.length; i++ )
+                               for ( var i = 0, tl = t.length; i < tl; i++ )
                                        if ( jQuery.filter(t[i],[a]).r.length )
                                                return a;
                                return null;
@@ -1030,7 +1030,7 @@ jQuery.fn = jQuery.prototype = {
                        if ( table && this.nodeName.toUpperCase() == "TABLE" && a[0].nodeName.toUpperCase() == "TR" )
                                obj = this.getElementsByTagName("tbody")[0] || this.appendChild(document.createElement("tbody"));
 
-                       for ( var i=0; i < a.length; i++ )
+                       for ( var i = 0, al = a.length; i < al; i++ )
                                fn.apply( obj, [ clone ? a[i].cloneNode(true) : a[i] ] );
 
                });
@@ -1164,7 +1164,7 @@ jQuery.extend({
                        jQuery.fn[ i ] = function(){
                                var a = arguments;
                                return this.each(function(){
-                                       for ( var j = 0; j < a.length; j++ )
+                                       for ( var j = 0, al = a.length; j < al; j++ )
                                                jQuery(a[j])[n]( this );
                                });
                        };
@@ -1229,34 +1229,26 @@ jQuery.extend({
                        for ( var i in obj )
                                fn.apply( obj[i], args || [i, obj[i]] );
                else
-                       for ( var i = 0; i < obj.length; i++ )
+                       for ( var i = 0, ol = obj.length; i < ol; i++ )
                                if ( fn.apply( obj[i], args || [i, obj[i]] ) === false ) break;
                return obj;
        },
 
        className: {
-               add: function(o,c){
-                       if (jQuery.className.has(o,c)) return;
-                       o.className += ( o.className ? " " : "" ) + c;
+               add: function( elem, c ){
+                       jQuery.each( c.split(/\s+/), function(i, cur){
+                               if ( !jQuery.className.has( elem.className, cur ) )
+                                       elem.className += ( elem.className ? " " : "" ) + cur;
+                       });
                },
-               remove: function(o,c){
-                       if( !c ) {
-                               o.className = "";
-                       } else {
-                               var classes = o.className.split(" ");
-                               for(var i=0; i<classes.length; i++) {
-                                       if(classes[i] == c) {
-                                               classes.splice(i, 1);
-                                               break;
-                                       }
-                               }
-                               o.className = classes.join(' ');
-                       }
+               remove: function( elem, c ){
+            elem.className = c ?
+                jQuery.grep( elem.className.split(/\s+/), function(cur){
+                                   return !jQuery.className.has( c, cur );     
+                }).join(' ') : "";
                },
-               has: function(e,a) {
-                       if ( e.className != undefined )
-                               e = e.className;
-                       return new RegExp("(^|\\s)" + a + "(\\s|$)").test(e);
+               has: function( classes, c ){
+                       return classes && new RegExp("(^|\\s)" + c + "(\\s|$)").test( classes );
                }
        },
 
@@ -1278,7 +1270,7 @@ jQuery.extend({
                if ( p == "height" || p == "width" ) {
                        var old = {}, oHeight, oWidth, d = ["Top","Bottom","Right","Left"];
 
-                       for ( var i=0; i<d.length; i++ ) {
+                       for ( var i = 0, dl = d.length; i < dl; i++ ) {
                                old["padding" + d[i]] = 0;
                                old["border" + d[i] + "Width"] = 0;
                        }
@@ -1357,7 +1349,7 @@ jQuery.extend({
        
        clean: function(a) {
                var r = [];
-               for ( var i = 0; i < a.length; i++ ) {
+               for ( var i = 0, al = a.length; i < al; i++ ) {
                        var arg = a[i];
                        if ( typeof arg == "string" ) { // Convert html string into DOM nodes
                                // Trim whitespace, otherwise indexOf won't work as expected
@@ -1398,7 +1390,7 @@ jQuery.extend({
                        
                        
                        if ( arg.length != undefined && ( (jQuery.browser.safari && typeof arg == 'function') || !arg.nodeType ) ) // Safari reports typeof on a DOM NodeList to be a function
-                               for ( var n = 0; n < arg.length; n++ ) // Handles Array, jQuery, DOM NodeList collections
+                               for ( var n = 0, argl = arg.length; n < argl; n++ ) // Handles Array, jQuery, DOM NodeList collections
                                        r.push(arg[n]);
                        else
                                r.push( arg.nodeType ? arg : document.createTextNode(arg.toString()) );
@@ -1407,6 +1399,18 @@ jQuery.extend({
                return r;
        },
 
+       /**
+        * A handy, and fast, way to traverse in a particular direction and find
+        * a specific element.
+        *
+        * @private
+        * @name $.nth
+        * @type DOMElement
+        * @param DOMElement cur The element to search from.
+        * @param Number|String num The Nth result to match. Can be a number or a string (like 'even' or 'odd').
+        * @param String dir The direction to move in (pass in something like 'previousSibling' or 'nextSibling').
+        * @cat DOM/Traversing
+        */
        nth: function(cur,result,dir){
                result = result || 1;
                var num = 0;
@@ -1463,7 +1467,7 @@ jQuery.extend({
                        submit: "a.type=='submit'",
                        image: "a.type=='image'",
                        reset: "a.type=='reset'",
-                       button: "a.type=='button'",
+                       button: "a.type=='button'||a.nodeName=='BUTTON'",
                        input: "/input|select|textarea|button/i.test(a.nodeName)"
                },
                ".": "jQuery.className.has(a,m[2])",
@@ -1507,7 +1511,7 @@ jQuery.extend({
                ">|/", "jQuery.sibling(a.firstChild)",
                "\\+", "jQuery.nth(a,2,'nextSibling')",
                "~", function(a){
-                       var s = jQuery.sibling(a.parentNode.firstChild)
+                       var s = jQuery.sibling(a.parentNode.firstChild);
                        return s.slice(0, jQuery.inArray(a,s));
                }
        ],
@@ -1563,7 +1567,7 @@ jQuery.extend({
 
                        if ( m ) {
                                // Perform our own iteration and filter
-                               for ( var i = 0; i < ret.length; i++ )
+                               for ( var i = 0, rl = ret.length; i < rl; i++ )
                                        for ( var c = ret[i].firstChild; c; c = c.nextSibling )
                                                if ( c.nodeType == 1 && ( c.nodeName == m[1].toUpperCase() || m[1] == "*" ) )
                                                        r.push( c );
@@ -1649,7 +1653,7 @@ jQuery.extend({
                                                // We need to find all descendant elements, it is more
                                                // efficient to use getAll() when we are already further down
                                                // the tree - we try to recognize that here
-                                               for ( var i = 0; i < ret.length; i++ )
+                                               for ( var i = 0, rl = ret.length; i < rl; i++ )
                                                        jQuery.merge( r,
                                                                m[1] != "" && ret.length != 1 ?
                                                                        jQuery.getAll( ret[i], [], m[1], m[2], rec ) :
@@ -1669,7 +1673,7 @@ jQuery.extend({
                                                        r = [];
 
                                                        // Then try to find the element with the ID
-                                                       for ( var i = 0; i < tmp.length; i++ )
+                                                       for ( var i = 0, tl = tmp.length; i < tl; i++ )
                                                                if ( tmp[i].getAttribute("id") == m[2] ) {
                                                                        r = [ tmp[i] ];
                                                                        break;
@@ -1799,7 +1803,7 @@ jQuery.extend({
 
                        var p = jQuery.parse;
 
-                       for ( var i = 0; i < p.length; i++ ) {
+                       for ( var i = 0, pl = p.length; i < pl; i++ ) {
                
                                // Look for, and replace, string-like sequences
                                // and finally build a regexp out of it
@@ -1893,7 +1897,7 @@ jQuery.extend({
                var r = [];
 
                if ( a.constructor != Array ) {
-                       for ( var i = 0; i < a.length; i++ )
+                       for ( var i = 0, al = a.length; i < al; i++ )
                                r.push( a[i] );
                } else
                        r = a.slice( 0 );
@@ -1902,7 +1906,7 @@ jQuery.extend({
        },
 
        inArray: function( b, a ) {
-               for ( var i = 0; i < a.length; i++ )
+               for ( var i = 0, al = a.length; i < al; i++ )
                        if ( a[i] == b )
                                return i;
                return -1;
@@ -1930,7 +1934,7 @@ jQuery.extend({
 
                // Now check for duplicates between the two arrays
                // and only add the unique items
-               for ( var i = 0; i < second.length; i++ ) {
+               for ( var i = 0, sl = second.length; i < sl; i++ ) {
                        // Check for duplicates
                        if ( jQuery.inArray( second[i], r ) == -1 )
                                // The item is unique, add it
@@ -1969,7 +1973,7 @@ jQuery.extend({
 
                // Go through the array, only saving the items
                // that pass the validator function
-               for ( var i = 0; i < elems.length; i++ )
+               for ( var i = 0, el = elems.length; i < el; i++ )
                        if ( !inv && fn(elems[i],i) || inv && !fn(elems[i],i) )
                                result.push( elems[i] );
 
@@ -2015,7 +2019,7 @@ jQuery.extend({
 
                // Go through the array, translating each of the items to their
                // new value (or values).
-               for ( var i = 0; i < elems.length; i++ ) {
+               for ( var i = 0, el = elems.length; i < el; i++ ) {
                        var val = fn(elems[i],i);
 
                        if ( val !== null && val != undefined ) {
@@ -2026,7 +2030,7 @@ jQuery.extend({
 
                var r = [ result[0] ];
 
-               check: for ( var i = 1; i < result.length; i++ ) {
+               check: for ( var i = 1, rl = result.length; i < rl; i++ ) {
                        for ( var j = 0; j < i; j++ )
                                if ( result[i] == r[j] )
                                        continue check;
@@ -2115,7 +2119,7 @@ jQuery.extend({
                        if ( !element ) {
                                var g = this.global[type];
                                if ( g )
-                                       for ( var i = 0; i < g.length; i++ )
+                                       for ( var i = 0, gl = g.length; i < gl; i++ )
                                                this.trigger( type, data, g[i] );
 
                        // Handle triggering a single element
@@ -3093,15 +3097,19 @@ jQuery.macros = {
                },
 
                /**
-                * Removes the specified class from the set of matched elements.
+                * Removes all or the specified class from the set of matched elements.
                 *
-                * @example $("p").removeClass("selected")
+                * @example $("p").removeClass()
                 * @before <p class="selected">Hello</p>
                 * @result [ <p>Hello</p> ]
                 *
+                * @example $("p").removeClass("selected")
+                * @before <p class="selected first">Hello</p>
+                * @result [ <p class="first">Hello</p> ]
+                *
                 * @name removeClass
                 * @type jQuery
-                * @param String class A CSS class to remove from the elements
+                * @param String class (optional) A CSS class to remove from the elements
                 * @cat DOM
                 */
                removeClass: function(c){
@@ -3222,6 +3230,39 @@ jQuery.macros = {
                bind: function( type, data, fn ) {
                        jQuery.event.add( this, type, fn || data, data );
                },
+               
+               /**
+                * Binds a handler to a particular event (like click) for each matched element.
+                * The handler is executed only once for each element. Otherwise, the same rules
+                * as described in bind() apply.
+                The event handler is passed an event object that you can use to prevent
+                * default behaviour. To stop both default action and event bubbling, your handler
+                * has to return false.
+                *
+                * In most cases, you can define your event handlers as anonymous functions
+                * (see first example). In cases where that is not possible, you can pass additional
+                * data as the second paramter (and the handler function as the third), see 
+                * second example.
+                *
+                * @example $("p").one( "click", function() {
+                *   alert( $(this).text() );
+                * } )
+                * @before <p>Hello</p>
+                * @result alert("Hello")
+                *
+                * @name one
+                * @type jQuery
+                * @param String type An event type
+                * @param Object data (optional) Additional data passed to the event handler as event.data
+                * @param Function fn A function to bind to the event on each of the set of matched elements
+                * @cat Events
+                */
+               one: function( type, data, fn ) {
+                       jQuery.event.add( this, type, function(event) {
+                               jQuery(this).unbind(event);
+                               return (fn || data).apply( this, arguments);
+                       }, data);
+               },
 
                /**
                 * The opposite of bind, removes a bound event from each of the matched
@@ -3286,4 +3327,4 @@ jQuery.macros = {
        }
 };
 
-jQuery.init();
+jQuery.init();
\ No newline at end of file