core.md.svn-base

mooltools源码很不错的源码

Core {#Core}
============

包含一系列在[MooTools](http://mootools.net)中常用的工具函数。
也包含一些诸如[Hash][]和[Array][]的基本扩展方法。

函数: $chk {#chk}
---------------------

检测参数值存在(非null, undefined, false, 或 "")或为0. 适用于将0也视作通行条件的情况.

### 语法:

	$chk(item);

### 参数:

1. item - (*mixed*) 目标检测对象

### 返回值:

* (*boolean*) 如果传入的对象存在或值为0,返回true; 否则返回false.

### 示例:

	function myFunction(arg){
		if($chk(arg)) {
			alert('The object exists or is 0.');
		}
		else {
			alert('The object is either null, undefined, false, or ""');
		}
	}



函数: $clear {#clear}
-------------------------

清除定时器(Timeout或Interval). 通常配合[Function:delay][]和[Function:periodical][]方法使用.

### 语法:

	$clear(timer);

### 参数:

1. timer - (*number*) 要清除的目标定时器, 即由setInterval(periodical)或setTimeout(delay)产生的定时器对象引用.

### 返回值:

* (*false*) 返回null

### 示例:

	var myTimer = myFunction.delay(5000); //等待5秒后执行myFunction
	myTimer = $clear(myTimer); //取消定时执行的myFunction

### 另参考:

- [Function:delay][]
- [Function:periodical][]



函数: $defined {#defined}
-----------------------------

检测参数值是否已定义

### 语法:

	$defined(obj);

### 参数:

1. obj - (*mixed*) 目标检测对象.

### 返回值:

* (*boolean*) 如果传入对象不为null或undefined,返回true; 否则返回false.

### 示例:

	function myFunction(arg){
		if($defined(arg)){ 
			alert('The object is defined.');
		}
		else{ 
			alert('The object is null or undefined.');
		}
	}



函数: $arguments {#arguments}
---------------------------------

创建一个可返回传入参数的特定项的函数(详见示例)

### 语法:

	var argument = $arguments(i);

### 参数

1. i - (*number*) 指定返回参数项的索引号

### 返回值

* (*function*) 可返回特定项参数的函数

### 示例:

	var secondArgument = $arguments(1);  //创建一个总返回传入参数的第二个参数的函数
	alert(secondArgument('a','b','c'));  //显示 "b"



函数: $empty {#empty}
-------------------------

一个什么事情都不做的空函数. 典型应用: 事件监听器的占位方法.

### 语法:

	var emptyFn = $empty;

### 示例:

	var myFunc = $empty;
	

函数: $lambda {#lambda}
-------------------------

对传入的参数进行函数封装.

即,如果传入参数为一个function,则原样返回该function; 

如果为其他对象,则返回一个新创建的function, 该function不做其他任何事,仅仅是返回原来这个对象.

### 语法:

	var returnTrue = $lambda(true);
	
### 参数

1. value - (*mixed*) 将被封装的对象

### 返回值

* (*function*) 一个能返回给定对象的函数

### 示例:

	myLink.addEvent('click', $lambda(false)); //禁止myLink的点击
	
	//等价于:
	myLink.addEvent('click', function(){
		return false;
	});
	

函数: $extend {#extend}
---------------------------

将第二个参数对象的所有属性复制到第一个参数对象中.


### 语法:

	$extend(original, extended);

### 参数:

1. original - (*object*) 目标对象
2. extended - (*object*) 源对象

### 返回值:

* (*object*) 复制属性后的第一个参数对象

### 示例:

#### 常规用法:

	var firstObj = {
		'name': 'John',
		'lastName': 'Doe'
	};
	
	var secondObj = {
		'age': '20',
		'sex': 'male',
		'lastName': 'Dorian'
	};
	
	$extend(firstObj, secondObj);
	
	/*firstObj变为: 
	{ 
		'name': 'John', 
		'lastName': 'Dorian', 
		'age': '20', 
		'sex': 'male' 
	}
	*/

#### 特殊用法:
	
	myObject.extend = $extend;
	myObject.extend(otherObject);


函数: $merge {#merge}
-------------------------

合并一组对象生成新对象

### 语法:

	var merged = $merge(obj1, obj2[, obj3[, ...]]);

### 参数:

1. (objects) 任意数量的对象

### 返回值:

* (*object*) 合并生成的新对象

### 示例:

	var obj1 = {a: 0, b: 1};
	var obj2 = {c: 2, d: 3};
	var obj3 = {a: 4, d: 5};
	var merged = $merge(obj1, obj2, obj3); //返回新对象: {a: 4, b: 1, c: 2, d: 5}

	var nestedObj1 = {a: {b: 1, c: 1}};
	var nestedObj2 = {a: {b: 2}};
	var nested = $merge(nestedObj1, nestedObj2); //返回新对象: {a: {b: 2, c: 1}}


函数: $each {#each}
-----------------------

迭代数组(包括非常规数组,如由内建的getElementsByTagName方法返回的集合对象, arguments对象, 或Ojbect对象)

### 语法:

	$each(iterable, fn[, bind]);

### 参数:

1. iterable - (*object* or *array*) 被迭代的对象
2. fn       - (*function*) 迭代过程中对每个迭代元素进行处理的函数
3. bind     - (*object*, 可选) 迭代函数中'this'所应用的对象. 详见 [Function:bind][].

#### 参数详解: fn

##### 语法:

	fn(item, index, object)

##### 参数:

1. item   - (*mixed*)  当前迭代项
2. index  - (*number*) 当前迭代项的索引.如果迭代对象是一个Oject对象, 则是对象的属性名
3. object - (*mixed*)  迭代对象

### 示例:

#### 迭代数组:

	$each(['Sun','Mon','Tue'], function(day, index){
		alert('name:' + day + ', index: ' + index);
	});
	//显示 "name: Sun, index: 0", "name: Mon, index: 1" 等...


#### 迭代对象:

	$each({
		first: "Sunday", 
		second: "Monday", 
		third: "Tuesday"
	}, 
	function(value, key){
		alert("The " + key + " day of the week is " + value);
	});
	//显示 "The first day of the week is Sunday", "The second day of the week is Monday" 等...


函数: $pick {#pick}
-----------------------

返回参数列表中第一个非未定义的项; 如果全部未定义,则返回null

### 语法:

	var picked = $pick(var1[, var2[, var3[, ...]]]);

### 参数:

* (*mixed*) 任意个数的参数

### 返回值:

* (*mixed*) 第一个非未定义的项
* (*false*) 如果都是null或undefined, 则返回null

### 示例:

	function say(infoMessage, errorMessage){
		alert($pick(errorMessage, infoMessage, 'There was no message supplied.'));
	}
	
	say(); //显示 "There was no message supplied."
    say("This is an info message."); //显示 "This is an info message."
    say("This message will be ignored.", "This is the error message."); //显示 "This is the error message."



函数: $random {#random}
---------------------------

返回指定区间内的一个随机整数

### 语法:

	var random = $random(min, max);

### 参数:

1. min - (*number*) 下限(包括)
2. max - (*number*) 上限(包括)

### 返回值:

* (*number*) 给出区间范围内的一个随机整数

### 示例:

	alert($random(5, 20)); //显示: 5~20之间的一个随机整数



函数: $splat {#splat}
-------------------------

把传入的参数包装成一个数组

### 语法:

	var splatted = $splat(obj);

### 参数:

1. obj - (*mixed*) 任意类型的变量

### 返回值:

* (*array*) 如果传入的参数是个数组,那么返回该数组; 否则,返回一个包含传入参数的数组

### 示例:

	$splat('hello'); //返回 ['hello']
	$splat(['a', 'b', 'c']); //原样返回 ['a', 'b', 'c']



函数: $time {#time}
-----------------------

返回当前时间戳

### 语法:

	var time = $time();

### 返回值:

* (*number*) - 当前时间戳



函数: $try {#try}
---------------------

尝试执行给出的一组函数, 并返回第一个执行成功的函数的返回值; 

如果一个都没执行成功,则返回null

### 语法:

	$try(fn[, fn, fn, fn, ...]);

### 参数:

* fn   - (*function*) 将被执行的函数

### 返回值:

* (*mixed*) 返回第一个执行成功的函数的返回值
* (*null*)  如果一个都没执行成功,则返回`null`

### 示例:

	var result = $try(function(){
		return some.made.up.object;
	}, function(){
		return jibberish.that.doesnt.exists;
	}, function(){
		return false;
	});
	//返回false
	
	var failure, success;
	
	$try(function(){
		some.made.up.object = 'something';
		success = true;
	}, function(){
		failure = true;
	});
	
	if (success) {
		alert('yey!');
	}


函数: $type {#type}
-----------------------

检测传入参数的类型

### 语法:

	$type(obj);

### 参数:

1. obj - (*object*) 目标检测对象

### 返回值:

* 'element'    - (*string*) DOM元素节点
* 'textnode'   - (*string*) DOM文本节点
* 'whitespace' - (*string*) DOM空白节点
* 'arguments'  - (*string*) arguments
* 'array'      - (*string*) 数组
* 'object'     - (*string*) Object对象
* 'string'     - (*string*) 字符串
* 'number'     - (*string*) 数字
* 'date'       - (*string*) 日期对象
* 'boolean'    - (*string*) 布尔值
* 'function'   - (*string*) 函数对象
* 'regexp'     - (*string*) 正则表达式对象
* 'class'      - (*string*) Class (由new Class创建, 或由其他Class对象扩展而来).
* 'collection' - (*string*) 原生htmlelements集合, 如由方法childNodes, getElementsByTagName等获取到的结果
* 'window'     - (*string*) window
* 'document'   - (*string*) document
* false        - (*boolean*) undefined, null, NaN 或以上列出的类型都不是

### 示例:

	var myString = 'hello';
	$type(myString); //返回 "string".


[Hash]: /Native/Hash
[Array]: /Native/Array
[Function:bind]: /Native/Function/#Function:bind
[Function:delay]: /Native/Function/#Function:delay
[Function:periodical]: /Native/Function/#Function:periodical