6. 标准库

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

6.1 list*

6.1.1 listSet

接受 3 个参数:list sourceListnumber index任意 value

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

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

6.1.2 listForEach

接受 2 个参数:list targetListfunction fn

targetList 中每一项运行 fnfn 的第一个参数是这一项的值,第二个参数是这一项的下标。

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 targetListfunction fn

targetList 中每一项运行 fnfn 的第一个参数是这一项的值,第二个参数是这一项的下标。然后,将所有 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 targetListnumber 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 targetListfunction fn

targetList 中每一项运行 fnfn 的第一个参数是这一项的值,第二个参数是这一项的下标,并要求返回一个布尔值。然后,将所有返回 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 sourcenumber startnumber lengthlist 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 sourcenumber startnumber 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 targetListtarget

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 targetListtarget

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

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

6.1.12 listFindIndex

接受 2 个参数:list targetListfunction predicate

targetList 中每一项依次运行 fnfn 的第一个参数是这一项的值,第二个参数是这一项的下标,并要求返回一个布尔值。当任意一个 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 targetnumber digits = 0。返回将 target 四舍五入到 digits 位小数后的字符串。

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

6.3.3 stringFormatNumberPrecision

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

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

6.3.4 stringSplit

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

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

6.3.5 stringSubByLength

接受 2 - 3 个参数:string strnumber startIndexnumber length = 剩余长度

返回 strstartIndex(含)开始 length(含)个字符的子串。

6.3.6 stringSubByIndex

接受 2 - 3 个参数:string strnumber startIndexnumber endIndex = 字符串长度

返回 strstartIndex(含)开始直到 endIndex(不含)的子串。

6.4 random*

6.4.1 random

接受 0 - 2 个参数:number low = 0number high = 1

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

6.4.2 randomInt

接受 0 - 2 个参数:number low = 0number high = 1

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

6.4.3 randomBoolean

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

返回一个有 trueChancetrue 的随机布尔值。

6.4.4 randomBiased

实验性,尚未确认

接受 0 - 4 个参数:number low = 0number high = 1number bias = (low + high) / 2number 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 contentnumber 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 idnumber widthnumber 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 idstring pathnumber xnumber ynumber width = -1number height = -1

将位于 path 的图片绘制到 ID 为 id 的画布上。使用 xy 可以控制绘制的位置(左上角)。使用 widthheight 可以控制绘制出来的尺寸。如果忽略,那么就会使用图片的原始尺寸。

需要注意的是,widthheight 要么同时提供,要么都不提供。不可以只提供一个。

6.8.5 canvasPutImagePart

接受 8 - 10 个参数:string idstring pathnumber sourceXnumber sourceYnumber sourceWidthnumber sourceHeightnumber destXnumber destYnumber destWidth = -1number destHeight = -1

将位于 path 的图片的一部分绘制到 ID 为 id 的画布上。使用 sourceXsourceYsourceWidthsourceHeight 可以控制需要绘制的部分在来源图片的位置。使用 destXdestY 可以控制在画布的位置(左上角)。使用 destWidthdestHeight 可以控制绘制出来的尺寸。如果忽略,那么就会使用图片的来源部分的尺寸。

需要注意的是,destWidthdestHeight 要么同时提供,要么都不提供。不可以只提供一个。

6.8.6 canvasSetFont

接受 3 个参数:string idnumber sizestring fontIdentifier

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

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

6.8.7 canvasSetFillStyle

接受 2 个参数:string idstring fillStyle

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

6.8.8 canvasFillText

接受 4 - 6 个参数:string idstring textnumber xnumber ystring hAlign = "start"string vAlign = "alphabetic"

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

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

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

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

6.8.9 canvasFillRect

接受 5 个参数:string idnumber xnumber ynumber widthnumber height

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

6.8.10 canvasSetStrokeStyle

接受 2 个参数:string idstring strokeStyle

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

6.8.11 canvasSetLineWidth

接受 2 个参数:string idnumber lineWidth

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

6.8.12 canvasStrokeText

接受 4 - 6 个参数:string idstring textnumber xnumber ystring hAlign = "start"string vAlign = "alphabetic"

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