6. 标准库

WTCD 提供一系列标准库用来做一些正常做不到或是即使做到了也非常复杂的操作。

6.1 list*

6.1.1 listSet

接受 3 个参数：list sourceList，number index，任意 value。

返回一个列表，返回的列表是 sourceList 中 index 被替换为 value 后的列表。该函数不会修改 sourceList。

listSet::[[ 0 1 2 3 4 5 ] 3 "Nice"] == [ 0 1 2 "Nice" 4 5 ]

6.1.2 listForEach

接受 2 个参数：list targetList，function fn。

对 targetList 中每一项运行 fn。fn 的第一个参数是这一项的值，第二个参数是这一项的下标。

declare number contentSum = 0
declare number indexSum = 0
listForEach::[[ 1 2 3 4 100 ] function[number item number index] {
  contentSum += item
  indexSum += index
}]
contentSum // 110
indexSum // 10

6.1.3 listMap

接受 2 个参数：list targetList，function fn。

对 targetList 中每一项运行 fn。fn 的第一个参数是这一项的值，第二个参数是这一项的下标。然后，将所有 fn 的运行返回值合在一起，形成一个新的列表并返回。

listMap::[[ 0 1 2 4 20 ] function[number item] item * item] == [ 0 1 4 16 400 ]

6.1.4 listCreateFilled

接受 1 - 2 个参数：number count，任意 value = null。

创建一个列表，这个列表有 count 个元素，每个元素的值都是 value。

listCreateFilled::[5 8] == [ 8 8 8 8 8 ]

6.1.5 listChunk

接受 2 个参数：list targetList，number chunkSize。

将 targetList 分成若干个列表，每个列表的长度为 chunkSize。

listChunk::[[ 1 2 3 4 5 6 7 8 9 10 ] 3 ] == [ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 9 ] [ 10 ] ]

6.1.6 listFilter

接受 2 个参数：list targetList，function fn。

对 targetList 中每一项运行 fn。fn 的第一个参数是这一项的值，第二个参数是这一项的下标，并要求返回一个布尔值。然后，将所有返回 true 的项目合在一起形成一个新的列表并返回。

listFilter::[[ 1 2 3 4 5 6 7 8 ] function[number a] a % 2 == 0] == [ 2 4 6 8 ]

6.1.7 listSplice

接受 3 - 4 个参数：list source，number start，number length，list newItems = []。

从 source 的 index = start 的元素开始，删除 length 个元素，并用 newItems 中的元素代替。返回修改后的列表。（不会修改原始列表）

listSplice::[[ 0 1 2 3 ] 1 2] == [ 0 3 ]
listSplice::[[ 0 1 2 3 ] 1 2 [ "Wow1" "Wow2" ]] == [ 0 "Wow1" "Wow2" 3]

6.1.8 listSlice

接受 2 - 3 个参数：list source，number start，number end = listLength::[source]。

复制从 source 的 index = start（含）开始到 index = end（不含）的元素。

    assert::[listSlice::[[ 0 1 2 3 4 5 ] 2] == [ 2 3 4 5 ]]
    assert::[listSlice::[[ 0 1 2 3 4 5 ] 2 4] == [ 2 3 ]]

6.1.9 listLength

接受 1 个参数：list targetList。

返回 targetList 的元素数量。

listLength::[[ 0 1 2 3 4 ]] == 5

6.1.10 listIndexOf

接受 2 个参数：list targetList，target。

找 targetList 中第一个 == target 的元素，返回其 index。若无法找到，返回 -1。

assert::[listIndexOf::[[ 0 1 2 3 ] 2] == 2]
assert::[listIndexOf::[[ 0 1 2 3 ] 4] == -1]

6.1.11 listIncludes

接受 2 个参数：list targetList，target。

判断 targetList 中是否有 == target 的元素。

assert::[listIncludes::[[ 0 1 2 3 ] 2] == true]
assert::[listIncludes::[[ 0 1 2 3 ] 4] == false]

6.1.12 listFindIndex

接受 2 个参数：list targetList，function predicate。

对 targetList 中每一项依次运行 fn。fn 的第一个参数是这一项的值，第二个参数是这一项的下标，并要求返回一个布尔值。当任意一个 predicate 返回 true 时，返回该项的 index。如果没有一项能使 predicate 返回 true，否则返回 -1。

assert::[listFindIndex::[[ 1 3 5 8 9 11 14 ] $[item] item % 2 == 0] == 3]
assert::[listFindIndex::[[ 1 3 5 8 9 11 14 ] $[item index] index == 4] == 4]
assert::[listFindIndex::[[ 1 3 5 8 9 11 14 ] $[item] false] == -1]

