第7集丨ObjectScript JSON 中 dynEnt 方法汇总

写在前面

为了与大家保持一个愉快的沟通，以及便于描述方便，本文做了一些术语简写，如下：

• 文章宗旨：尽量不讲废话
• 文章思路：以总结的方式编写
• dynEnt：动态实体
• dynObj：动态对象
• dynAry：动态数组
• textConstructor( 文本构造器)：文字 JSON 构造函数{}和[]
• jsonStr：文本 JSON 字符串
• * ：表示重点掌握
• -：废话可忽略
• spaAry(稀疏数组)：有些元素没有值
• JSON Adaptor：json 适配器

本节提供每个可用动态实体方法的概述和参考。动态实体是%Library.DynamicObject 或 %Library.DynamicArray ，两者都扩展%Library.DynamicAbstractObject抽象对象.

1. %FromJSON()

给定一个 JSON 源，解析该源并返回数据类型为 %DynamicAbstractObject 的对象 。如果在解析过程中发生错误，将引发异常。

classmethod %FromJSON(str) as %DynamicAbstractObject

参数：

• str — 输入可以来自以下任何一个源：
  • 包含源的字符串值。
  • 要从中读取源的流对象。
  • 文件 URI，可在其中读取源。该文件必须编码为 UTF-8。

另请参考：%ToJSON()，将大型dynEnt序列化为流

类参考：%DynamicAbstractObject.%FromJSON()

2. %get()

给定有效的对象键或数组索引，返回值。如果该值不存在，则返回空字符串 “”。有关详细信息和示例，请参阅%Set()、%Get ()和 %Remove() 动态定义属性和值

method %Get(key) as %RawString

参数：

• key ― 要检索的值的对象键或数组索引。数组索引必须作为规范整数值传递。数组索引从位置 0 开始。

类引用： %DynamicObject.%Get() 和 %DynamicArray.%Get()

3. %GetIterator()

返回一个 %Iterator 对象，该对象允许对dynEnt的所有成员进行迭代。有关详细信息和示例，请参阅“使用 %GetNext()迭代动态实体” 。

 method %GetIterator() as %Iterator.AbstractIterator

类参考：%DynamicObject.%GetIterator() 、%DynamicArray.%GetIterator(),、%Iterator.Object、%Iterator.Array

4. %GetNext()

这是 %GetIterator() 返回的 %Iterator 对象的方法。如果迭代器位于有效元素上，则前进迭代器并返回 true;如果它超出最后一个元素，则返回 false。键和值参数返回当前迭代器位置处的有效元素的值。有关详细信息和示例，请参阅“使用 %GetNext()迭代动态实体” 。

method getNext(Output key, Output value) as %Integer

参数：

• key — 返回元素在当前位置的对象键或数组索引

• value — 返回元素在当前位置的值。

类参考：%Iterator.Object.%GetNext() 、%Iterator.Array.%GetNext()

5. %GetTypeOf()

给定有效的对象键或数组索引，返回一个字符串，指示值的数据类型。有关详细信息和示例，请参阅 链接: 第4集丨ObjectScript JSON 中 数据类型应用

   method %GetTypeOf(key) as %String

参数：

• key ― 要测试的值的对象键或数组索引。

返回值：将返回以下字符串之一

• “null” — 一个 JSON null

• “boolean” — — 零（“假”）或非零（“真”）数值

• “number” — 任何规范的数值

• “oref” — 对另一个对象的引用

• “object” — 嵌套对象

• “array” — 一个嵌套数组

• “string” — 标准文本字符串

• “unassigned” — 属性或元素存在，但没有赋值

类参考: %DynamicAbstractObject.%GetTypeOf()

6. %IsDefined()

测试键指定的项是否在对象中定义。如果项目未分配或不存在，则返回 false。有关详细信息和示例，请参阅使用 %IsDefined() 测试有效值

 method %IsDefined(key) as %Boolean

参数：

• key ― 要测试的项目的对象键或数组索引。数组索引必须作为规范整数值传递。数组索引从位置 0 开始。

另请参见：解析null、空字符串值和未赋值
类引用： %DynamicObject.%IsDefined()、DynamicArray.%IsDefined()

7. %Pop()

返回数组中最后一个成员的值。然后从数组中删除该值。如果数组已经为空，则该方法返回空字符串 “”。有关详细信息和示例，请参阅%Push 和 %Pop 在dynAry 中应用

method %Pop() as %RawString

