尧图网站建设 
Quarkdown 集合索引访问函数 getat 全解析从签名、越界语义到链式调用实践【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdowngetat是 Quarkdown 标准库quarkdown-stdlib中用于从 Iterable 集合按索引取元素的函数它遵循 Quarkdown 特有的1-based 索引约定并内置越界兜底机制。本文以 quarkdown-quarkdoc 模块的 HTML→Markdown 文档转换测试资源getat.md为骨架结合 Collection.kt 的源码实现与 IterableTest.kt 的测试用例完整讲解getat的参数语义、越界处理、返回值类型以及如何通过函数调用链与其他集合操作组合帮助读者在 Quarkdown 文档与脚本中安全高效地访问集合元素。一、函数签名一次看清全部参数getat的 API 文档签名如下取自 getat.md.getat from:{IterableAny} \ index:{Int} \ orelse:{Dynamic DynamicValue(NOT_FOUND)} - Any该签名使用了反斜杠\进行行续接这是 Quarkdown 函数调用语法的一部分——当函数参数较多时在行尾加\即可换行继续书写参数列表编译器会消费反斜杠与换行符并忽略续行前的缩进参见 syntax-of-a-function-call.qd 中的Line continuation一节。按照 Quarkdown 的基本调用约定函数名以.开头每个参数用{}包裹形如.getat {collection} {index}。逐项解读签名中的三个要素返回值- Any返回集合中指定索引处的元素元素类型不受限制字符串、数字、布尔、嵌套集合等均可参数orelse带默认值orelse:{Dynamic DynamicValue(NOT_FOUND)}说明这是一个可选参数缺省时使用标准库中的NOT_FOUND哨兵值。二、参数详解from、index 与 orelse根据文档的 Parameters 小节三个参数的职责分别是参数类型含义默认值fromIterableAny从中取元素的集合必填indexInt要取的元素索引从 1 开始计数必填orelseDynamic索引越界时返回的兜底值未设置时返回false2.1 from接受任何可迭代值from参数的类型是IterableAny意味着凡是 Quarkdown 中可迭代的值都可以传入集合Collection普通 Markdown 列表自动转换为有序集合字典Dictionary当作键值对列表使用区间Range整数Range是合法的有序可迭代值Pair包含两个值的可迭代对象。关于哪些值属于 Iterable可进一步参考 iterable.qd 的说明。2.2 index1-based 索引是核心约定index参数最需要注意的一点是索引从 1 开始文档原文 (starting at 1)。也就是说getat中的索引1对应集合第一个元素2对应第二个依此类推。这一约定与多数编程语言包括 Quarkdown 底层实现的 Kotlin的 0-based 索引截然不同因此在底层实现中有一个显式的索引换算步骤详见第五节。2.3 orelse越界兜底值当index超出集合实际元素范围时getat不会报错而是返回orelse指定的值。这里文档描述与源码实现存在一处值得注意的细节参数文档KDoc描述为如果未设置返回false而签名中的默认值是DynamicValue(NOT_FOUND)即标准库定义的NOT_FOUND哨兵实际测试行为则是越界且未提供orelse时输出None见下节测试用例。NOT_FOUND的定义位于 Stdlib.kt其注释明确写着 Fallback value for non-existent elements in collections, dictionaries, and more取值解析为NoneValue——即 Quarkdown 的none值语义上代表不存在的元素与集合、字典等查找类函数的缺失语义保持一致。从源码结构看这是 KDoc 描述与默认值实现之间的历史性表述差异实际运行行为以测试为准无orelse时越界返回None。三、越界行为验证测试用例的实证getat的越界语义在 IterableTest.kt 中有两个直接对应的测试正常取值测试.var {abc} - A - B - C .abc::getat {2}执行结果渲染为pB/p——集合abc包含 A、B、C 三个元素索引21-based取到第二个元素B验证了 1-based 索引约定。越界测试.abc::getat {5}执行结果渲染为pspan classcodespan-contentcodeNone/code/span/p即在只有 3 个元素的集合上请求索引5返回none而不会抛出异常。此外OptionalityTest.kt 展示了getat与可选性处理函数组合的完整实战对集合[10, 20, 30].x::getat {2}::ifpresent {.1::sum {3}}::otherwise {No}输出23取到 20 后加 3而.x::getat {5}::ifpresent {.1::sum {3}}::otherwise {No}输出No越界得到 none走 otherwise 分支。这说明getat的返回值可以无缝接入ifpresent/otherwise这类存在性检查控制流实现安全的条件渲染。四、链式调用与其他集合操作自由组合文档明确指出getat是设计用于链式调用chaining的函数其链式签名如下IterableAny::getat index:{Int} \ orelse:{Dynamic} - Any链式调用的语法形式是.myiterable::operation即通过双冒号在集合值上直接调用操作参考 iterable.qd 与 syntax-of-a-function-call.qd 的 Chaining calls 章节。链式写法省略了from参数——集合值自身成为隐式的接收者只需给出index与可选的orelse。为什么要强调链式设计因为 Quarkdown 中集合操作都是不可变的任何操作都会产生新集合或新值绝不修改原始集合iterable.qd 明确说明 Operations are immutable and never modify the original iterable。这一特性使得任意长度的链式组合都是安全、可预测的。例如.foreach {.letters::prepended {A}::appended {D}} .1链式调用尤其适合在foreach循环、模板渲染等场景中把getat与size、sorted、reversed、first、last等同族操作全部定义在同一个 Collection.kt 文件中串联起来一步到位地完成取值 变换 输出。五、源码级原理1-based 索引到 Kotlin 的换算getat的底层实现位于 Collection.kt核心代码如下internal const val INDEX_STARTS_AT 1 private fun quarkdownIndexToKotlin(index: Int) index - INDEX_STARTS_AT QFunction Name(getat) LikelyChained fun collectionGet( Name(from) collection: IterableOutputValue*, index: Int, Name(orelse) fallback: DynamicValue DynamicValue(NOT_FOUND), ) nativeCollectionGet(quarkdownIndexToKotlin(index), collection, fallback)实现要点可以拆解为三层索引换算层quarkdownIndexToKotlin(index) index - 1。常量INDEX_STARTS_AT 1集中声明了Quarkdown 集合索引从 1 开始这一约定用户传入的 1-based 索引在这里统一转换为 Kotlin 的 0-based 索引。越界安全层nativeCollectionGet使用collection.toList().getOrNull(index) ?: fallback——getOrNull保证越界时返回 null 而非抛异常随后由?:兜底为fallback。这解释了为何getat天然对越界免疫。元数据层QFunction、Name(getat)、LikelyChained三个注解分别声明该函数是标准库导出的 Quarkdown 函数、对外名称为getat、且大概率会被链式调用。其中LikelyChained由 quarkdoc 模块的 LikelyChainedPageTransformer.kt 消费用于在生成的 API 文档中自动追加 Chaining 一节——这正是本文所依据的 getat.md 中链式签名部分的来源。同文件中的first、second、third、last等便捷函数也复用了nativeCollectionGet分别传入 0、1、2 等 Kotlin 原生索引与getat共享同一套越界兜底逻辑。六、文档从何而来quarkdoc 的 HTML→Markdown 转换值得说明的是本文讨论的 getat.md 并不是手写的说明文档而是 quarkdown-quarkdoc 模块中HTML→Markdown 文档转换功能的测试夹具它对应的源文件是同目录下的 getat.html一个由 Dokka 生成的带语法高亮标记的 API 页面。该转换由 HtmlToMarkdown.kt 实现测试见 HtmlToMarkdownTest.kt。其中名为stdlib page with wrapped signature keeps line breaks的测试专门验证getat这类**签名换行wrapped signature**页面在转换后仍能保留换行结构从而保证标准库函数的长签名在 Markdown 文档中清晰可读。换言之getat.md本身就是标准库函数文档生成流水线的一个端到端样例从 Kotlin 源码注解KDoc Name等→ Dokka HTML → 转换后的 Markdown 文档。七、最佳实践小结索引从 1 开始getat的索引是 1-based与底层 Kotlin 的 0-based 完全不同这是最容易踩的坑越界不必防御越界时返回orelse缺省为none不会中断文档编译可放心对动态长度的集合取值优先链式写法集合已确定时用.myiterable::getat {n}省略from代码更简洁需要显式指明来源时再用完整调用形式.getat from:{...} index:{...}搭配存在性检查将getat与::ifpresent {..}::otherwise {..}组合可优雅实现取到就渲染、取不到给默认文案的逻辑组合不可变操作getat返回的是值而非引用可与sorted、reversed、prepended、appended等操作任意串联原集合始终不被修改。掌握了这些要点读者即可在 Quarkdown 文档、模板与脚本中安全、高效地按索引访问任意 Iterable 值并借助链式调用构建出清晰可维护的数据处理流程。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Quarkdown 集合索引访问函数 getat 全解析：从签名、越界语义到链式调用实践
Quarkdown 集合索引访问函数 getat 全解析从签名、越界语义到链式调用实践【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdowngetat是 Quarkdown 标准库quarkdown-stdlib中用于从 Iterable 集合按索引取元素的函数它遵循 Quarkdown 特有的1-based 索引约定并内置越界兜底机制。本文以 quarkdown-quarkdoc 模块的 HTML→Markdown 文档转换测试资源getat.md为骨架结合 Collection.kt 的源码实现与 IterableTest.kt 的测试用例完整讲解getat的参数语义、越界处理、返回值类型以及如何通过函数调用链与其他集合操作组合帮助读者在 Quarkdown 文档与脚本中安全高效地访问集合元素。一、函数签名一次看清全部参数getat的 API 文档签名如下取自 getat.md.getat from:{IterableAny} \ index:{Int} \ orelse:{Dynamic DynamicValue(NOT_FOUND)} - Any该签名使用了反斜杠\进行行续接这是 Quarkdown 函数调用语法的一部分——当函数参数较多时在行尾加\即可换行继续书写参数列表编译器会消费反斜杠与换行符并忽略续行前的缩进参见 syntax-of-a-function-call.qd 中的Line continuation一节。按照 Quarkdown 的基本调用约定函数名以.开头每个参数用{}包裹形如.getat {collection} {index}。逐项解读签名中的三个要素返回值- Any返回集合中指定索引处的元素元素类型不受限制字符串、数字、布尔、嵌套集合等均可参数orelse带默认值orelse:{Dynamic DynamicValue(NOT_FOUND)}说明这是一个可选参数缺省时使用标准库中的NOT_FOUND哨兵值。二、参数详解from、index 与 orelse根据文档的 Parameters 小节三个参数的职责分别是参数类型含义默认值fromIterableAny从中取元素的集合必填indexInt要取的元素索引从 1 开始计数必填orelseDynamic索引越界时返回的兜底值未设置时返回false2.1 from接受任何可迭代值from参数的类型是IterableAny意味着凡是 Quarkdown 中可迭代的值都可以传入集合Collection普通 Markdown 列表自动转换为有序集合字典Dictionary当作键值对列表使用区间Range整数Range是合法的有序可迭代值Pair包含两个值的可迭代对象。关于哪些值属于 Iterable可进一步参考 iterable.qd 的说明。2.2 index1-based 索引是核心约定index参数最需要注意的一点是索引从 1 开始文档原文 (starting at 1)。也就是说getat中的索引1对应集合第一个元素2对应第二个依此类推。这一约定与多数编程语言包括 Quarkdown 底层实现的 Kotlin的 0-based 索引截然不同因此在底层实现中有一个显式的索引换算步骤详见第五节。2.3 orelse越界兜底值当index超出集合实际元素范围时getat不会报错而是返回orelse指定的值。这里文档描述与源码实现存在一处值得注意的细节参数文档KDoc描述为如果未设置返回false而签名中的默认值是DynamicValue(NOT_FOUND)即标准库定义的NOT_FOUND哨兵实际测试行为则是越界且未提供orelse时输出None见下节测试用例。NOT_FOUND的定义位于 Stdlib.kt其注释明确写着 Fallback value for non-existent elements in collections, dictionaries, and more取值解析为NoneValue——即 Quarkdown 的none值语义上代表不存在的元素与集合、字典等查找类函数的缺失语义保持一致。从源码结构看这是 KDoc 描述与默认值实现之间的历史性表述差异实际运行行为以测试为准无orelse时越界返回None。三、越界行为验证测试用例的实证getat的越界语义在 IterableTest.kt 中有两个直接对应的测试正常取值测试.var {abc} - A - B - C .abc::getat {2}执行结果渲染为pB/p——集合abc包含 A、B、C 三个元素索引21-based取到第二个元素B验证了 1-based 索引约定。越界测试.abc::getat {5}执行结果渲染为pspan classcodespan-contentcodeNone/code/span/p即在只有 3 个元素的集合上请求索引5返回none而不会抛出异常。此外OptionalityTest.kt 展示了getat与可选性处理函数组合的完整实战对集合[10, 20, 30].x::getat {2}::ifpresent {.1::sum {3}}::otherwise {No}输出23取到 20 后加 3而.x::getat {5}::ifpresent {.1::sum {3}}::otherwise {No}输出No越界得到 none走 otherwise 分支。这说明getat的返回值可以无缝接入ifpresent/otherwise这类存在性检查控制流实现安全的条件渲染。四、链式调用与其他集合操作自由组合文档明确指出getat是设计用于链式调用chaining的函数其链式签名如下IterableAny::getat index:{Int} \ orelse:{Dynamic} - Any链式调用的语法形式是.myiterable::operation即通过双冒号在集合值上直接调用操作参考 iterable.qd 与 syntax-of-a-function-call.qd 的 Chaining calls 章节。链式写法省略了from参数——集合值自身成为隐式的接收者只需给出index与可选的orelse。为什么要强调链式设计因为 Quarkdown 中集合操作都是不可变的任何操作都会产生新集合或新值绝不修改原始集合iterable.qd 明确说明 Operations are immutable and never modify the original iterable。这一特性使得任意长度的链式组合都是安全、可预测的。例如.foreach {.letters::prepended {A}::appended {D}} .1链式调用尤其适合在foreach循环、模板渲染等场景中把getat与size、sorted、reversed、first、last等同族操作全部定义在同一个 Collection.kt 文件中串联起来一步到位地完成取值 变换 输出。五、源码级原理1-based 索引到 Kotlin 的换算getat的底层实现位于 Collection.kt核心代码如下internal const val INDEX_STARTS_AT 1 private fun quarkdownIndexToKotlin(index: Int) index - INDEX_STARTS_AT QFunction Name(getat) LikelyChained fun collectionGet( Name(from) collection: IterableOutputValue*, index: Int, Name(orelse) fallback: DynamicValue DynamicValue(NOT_FOUND), ) nativeCollectionGet(quarkdownIndexToKotlin(index), collection, fallback)实现要点可以拆解为三层索引换算层quarkdownIndexToKotlin(index) index - 1。常量INDEX_STARTS_AT 1集中声明了Quarkdown 集合索引从 1 开始这一约定用户传入的 1-based 索引在这里统一转换为 Kotlin 的 0-based 索引。越界安全层nativeCollectionGet使用collection.toList().getOrNull(index) ?: fallback——getOrNull保证越界时返回 null 而非抛异常随后由?:兜底为fallback。这解释了为何getat天然对越界免疫。元数据层QFunction、Name(getat)、LikelyChained三个注解分别声明该函数是标准库导出的 Quarkdown 函数、对外名称为getat、且大概率会被链式调用。其中LikelyChained由 quarkdoc 模块的 LikelyChainedPageTransformer.kt 消费用于在生成的 API 文档中自动追加 Chaining 一节——这正是本文所依据的 getat.md 中链式签名部分的来源。同文件中的first、second、third、last等便捷函数也复用了nativeCollectionGet分别传入 0、1、2 等 Kotlin 原生索引与getat共享同一套越界兜底逻辑。六、文档从何而来quarkdoc 的 HTML→Markdown 转换值得说明的是本文讨论的 getat.md 并不是手写的说明文档而是 quarkdown-quarkdoc 模块中HTML→Markdown 文档转换功能的测试夹具它对应的源文件是同目录下的 getat.html一个由 Dokka 生成的带语法高亮标记的 API 页面。该转换由 HtmlToMarkdown.kt 实现测试见 HtmlToMarkdownTest.kt。其中名为stdlib page with wrapped signature keeps line breaks的测试专门验证getat这类**签名换行wrapped signature**页面在转换后仍能保留换行结构从而保证标准库函数的长签名在 Markdown 文档中清晰可读。换言之getat.md本身就是标准库函数文档生成流水线的一个端到端样例从 Kotlin 源码注解KDoc Name等→ Dokka HTML → 转换后的 Markdown 文档。七、最佳实践小结索引从 1 开始getat的索引是 1-based与底层 Kotlin 的 0-based 完全不同这是最容易踩的坑越界不必防御越界时返回orelse缺省为none不会中断文档编译可放心对动态长度的集合取值优先链式写法集合已确定时用.myiterable::getat {n}省略from代码更简洁需要显式指明来源时再用完整调用形式.getat from:{...} index:{...}搭配存在性检查将getat与::ifpresent {..}::otherwise {..}组合可优雅实现取到就渲染、取不到给默认文案的逻辑组合不可变操作getat返回的是值而非引用可与sorted、reversed、prepended、appended等操作任意串联原集合始终不被修改。掌握了这些要点读者即可在 Quarkdown 文档、模板与脚本中安全、高效地按索引访问任意 Iterable 值并借助链式调用构建出清晰可维护的数据处理流程。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考