6.2 math*

6.2.1 mathMin

接受 1 个及以上的数字。返回其中最小的值。

mathMin::[10 1 2 3 4] == 1

6.2.2 mathMax

接受 1 个及以上的数字。返回其中最大的值。

mathMax::[1 2 3 4 0] == 4

6.2.3 mathFloor

接受 1 个参数：number input。返回小于等于 input 的最大整数。

mathFloor::[11.8] == 11
mathFloor::[-11.8] == -12

6.2.4 mathCeil

接受 1 个参数：number input。返回大于于等于 input 的最小整数。

mathFloor::[11.8] == 12
mathFloor::[-11.8] == -11

6.3 string*

6.3.1 stringLength

接受 1 个参数：string input。返回 input 的长度。

stringLength::["Hello~"] == 6

6.3.2 stringFormatNumberFixed

接受 1 个参数：number target，number digits = 0。返回将 target 四舍五入到 digits 位小数后的字符串。

stringFormatNumberFixed::[1.235 2] == "1.24"

6.3.3 stringFormatNumberPrecision

接受 2 个参数：number target，number digits。返回将 target 四舍五入到保留 digits 位数字后的字符串。

stringFormatNumberPrecision::[1.235 2] == "1.2"
stringFormatNumberPrecision::[1234 2] == "1.2e+3"

6.3.4 stringSplit

接受 2 个参数：string str，string separator。返回用 separator 分割 str 产生的列表。

stringSplit::["a,b" ","] == ["a" "b"]

6.3.5 stringSubByLength

接受 2 - 3 个参数：string str，number startIndex，number length = 剩余长度。

返回 str 从 startIndex（含）开始 length（含）个字符的子串。

6.3.6 stringSubByIndex

接受 2 - 3 个参数：string str，number startIndex，number endIndex = 字符串长度。

返回 str 从 startIndex（含）开始直到 endIndex（不含）的子串。

6.4 random*

6.4.1 random

接受 0 - 2 个参数：number low = 0，number high = 1。

返回一个大于等于 low，小于 high 的随机浮点数。

6.4.2 randomInt

接受 0 - 2 个参数：number low = 0，number high = 1。

返回一个大于等于 low，小于 high 的随机整数。

6.4.3 randomBoolean

接受 0 - 1 个参数：boolean trueChance = 0.5。

返回一个有 trueChance 为 true 的随机布尔值。

6.4.4 randomBiased

实验性，尚未确认

接受 0 - 4 个参数：number low = 0，number high = 1，number bias = (low + high) / 2，number influence = 3。

返回一个大于等于 low，小于 high，偏向于 bias，影响系数为 influence 的随机浮点数。

6.5 content*

6.5.1 contentAddParagraph

接受 1 个参数：string content。

创建并插入一个内容为 content 的自然段。

6.5.2 contentAddImage

接受 1 个参数：string src。

创建并插入一个地址为 src 的图片。

6.5.3 contentAddUnorderedList

接受任意数量个字符串参数。

然后用它们来产生并插入一个无序列表。

6.5.4 contentAddOrderedList

接受任意数量个字符串参数。

然后用它们来产生并插入一个有序列表。

6.5.5 contentAddHeader

接受 1 - 2 个参数：string content，number level = 1。

创建并插入一个级别为 level，内容为 content 的标题。

6.5.6 contentAddTable

接受 1 个及以上的参数。每一个参数都是长度相同的列表。每一个列表对应表格的一行。第一行作为表头。

contentAddTable::[
  [ "名字" "年龄" "性别" ]
  [ "琳"   "18"   "女"   ]
  [ "czp"  "？"   "男"   ]
]

6.6.6 contentAddHorizontalRule

创建并插入一条水平分割线。

6.6 Debug

6.6.1 print

接受任意数量个参数。将这些值打印到浏览器控制台。

6.6.2 assert

接受 1 个参数：boolean isOk。

如果 isOk 不是 true，立刻产生一个异常（中断执行）。

6.6.3 assertError

接受 1 个参数：function fn。

调用 fn。如果 fn 没有产生 WTCD 错误，则产生一个异常。（断言这个提供的函数在运行时会报错。）

6.6.4 timeStart

接受 0 - 1 个参数：string timerName = "default"。

启动一个名为 timerName 的计时器。

6.6.5 timeEnd

接受 0 - 1 个参数：string timerName = "default"。

结束名为 timerName 的计时器，并将计时结果打印到浏览器控制台。

6.7 reader*