另请参见：%Push（）、%Get（）、%Remove（）、解析 Null、空字符串和未赋值

类引用：%DynamicArray.%Pop()

8. %Push（）

给定一个新值，将其追加到当前数组的末尾，从而增加数组的长度。返回指向当前修改的数组的 oref，以便可以链接对 %Push（） 的调用。有关详细信息和示例，请参阅%Push 和 %Pop 在dynAry 中应用

method %Push(value, type) as %DynamicAbstractObject

参数：

• value — 要分配给新数组元素的值。

• type — （可选）指示值的数据类型的字符串。可以使用以下字符串：

  • “null” — 一个 JSON null。值参数必须为 “”（空字符串）。

  • “boolean” — JSON false（值参数必须为 0）或 true（值参数必须为 1）。

  • “false” — JSON false（值参数必须为 0）。

  • “true” — JSON true（值参数必须为 1）。

  • “number” — 将值转换为规范数值

  • “string” — 将值转换为文本字符串

注意：如果指定的值是对象或 oref，则不能使用可选类型参数。例如，如果指定的值是动态实体，则无论为类型指定什么值，都将引发错误。有关详细信息，请参阅使用 %Set() 或 %Push() 覆盖默认数据类型

类引用：%DynamicArray.%Push()

9. %Remove()

从动态对象或数组中删除指定的元素，并返回已删除元素的值。如果元素的值是嵌入的动态对象或数组，则也会删除所有从属节点。在动态数组中，删除的元素后面的所有元素的下标位置将递减 1。有关详细信息和示例，请参阅%Set()、%Get ()和 %Remove() 动态定义属性和值

method %Remove(key) as %DynamicAbstractObject

参数：

• key ― 要删除的元素的对象键或数组索引。数组索引必须作为规范整数值传递。数组索引从位置 0 开始。

类参考：%DynamicObject.%Remove()、%DynamicArray.%Remove()

10. %Set()

创建新值或更新现有值。返回对已修改数组的引用，允许嵌套对 %Set（） 的调用。有关详细信息和示例，请参阅%Set()、%Get ()和 %Remove() 动态定义属性和值

method %Set(key, value, type) as %DynamicAbstractObject

参数：

• key ― 要创建或更新的值的对象键或数组索引。数组索引必须作为规范整数值传递。数组索引从位置 0 开始。

• value — 用于更新先前值或创建新值的新值。

• type — （可选）指示值的数据类型的字符串。可以使用以下字符串：

  • “null” — 一个 JSON null。值参数必须为 “”（空字符串）。

  • “boolean” — JSON false（值参数必须为 0）或 true（值参数必须为 1）。

  • “false” — JSON false（值参数必须为 0）。

  • “true” — JSON true（值参数必须为 1）。

  • “number” — 将值转换为规范数值

  • “string” — 将值转换为文本字符串

注意：如果指定的值是对象或 oref，则不能使用可选类型参数。例如，如果指定的值是动态实体，则无论为类型指定什么值，都将引发错误。有关详细信息，请参阅使用 %Set() 或 %Push() 覆盖默认数据类型

类引用：%DynamicObject.%Set()、%DynamicArray.%Set()

11. %Size()

返回一个整数，显示动态对象或数组的大小。对于数组，大小包括数组中未分配的条目。对于对象，大小仅包括已赋值的元素。有关详细信息和示例，请参阅具有 %Size() 的稀疏数组迭代

method %Size() as %Integer

类引用： %DynamicAbstractObject

12. %ToJSON()

将 %DynamicAbstractObject的实例转换为 JSON 字符串。

 method %ToJSON(outstrm As %Stream.Object) as %String

参数：

• outstrm — 可选。有多种可能性：
  • 如果未指定 outstrm 并且通过 DO 调用该方法，则 JSON 字符串将写入当前输出设备。
  • 如果未指定 outstrm 并且该方法作为表达式调用，则 JSON 字符串将成为表达式的值。
  • 如果将 outstrm 指定为%流.对象，JSON 字符串将写入流（有关详细信息和示例，请参阅“将大型动态实体序列化为流”）。
  • 如果 outstrm 是一个对象，但不是%流.对象然后将引发异常。
  • 如果 outstrm 不是对象且不为 null，则假定它是完全限定的文件规范（必须定义文件的完整路径）。文件链接到新创建的%流.文件字符流中，JSON 字符串将写入流，流在完成后保存到文件中。

类引用： %DynamicAbstractObject.%ToJSON()