第五章 IRIS 动态实体方法快速参考

本节提供了每个可用动态实体方法的概述和参考。动态实体是%Library.DynamicObject或%Library.DynamicArray的实例，这两个实例都扩展了%Library_DynamicAbstractObject。本章中的每个列表都包含指向相应在线类参考文档的链接。

本节列出了所有可用的动态实体方法，简要描述了每种方法，并提供了更多信息的链接。所有方法都可用于对象和数组，但%Push()和%Pop()除外，它们仅适用于数组。

5.1 方法详细信息

%FromJSON()

给定JSON源，解析源并在包含解析的JSON返回数据类型为%DynamicAbstractObject的对象。如果在分析过程中发生错误，将引发异常。有关详细信息和示例，请参阅“将动态实体转换为JSON”。

   classmethod %FromJSON(str) as %DynamicAbstractObject

参数：

• str-输入可以来自以下任何一个源：
  • 包含源的字符串值。
  • 要从中读取源的流对象。

另请参阅：%FromJSONFile()，%ToJSON()，将大型动态实体序列化为流

类引用：%DynamicAbstractObject.%FromJSON()

%FromJSONFile()

给定JSON源，解析源并在包含解析的JSON返回数据类型为%DynamicAbstractObject的对象。如果在分析过程中发生错误，将引发异常。有关详细信息和示例，请参阅“将动态实体转换为JSON”。

   classmethod %FromJSONFile(filename) as %DynamicAbstractObject

参数：

• filename—可以读取源的文件URI的名称。文件必须编码为UTF-8。

另请参阅：%FromJSONFile()，%ToJSON()，将大型动态实体序列化为流

类引用：%DynamicAbstractObject.%FromJSON()

%Get()

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

   method %Get(key) as %RawString

参数：

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

另请参阅： %Set(), %Remove(), %Pop()

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

%GetIterator()

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

   method %GetIterator() as %Iterator.AbstractIterator

另请参阅：%GetNext()

类引用：%DynamicObject.%GetIterator(),%DynamicArray.%GetIterator(),%Iterator.Object,%Iterator.Array

%GetNext()

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

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

参数：

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

另请参阅：%GetIterator()

类引用：%Iterator.Object.%GetNext(),%Iterator.Array.%GetNext()

%GetTypeOf()

给定有效的对象键或数组索引，返回一个字符串，指示值的数据类型。有关详细信息和示例，请参阅“使用数据类型”。

   method %GetTypeOf(key) as %String

参数：

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

返回值：

将返回以下字符串之一：

• “null”-JSON null
• “boolean”-零（“false”）或非零（“true”）数值
• “number”-任何规范数值
• “oref”-对另一个对象的引用
• “object”-嵌套对象
• “array”-嵌套数组
• “string”-标准文本字符串
• “unassigned”-属性或元素存在，但没有赋值

另请参阅：%IsDefined()

类引用：%DynamicAbstractObject.%GetTypeOf()

%IsDefined()

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

   method %IsDefined(key) as %Boolean

参数：

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

另请参阅：解析Null、空字符串和未分配的值

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

%Pop()

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

   method %Pop() as %RawString

另请参阅：%Push(), %Get(), %Remove(),解析Null、空字符串和未分配的值

类引用：%DynamicArray.%Pop()

%Push()

给定一个新值，将其附加到当前数组的末尾，从而增加数组的长度。返回指向当前已修改数组的oref，以便可以链接对%Push()的调用。有关详细信息和示例，请参阅“将%Push和%Pop用于动态阵列”。

   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()重写默认数据类型”。

另请参阅：%Pop(), %Set(), 方法链

类引用：%DynamicArray.%Push()

%Remove()

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

   method %Remove(key) as %DynamicAbstractObject

参数：

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

另请参阅：%Set(), %Get(), %Pop()

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

%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”-将值转换为文本字符串。

%Size()

返回显示动态对象或数组大小的整数。对于数组，大小包括数组中未分配的条目。对于对象，大小仅包括具有指定值的元素。有关详细信息和示例，请参阅“使用%Sizee()进行稀疏阵列迭代”。

   method %Size() as %Integer

另请参阅：%GetNext()

类引用：%DynamicAbstractObject.%Size()

%ToJSON()

转换%DynamicAbstractObject的实例。转换为JSON字符串。有关详细信息和示例，请参阅“将动态实体转换为JSON”。

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

参数：

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

另请参阅：%FromJSON(), %FromJSONFile()

类引用： %DynamicAbstractObject.%ToJSON()