6.7.1 readerSetPinned

接受 1 个参数：function pinnedFunction。

设置 pinnedFunction 为当前的常驻函数。常驻函数是指在每次需要用户做出选择的时候被调用的函数。在这个函数内调用 content* 会把创建的内容添加到一个特殊的常驻区域。常驻区域的显示方式则是由具体的阅读器决定的。

6.7.2 readerUnsetPinned

不接受参数。取消当前常驻函数。

6.7.3 readerSetStateDesc

接受 1 个参数：string stateDesc。

将当前的状态描述文本设置为 stateDesc。状态描述文本通常被用在支持多存档的阅读器的存档选择界面中来帮助区分存档。

6.7.4 readerUnsetStateDesc

不接受参数。取消当前状态描述文本。

6.8 canvas*

6.8.1 canvasCreate

接受 3 个参数：string id，number width，number height。

创建一个 ID 为 id，宽度为 width，高度为 height 的画布。需要注意的是，这个画布是不会显示出来的。

如果需要显示这个画布，则需要使用 canvasOutput。

6.8.2 canvasOutput

接受 1 个参数：string id。

将 ID 为 id 的画布显示出来。需要注意的是，这个画布一旦被显示就会被克隆。因此之后对该画布的修改不会影响到已经显示出来的版本。

6.8.3 canvasClear

接受 1 个参数：string id。

将 ID 为 id 的画布清空。

6.8.4 canvasPutImage

接受 4 - 6 个参数：string id，string path，number x，number y，number width = -1，number height = -1。

将位于 path 的图片绘制到 ID 为 id 的画布上。使用 x 和 y 可以控制绘制的位置（左上角）。使用 width 和 height 可以控制绘制出来的尺寸。如果忽略，那么就会使用图片的原始尺寸。

需要注意的是，width 和 height 要么同时提供，要么都不提供。不可以只提供一个。

6.8.5 canvasPutImagePart

接受 8 - 10 个参数：string id，string path，number sourceX，number sourceY，number sourceWidth，number sourceHeight，number destX，number destY，number destWidth = -1，number destHeight = -1。

将位于 path 的图片的一部分绘制到 ID 为 id 的画布上。使用 sourceX，sourceY，sourceWidth，sourceHeight 可以控制需要绘制的部分在来源图片的位置。使用 destX 和 destY 可以控制在画布的位置（左上角）。使用 destWidth 和 destHeight 可以控制绘制出来的尺寸。如果忽略，那么就会使用图片的来源部分的尺寸。

需要注意的是，destWidth 和 destHeight 要么同时提供，要么都不提供。不可以只提供一个。

6.8.6 canvasSetFont

接受 3 个参数：string id，number size，string fontIdentifier。

设置 ID 为 id 的画布的字体为尺寸是 sizepx，类型是 fontIdentifier 的字体。

fontIdentifier 的解释方法由使用的 WTCD 阅读器指定。在《可穿戴科技》中，这个 fontIdentifier 的值为 googleFonts:<在 Google Fonts 上的字体名>。例如：googleFonts:ZCOOL KuaiLe。

6.8.7 canvasSetFillStyle

接受 2 个参数：string id，string fillStyle。

设置 ID 为 id 的画布的填充方式为 fillStyle。

6.8.8 canvasFillText

接受 4 - 6 个参数：string id，string text，number x，number y，string hAlign = "start"，string vAlign = "alphabetic"。

在 ID 为 id 的画布的位于（x, y）的位置，绘制以 hAlign 横向对齐，以 vAlign 纵向对齐的文本 text。

请使用 canvasSetFont 来选择字体，使用 canvasSetFillStyle 来选择填充方式。

hAlign 可采取的值可以在这里找到。

vAlign 可采取的值可以在这里找到。

6.8.9 canvasFillRect

接受 5 个参数：string id，number x，number y，number width，number height。

在 ID 为 id 的画布的位于（x, y）的位置绘制一个 widthpx x heightpx 的长方形。

6.8.10 canvasSetStrokeStyle

接受 2 个参数：string id，string strokeStyle。

设置 ID 为 id 的画布的描线方式为 strokeStyle。

6.8.11 canvasSetLineWidth

接受 2 个参数：string id，number lineWidth。

设置 ID 为 id 的画布的描线粗细为 lineWidthpx。

6.8.12 canvasStrokeText

接受 4 - 6 个参数：string id，string text，number x，number y，string hAlign = "start"，string vAlign = "alphabetic"。

类似 canvasFillText，但是只是描边。所以请使用 canvasSetStrokeStyle 来选择描边方式。