原文:http://www.phpfans.net/manu/Prototype/prototype/api/hash.htm
Hash
Hash 可以看作是一個 關聯數組,它對每一個值都綁定了一個唯一的鍵(值并不必須是唯一的),
然而,它不能保證迭代時元素的順序始終一致。因為 JavaScript 程序語言的特性,每個對象實際上都是一個 hash,但是,本篇所述的
Hash
增加了許多方法,讓你能夠輕松地枚舉鍵和值、迭代“鍵/值”對、 合并兩個 hash、將 hash 編碼成為一個查詢字符串等等。
創建一個 hash
構造一個 Hash
實例有兩種方法:第一種是使用 new
關鍵字實例化一個 JavaScript
對象(new Hash(obj)
)。第二種是使用 $H
函數。傳遞一個 JavaScript 對象或是一個 Hash 給 $H
,$H
函數會克隆它們,并不會對原始對象造成任何影響。
對于上述兩種構造方法,你也可以不傳遞任何參數而調用它們。它們將返回一個空的 hash。
在 Prototype 1.6 中的后向兼容性變更
后向兼容性變更 - 雖然新版本的 Hash 與之前的版本具有相同的目標,但是新版本的 Hash 不再兼容先前版本的 Hash 類型。
現在,不能再通過 Hash
實例的屬性來訪問“鍵/值”對,它們是私有的,這是為了防止在 Hash
實例上定義的屬性和混入的方法引起鍵的沖突。這意味著你必須使用 Hash#get(key)、 Hash#set(key, value) 和 Hash#unset(key) 實例方法來訪問、設置或刪除“鍵/值”對。例如:
var myhash = new Hash();
// 老的 API --> 新的 API
myhash.name = "Bob"; --> myhash.set('name', 'Bob');
myhash.name; --> myhash.get('name');
delete myhash.name; --> myhash.unset('name');
你也應該了解關于 Hash API 的其它變更:
-
$H(object)
快捷方法現在完全等同于new Hash(object)
。無論參數是一個對象還是另一個Hash
,它們都返回一個新的對象。 -
Hash#merge
返回一個新的Hash
,而不再是對調用該方法的實例對象進行修改。 -
Hash#update
是Hash#merge
的一個破壞性版本,它會修改調用該方法的實例對象。 -
Hash#clone
返回一個新的當前 Hash 對象的克隆實例。 -
Hash#toObject
返回一個當前 Hash 內部對象的復本。
譯注:Prototype 使用了一個單獨的內部對象來存儲“鍵/值”對。 -
Hash.toQueryString
現在是Object.toQueryString
的一個別名。(Hash.toQueryString
已不推薦使用,在將來的 Prototype 版本中,這個方法將會被移除。) -
Hash#remove
已經被Hash#unset
取代。 -
Hash.toJSON
已經被Object.toJSON
或Hash#toJSON
實例方法取代。
注意,對于 Prototype 的早期版本(< 1.6)
傳遞一個 hash 到 $H
并不會克隆它。
因為混入了 Enumerable,同時,它還有自己的方法,所以
Hash
不是所有的名稱都可以用作“鍵”的。如果新增的鍵的名稱與 Hash
的任何一個方法同名,則那個方法不能再被調用。 即使因為你不需要調用那個方法而僥幸獲得成功,但仍然會有問題:
var h = new Hash({ ... });
h['each'] = 'my own stuff';
h.map();
// -> 錯誤,因為 'each' 不再是一個函數
在 Enumerable 中,最重要的方法是 each, 因為幾乎每一個其它的方法都需要它——覆蓋它將導致我們的 hash
實例成為一個廢物。你也不能抱著僥幸心理使用 _each
,因為它也是 Enumerable
內部的一個重要方法。
方法
clone
1.6
clone() -> newHash
返回一個 hash 的克隆。
each
each(iterator) -> Hash
迭代處理 hash 中的“鍵/值”對。
get
1.6
get(key) -> value
返回 hash 指定鍵對應的值。
inspect
inspect() -> String
返回 hash 針對調試的字符串表現形式。
keys
keys() -> [String...]
返回一個數組,該數組包括 hash 中所有的鍵的名稱。
merge
1.6 改進
merge(object) -> newHash
將 object
和當前的 hash 實例合并,返回合并后的結果。在 v1.6.0 之前:
這是一個破壞性的方法(對象的值將會被增加到當前 hash 中)。從 v1.6.0 開始: 這不再是一個破壞性的方法(在合并之前,hash
已被克隆)。
remove
不推薦
remove(key) -> value
remove(key1, key2...) -> Array
從 hash 中移除指定的鍵,并返回被移除的鍵對應的值。從 v1.6.0 開始,該方法不可用。
set
1.6
set(key, value) -> value
將 hash 中 key
指定的鍵的值設置為
value
,返回所設置的值(value
)。
譯注:如果不存在指定的鍵,則新增。
toJSON
1.5.1
toJSON() -> String
返回一個 JSON 字符串。
toObject
1.6
toObject() -> Object
克隆 hash 內部的 Object
并返回。譯注:Hash
在內部使用一個單獨的 Object
保存“鍵/值”對。
toQueryString
1.6 改進
toQueryString() -> String
將一個 hash 轉換為 URL 編碼字符串形式。
unset
1.6
unset(key) -> value
刪除 hash 中的鍵,并返回鍵對應的值。
update
1.6
update(object) -> Hash
使用參數 object
包含的“鍵/值”對更新當前 hash。原始的 hash 對象將會被修改。
values
values() -> Array
返回一個數組,該數組是 hash 中所有的值的集合。