System.Walker

Type
Location: igium / Igium.Web / System / System.Walker
Examples: Igium.Web Examples

Instance Constructor

Constructor Test Description
new System.Walker(par: Object) N Creates a new System.Walker instance
par.stackSize: Integer N Optional. Defaults to System.Walker.defaultStackSize. Species the initial size of the stack used by the walker for the non-recursive traversal of trees. If the traversal depth exceeds this initial size, the stack size will be increased accordingly, wich could have a negative effect on performance.
par.walkProperties: Boolean N Optional. Defaults to true. Indicates whether the walker should consider object's propertes (with getters and setters) during traversal.
par.walkFields: Boolean N Optional. Defaults to true. Indicates whether the walker should consider object's fields during traversal.

Instance Methods

Method Test Description
walk(o, onVisit): void N Visits all nodes in an object's or array's reference graph.
walk::o: Object N A JavaScript object or array to traverse.
walk::onVisit(containerItemType, container, containerUniqueId, depth, objectArray, key, valueItemType, value, uniqueId, revisit): Integer N A callback that is called for every node that the walker visits during traversal.

walk::onVisit

Return value

This function must return one of the following values:

Value Description
System.Walker.WALK_OK: Integer Instructs the walker to continue with the traversal after the visitor function returns.
System.Walker.WALK_SKIP: Integer Instructs the walker to not traverse the current object or array after the visitor function returns.
System.Walker.WALK_BREAK: Integer Instructs the walker to immediately end the traversal and return after the visitor function returns.

Parameters

Parameter Test Description
walk::onVisit::containerItemType: Integer N Indicates whether the current node is contained by an object (System.Walker.ITEM_TYPE_OBJECT) or an array (System.Walker.ITEM_TYPE_ARRAY).
walk::onVisit::container: Object/Array N The object/array that holds the reference to the current node.
walk::onVisit::containerUniqueId: Integer N A number uniquely identifying the container object/array's instance during the current traversal. Once assigned to an object/array, this value doesn't change until the traversal ends and can be stored and used safely by the walker's user.
walk::onVisit::depth: Integer N The distance of the current node from the root node on the current traversal path.
walk::onVisit::objectArray: Array N An array holding information of the current traversal path to the current node. This array has the following form:
--- walk::onVisit::objectArray[0] N For internal use. A unique id of the array in the array pool. Used for memory management optimization.
--- walk::onVisit::objectArray[1] N The count of the significant elements in the array. objectArrays are preallocated and the objectArray.length reflects the preallocation size. To get the real length of the data in the array, use objectArray[1] instead.
--- walk::onVisit::objectArray[2] N The unique id of the root object/array, which is always 1.
--- walk::onVisit::objectArray[3] N The root object/array property name/index from the current traversal path.
--- (walk::onVisit::objectArray[2*n], walk::onVisit::objectArray[2*n + 1]), n >= 2 N For all but the last two values this pair of values represents a vector (unique id, property name/index), where unique id is a unique id of an anscestor object/array, and property name/index is the anscestor's property name/index from the current traversal path; the last two values of the objectArray represent a vector (unique id, node), where unique id is a unique id of the current object/array or null for current value nodes, and node equals walk::onVisit::value.
walk::onVisit::key: String/Integer N If walk::onVisit::containerItemType == System.Walker.ITEM_TYPE_OBJECT constains the name of the property of the current node's container that contains it. If walk::onVisit::containerItemType == System.Walker.ITEM_TYPE_ARRAY constains the index of the current node within its container in the current traversal path.
walk::onVisit::valueItemType: Integer N Indicates whether the current node is an object (System.Walker.ITEM_TYPE_OBJECT), an array (System.Walker.ITEM_TYPE_ARRAY) or of a value type (System.Walker.ITEM_TYPE_VALUE).
walk::onVisit::value: any N The current node.
walk::onVisit::uniqueId: Integer N A number uniquely identifying the current object/array's instance during the current traversal. Once assigned to an object/array, this value doesn't change until the traversal ends and can be stored and used safely by the walker's user. If the current node is of a value type, this parameter is set to null.
walk::onVisit::revisit: Boolean N Indicates whether the current node has been already visited as part of another traversal path. Note that revisiting nodes is no sign of a cyclic structure, it simply means that two different properties/array locations reference the same object/array. For current nodes of value types always this parameter is always set to false.

Static Fields

Field Value Description
System.Walker.defaultStackSize: Integer 256 Species the default initial size of the stack used by the walker for the non-recursive traversal of trees.
System.Walker.ITEM_TYPE_OBJECT: Integer 1 Indicates that the visited memory graph node is an object. The corresponding key must be interpreted as an object property name.
System.Walker.ITEM_TYPE_ARRAY: Integer 2 Indicates that the visited memory graph node is an array. The corresponding key must be interpreted as a numerical index in an array.
System.Walker.ITEM_TYPE_VALUE: Integer 3 Indicates that the visited memory graph node has a value type. The corresponding key will have the value of null and must be ignored.
System.Walker.WALK_OK: Integer 1 Instructs the walker to continue with the traversal after the visitor function returns.
System.Walker.WALK_SKIP: Integer 2 Instructs the walker to not traverse the current object or array after the visitor function returns.
System.Walker.WALK_BREAK: Integer 2 Instructs the walker to immediately end the traversal and return after the visitor function returns.

Remarks

System.Walker's walk method

System.Walker's walk method visits all nodes in an object's or array's reference graph with the following specifics:

  • does not visit the root object itself; will set revisit to true if the root object is referenced in the graph
  • due to optimizations does not follow any named traversal algorythm
  • in trees ascendents are guarantied to be visited before descendants but not necessarily immediately one after the other
  • within a single object/array all properties/items are guarantied to be visited in the order the JavaScript virtual machine enumerates them
  • assigns an autoincrement unique number to every visited object/array and passes it to onVisit (can be used as an array indexer without performance penalty)
  • cyclic references can be detected from the onVisit callback using System.Walker.hasCyclicStructure(objectArray) === true
  • to prevent the walker from walking the same object over and over again, onVisit is recommended to return System.Walker.WALK_SKIP on revisit == true
  • to prevent infinite reference cycles, onVisit is recommended to return System.Walker.WALK_SKIP on System.Walker.hasCyclicStructure(objectArray) === true
  • to prevent walking the global object, onVisit is recommended to return System.Walker.WALK_SKIP on value === GLOBAL (value === window)
  • to ignore object functions, onVisit is recommended to return System.Walker.WALK_SKIP on System.Type.isFunction(value) === true)

Unique ids

An autoincrement unique id is assigned to every object and array instance on first encounter. Further references to the same object/array can be recognized by the same unique id. Because unique ids are assigned in the order of visiting, it is guarantied that all containerUniqueId and uniqueId values passed to onVisit will appear for the first time in ascending order and without spaces, starting from 2 (0 is not used and the unique id 1 is constantly assigned to the root object/array, which never gets visited).

The objectArray structure

Data elements (index >= 2) represent the following sequence: <rootObjectId==1>, <rootObjectPropertyName>, <childObjectId>, <childObjectPropertyName>, ..., <currentObjectId>, <currentObject>, or, for the root object: <rootObjectId==1>, <rootObject> (will never be passed to onVisit, because the walker never visits the root object).

Unit tests: TODO