標準函數庫是擴充 WMLScript 語言能力的關鍵機制。所有函數庫都必須遵守 WMLScript 的既定規則,本文把 Lang、Float 與 String 三個核心函數庫逐一整理,方便查閱。
函數庫在定義程式的參數與回傳值時,使用以下五種資料格式:Boolean、Integer、Float、String、Invalid。若某參數同時接受整數與浮點數,會以 number 標記;若接受任何格式,則標記為 any。
錯誤處理方式與語言本身一致:傳入 invalid 參數會得到 invalid 回傳值;參數無法轉換為所需格式時同樣回傳 invalid;與程式相關的錯誤則回傳對應的錯誤碼,具體數值由每支程式自行定義。
這個函數庫與 WMLScript 語言核心關係最為密切。
回傳數值的絕對值。傳入整數回傳整數,傳入浮點數回傳浮點數。回傳值為數字或 invalid。
var a = -3;
var b = Lang.abs(a); // b = 3
min 回傳兩者中的較小值,max 回傳較大值。回傳值的格式與所選中的數值相同,比較前會依 WMLScript 的整數/浮點數轉換法則確定資料格式。
var d = Lang.min(45, 76.3); // d = 45(整數)
var e = Lang.max(45, 76.3); // e = 76.3(浮點數)
把字串解析為整數。若第一個字元不是正負號或十進位數字,解析立即結束。合法的整數語法由 WMLScript 數值字串文法界定。
var i = Lang.parseInt("1234"); // i = 1234
var j = Lang.parseInt("100 m/s"); // j = 100
把字串解析為浮點數,規則與 parseInt 類似,一旦首字元無法構成合法的浮點數表示,解析即結束;解析失敗回傳 invalid。
var a = Lang.parseFloat("123.7 Hz"); // a = 123.7
var b = Lang.parseFloat("7.34e2 Hz"); // b = 734
var c = Lang.parseFloat("-1.c"); // c = -0.1
var d = Lang.parseFloat("100"); // d = 100.0
var e = Lang.parseFloat("Number:5.5"); // e = invalid
var f = Lang.parseFloat("7.3e meters"); // f = invalid
若 value 能被 parseInt / parseFloat 成功轉換,回傳布林值 true,否則回傳 false。
var a = Lang.isInt("-123"); // true
var b = Lang.isInt("123.33"); // true
var c = Lang.isInt("string"); // false
var d = Lang.isInt("#123"); // false
var e = Lang.isInt(invalid); // invalid
分別回傳系統支援的最大與最小整數值,即 2147483647 與 −2147483648,無參數。
若執行環境支援浮點數則回傳 true,否則回傳 false。可用來在執行期偵測裝置能力。
var floatsSupported = Lang.float();
結束 WMLScript 位元碼的解譯,把控制權交還呼叫解譯器的一方,並回傳指定的 value。適合用作一般性的正常結束。
Lang.exit("Value:" + myVal); // 回傳字串
Lang.exit(invalid); // 回傳 invalid
不正常地中止解譯並回傳錯誤描述,供呼叫端偵測嚴重錯誤。若 errorDescription 為 invalid,則以字串 "invalid" 代替。
Lang.abort("Error:" + errVal);
回傳一個大於或等於 0、且小於 value 的隨機整數。value 為 0 時回傳 0;value 小於 0 或非整數時回傳 invalid。
var a = 10;
var b = Lang.random(5) * a; // b 落在 0 到 45 之間
var c = Lang.random("string"); // c = invalid
初始化亂數序列並回傳空字串。value 為 0 或正整數時以其作為亂數種子,否則採用隨機初始值;若傳入浮點數,會先用 Float.int() 取整。
var a = Lang.seed(123); // a = ""
var b = Lang.random(20); // b 落在 0 到 19
var c = Lang.seed("seed"); // c = invalid,亂數種子維持不變
回傳解譯器支援的字元集,以 IANA 設定的 MIB Enum 整數表示。
var charset = Lang.characterSet(); // 4 代表 Latin-1
收錄常用的浮點數運算程式。
回傳數值的整數部分,直接截去小數而無條件捨去。
var b = Float.int(3.14); // b = 3
var c = Float.int(-2.8); // c = -2
floor 回傳最接近但不更大於 value 的整數;ceil 回傳最接近但不更小於 value 的整數。若 value 本身已是整數,結果即為該值。
var b = Float.floor(-2.8); // b = -3
var c = Float.ceil(-2.8); // c = -2
回傳 x 的 y 次方。若 x 為負數,y 必須為整數;x 等於 0 而 y 小於 0,或 x 小於 0 而 y 非整數,皆回傳 invalid。
var b = Float.pow(3, 2); // b = 9
回傳最接近 value 的整數。若兩個整數與 value 距離相等,取較大者。
var a = Float.round(3.5); // a = 4
var b = Float.round(-3.5); // b = -3
var c = Float.round(0.5); // c = 1
var d = Float.round(-0.5); // d = 0
回傳 value 的平方根近似值,value 為負數時回傳 invalid。
var b = Float.sqrt(4); // b = 2.0
var c = Float.sqrt(5); // c ≈ 2.2360679775
回傳 IEEE 754 單精度格式中可表示的最大與最小正規化浮點數,分別約為 3.40282347E+38 與 1.17549435E-38。
字串可視為字元陣列,每個字元有對應索引,第一個字元的索引為 0,長度即字元總數。分隔字元可用來切分元素,索引同樣從 0 起算;字元本身不能作為分隔符。可視為空白的字元包含 TAB、VT(垂直定位)、FF(換頁)、SP(空格)、LF(換行)與 CR(歸位)。
回傳字串長度。
var b = String.length("ABC"); // b = 3
var c = String.length(""); // c = 0
var d = String.length(342); // d = 3
長度為 0 時回傳 true,否則 false。
var c = String.isEmpty("Hello"); // false
var d = String.isEmpty(""); // true
var e = String.isEmpty(true); // false
回傳指定索引處的字元。索引超出範圍時回傳空字串。
var b = String.charAt("My name is Joe", 0); // b = "M"
var c = String.charAt("My name is Joe", 100); // c = ""
var d = String.charAt(34.0, 0); // d = "3"
從 startIndex 起擷取 length 個字元組成新字串。startIndex 小於 0 時以 0 計算;length 超出剩餘字元數時以剩餘數量替代;若傳入浮點數,會先用 Float.int() 取整。startIndex 大於最後索引或 length 小於等於 0 時回傳空字串。
var b = String.subString("ABCD", 1, 2); // b = "BC"
var c = String.subString("ABCD", 2, 5); // c = "CD"
var d = String.subString(1234, 0, 2); // d = "12"
回傳 substring 在 string 中首次出現的索引,找不到回傳 −1。比對為大小寫相不相等即判定相符。
var b = String.find("abcde", "cd"); // b = 2
var c = String.find("abcde", "gz"); // c = -1
var d = String.find(34, "3"); // d = 0
以 newSubString 取代 string 中所有符合的 oldSubString,回傳新字串。
var c = String.replace("Hello Joe. What is up Joe?", "Joe", "Don");
// c = "Hello Don. What is up Don?"
回傳以 separator 切分後的元素數目。空字串也是有效元素,因此回傳值永不小於 1;separator 為空字串時回傳 invalid。
var b = String.elements("My name is Joe;Age 50", " "); // b = 6
var c = String.elements("My name is Joe;Age 50", ";"); // c = 2
var d = String.elements("", ";"); // d = 1
var e = String.elements(";", ";"); // e = 2
取得第 index 個元素。index 小於 0 回傳第一個元素,大於元素總數回傳最後一個,字串為空時回傳空字串,浮點索引先取整。
var b = String.elementAt("My name is Joe;Age 50", 0, ";"); // b = "My name is Joe"
var c = String.elementAt("My name is Joe;Age 50", 1, ";"); // c = "Age 50"
移除指定索引的元素並回傳新字串。索引邊界處理與 elementAt 相同。
var c = String.removeAt(" A A;B C D", 1, ";"); // c = " A A"
var d = String.removeAt(" A A;B C D", 0, ";"); // d = "B C D"
以 element 取代指定索引處的元素並回傳新字串。
var d = String.replaceAt("B C; E", "A", 0, ";"); // d = "A C;E"
var e = String.replaceAt("B C; E", "F", 1, ";"); // e = "B C;F"
在指定索引處插入元素與對應分隔符。index 小於 0 以 0 計算,大於元素總數時附加到尾端,字串為空時回傳只含該元素的新字串。
var b = String.insertAt("B C; E", "A", 0, ";"); // b = "A;B C; E"
var c = String.insertAt("B C; E", "X", 3, ";"); // c = "B C; E;X"
var d = String.insertAt("B C; E", "D", 1, ";"); // d = "B C;D; E"
把字串中連續的多個空白壓縮為單一空白。
刪除字串開頭與結尾的空白,中間內容保持不變。
依字元碼比較兩個字串的語彙關係:string1 小於 string2 回傳 −1,兩者相等回傳 0,string1 大於 string2 回傳 1。
var c = String.compare("Hello", "Hello"); // c = 0
var d = String.compare("Bye", "Jon"); // d = -1
var e = String.compare("Jon", "Bye"); // e = 1
回傳表示該值的字串,轉換規則與語言內建一致,只有 invalid 會被轉為字串 "invalid"。
var a = String.toString(12); // a = "12"
var b = String.toString(true); // b = "true"
依格式字串把 value 轉為格式化字串。格式語法為 [width][.precision]type。
d 而言代表最少顯示位數,不足時左側補 0;對 f 而言代表小數位數,會四捨五入,預設為 6;對 s 而言代表最大顯示字元數。d、浮點數 f 還是字串 s。格式字串中若要顯示百分比符號,需寫成 %%。無效格式會回傳 invalid。
var a = 45; var d = 1.2345678; var c = "now";
var e = String.format("e:%6d", a); // e = "e: 45"
var f = String.format("%6.4d", -45); // f = "-0045"
var g = String.format("Do it %s", c); // g = "Do it now"
var h = String.format("%10.2f%%", d); // h = " 1.23%"
var i = String.format("%.0d", 0); // i = ""