.. role:: ts-api-decorator

####
Util
####

.. container:: ts-api-section

   .. js:module:: Util




.. toctree::
   :titlesonly:
   :hidden:

   /api_ref/viewing/classes/Util.ActionQueue
   /api_ref/viewing/classes/Util.CurrentAction
   /api_ref/viewing/classes/Util.Lazy
   /api_ref/viewing/interfaces/Util.OpenPromise
   /api_ref/viewing/classes/Util.StateMachine
   /api_ref/viewing/interfaces/Util.StateMachineAction
   /api_ref/viewing/classes/Util.Timer
   /api_ref/viewing/enum/Util.TimerIdleType
   /api_ref/viewing/interfaces/Util.TrackedOpenPromise
   /api_ref/viewing/interfaces/Util.UnsafePromise

.. container:: api-index-section

   .. rubric:: Enumerations

   .. rst-class:: api-index-list-item api-kind-enum api-parent-kind-namespace

   * :ref:`Util.TimerIdleType`



.. container:: api-index-section

   .. rubric:: Classes

   .. rst-class:: api-index-list-item api-kind-class api-parent-kind-namespace

   * :js:class:`~Util.ActionQueue`
   * :js:class:`~Util.CurrentAction`
   * :js:class:`~Util.Lazy`
   * :js:class:`~Util.StateMachine`
   * :js:class:`~Util.Timer`



.. container:: api-index-section

   .. rubric:: Interfaces

   .. rst-class:: api-index-list-item api-kind-interface api-parent-kind-namespace

   * :js:class:`~Util.OpenPromise`
   * :js:class:`~Util.StateMachineAction`
   * :js:class:`~Util.TrackedOpenPromise`
   * :js:class:`~Util.UnsafePromise`



.. container:: api-index-section

   .. rubric:: Type Aliases

   .. rst-class:: api-index-list-item api-kind-typealias api-parent-kind-namespace

   * :ref:`Util.Action`
   * :ref:`Util.ActionLike`
   * :ref:`Util.ActionResult`
   * :ref:`Util.LazyLike`
   * :ref:`Util.StateReducer`



.. container:: api-index-section

   .. rubric:: Functions

   .. rst-class:: api-index-list-item api-kind-function api-parent-kind-namespace

   * :js:func:`~Util.TypeAssert`
   * :js:func:`~Util.TypeAssertNever`
   * :js:func:`~Util._timerStressTest`
   * :js:func:`~Util.copyMap`
   * :js:func:`~Util.copySet`
   * :js:func:`~Util.createCylinderMeshDataFromArc`
   * :js:func:`~Util.createOpenPromise`
   * :js:func:`~Util.createTrackedOpenPromise`
   * :js:func:`~Util.createUnsafePromise`
   * :js:func:`~Util.delayCall`
   * :js:func:`~Util.exchangeIdEqual`
   * :js:func:`~Util.filterInPlace`
   * :js:func:`~Util.generateConeCylinderMeshData`
   * :js:func:`~Util.generateSphereMeshData`
   * :js:func:`~Util.isCircleElement`
   * :js:func:`~Util.isFace`
   * :js:func:`~Util.isLineElement`
   * :js:func:`~Util.isOtherEdgeElement`
   * :js:func:`~Util.isPlaneElement`
   * :js:func:`~Util.setSubtraction`
   * :js:func:`~Util.setToArray`
   * :js:func:`~Util.sleep`
   * :js:func:`~Util.toSet`
   * :js:func:`~Util.waitForAll`





------------

Type Aliases
============

.. rst-class:: ts-api-section

.. _Util.Action:

Action
------

.. rst-class:: ts-api-section

.. _Util.ActionLike:

ActionLike
----------

.. rst-class:: ts-api-section

.. _Util.ActionResult:

ActionResult
------------

.. rst-class:: ts-api-section

.. _Util.LazyLike:

LazyLike
--------

.. rst-class:: ts-api-section

.. _Util.StateReducer:

StateReducer
------------

Functions
=========

.. rst-class:: ts-api-section

TypeAssert
----------

.. js:function:: TypeAssert( _x)

   :param _x: None
   :type _x: T


   This purpose of this function is guarantee a value is of a given type.

   This is essentially a compile time ``console.assert(x instanceof T)``.

   This function is useful when terminating a type-narrowing if-else chain in that
   this function makes the code more robust to future type changes.

   ---

   Warning:

   ``T=never`` doesn't appear to work properly, hence the existence of ``TypeAssertNever``.

   ---

   Example:

   .. code-block::


      declare const x: Foo | Bar;
      if (x instanceof Foo) {
          console.log("foo");
      }
      else {
          // This becomes a compiler error if, for example, `x`'s type gets changed to add `Baz`:
          //    x: Foo | Bar | Baz
          TypeAssert<Bar>(x);
          console.log("bar");
      }



   :rtype: void

.. rst-class:: ts-api-section

TypeAssertNever
---------------

.. js:function:: TypeAssertNever( _x)

   :param _x: None
   :type _x: never


   See ``TypeAssert`` for details.

   This is useful for making the compiler enforce fully-covered switch statements.

   This function unconditionally throws ``InternalLogicError``.

   ---

   Example:

   .. code-block::


       switch (x) {
           case Enum.A:
               break;
           case Enum.B:
               break;
           default:
               TypeAssertNever(x); // compiler complains if missing other enum cases
       }



   :rtype: never

.. rst-class:: ts-api-section

_timerStressTest
----------------

.. js:function:: _timerStressTest()



   :rtype: void

.. rst-class:: ts-api-section

copyMap
-------

.. js:function:: copyMap( input)

   :param input: The Map to be copied
   :type input: Map <K, V>


   Performs a shallow copy of a Map.


   :rtype: Map <K, V>

.. rst-class:: ts-api-section

copySet
-------

.. js:function:: copySet( input)

   :param input: The Map to be copied
   :type input: Set <T>


   Performs a shallow copy of a Set.


   :rtype: Set <T>

.. rst-class:: ts-api-section

createCylinderMeshDataFromArc
-----------------------------

.. js:function:: createCylinderMeshDataFromArc( arc, axisDirection, numSegments, scale)

   :param arc: an array of numbers describing points on an arc that will be used to deform the cylinder
   :type arc: [number]
   :param axisDirection: cylinder axis.
   :type axisDirection: Point3
   :param numSegments: the number of segments to use when constructing the cylinder.  A higher number will give a smoother appearance but consume more memory.
   :type numSegments: number
   :param scale: a scaling factor to apply to the geometry.
   :type scale: number


   Creates a cylinder that is deformed by an arc.  An example of the resulting geometry can be observed in the Handles implementation.


   :rtype: MeshData

.. rst-class:: ts-api-section

createOpenPromise
-----------------

.. js:function:: createOpenPromise()



   Creates a new ``OpenPromise`` that does not have its state resolved or rejected.


   :rtype: OpenPromise <T>

.. rst-class:: ts-api-section

createTrackedOpenPromise
------------------------

.. js:function:: createTrackedOpenPromise()



   Creates a new ``TrackedOpenPromise`` that does not have its state resolved or rejected.


   :rtype: TrackedOpenPromise <T>

.. rst-class:: ts-api-section

createUnsafePromise
-------------------

.. js:function:: createUnsafePromise( promisedValue, readyPromise)

   :param promisedValue: The value this promise resolves to. (See ``this.unsafeValue``.)
   :type promisedValue: T
   :param readyPromise: The promise used for ``this.readyPromise``. (See also ``this.isReady``.)
   :type readyPromise: Promise <void>


   Creates a new ``UnsafePromise``.

   :returns: A new ``UnsafePromise``.


   :rtype: UnsafePromise <T>

.. rst-class:: ts-api-section

delayCall
---------

.. js:function:: delayCall( cb, args)

   :param cb: the callback to call the promise to call on the next frame.
   :type cb: function
   :param args: the arguments of the callback.
   :type args: [unknown]


   This function is an helper function that delay the call to a callback to the
   computation of the next 'frame' of the browser's js engine.
   The point is to let the js engine deal with pending promises before running
   the given code.

   :returns: a timeout id in order to cancel it if necessary.


   :rtype: ReturnType <unknown>




   .. js:function:: cb( cbArgs)
      :noindex:

      :param cbArgs: None
      :type cbArgs: [unknown]


      :rtype: unknown



.. rst-class:: ts-api-section

exchangeIdEqual
---------------

.. js:function:: exchangeIdEqual( exchangeIdA, exchangeIdB)

   :param exchangeIdA: the first exchange id to compare.
   :type exchangeIdA: string
   :param exchangeIdB: the second exchange id to compare.
   :type exchangeIdB: string


   Check if two exchange ids are equal.

   :returns: true or false if exchange ids are equal.


   :rtype: boolean

.. rst-class:: ts-api-section

filterInPlace
-------------

.. js:function:: filterInPlace( xs, pred)

   :param xs: Array to filter.
   :type xs: [T]
   :param pred: If this function returns true when testing an item, the item will be kept in the array, otherwise the item will be removed.
   :type pred: function


   This function takes an array of type <T>, and a predicate function to test each element of the array.
   This function does not create a new array.


   :rtype: void




   .. js:function:: pred( x)
      :noindex:

      :param x: None
      :type x: T


      :rtype: boolean



.. rst-class:: ts-api-section

generateConeCylinderMeshData
----------------------------

.. js:function:: generateConeCylinderMeshData( cylinderRadius, numSegments, stemHeight, coneBaseRadius, capHeight, taperHeight)

   :param cylinderRadius: the radius of the cylinder portion of the geometry.
   :type cylinderRadius: number
   :param numSegments: the number of segments used to create the cylinder and cone portions.  Increasing this number will result in a smoother appearance but consume more memory.
   :type numSegments: number
   :param stemHeight: the height of the cone portion.
   :type stemHeight: number
   :param coneBaseRadius: the radius of the cone portion
   :type coneBaseRadius: number
   :param capHeight: the height of the cylinder cap
   :type capHeight: number
   :param taperHeight: the height of the taper.
   :type taperHeight: number


   Creates a cylinder with an attached cone.  An example of the resulting geometry can be observed in the default Axis Triad or Handles implementation.


   :rtype: MeshData

.. rst-class:: ts-api-section

generateSphereMeshData
----------------------

.. js:function:: generateSphereMeshData()



   Creates a basic sphere with normals.


   :rtype: MeshData

.. rst-class:: ts-api-section

isCircleElement
---------------

.. js:function:: isCircleElement( prop)

   :param prop: the Subentity to check.
   :type prop: object


   Check whether or not a Subentity is a CircleElement.

   :returns: true if the prop passed is a CircleElement, false otherwise.


   :rtype: boolean

.. rst-class:: ts-api-section

isFace
------

.. js:function:: isFace( prop)

   :param prop: the Subentity to check.
   :type prop: object


   Check whether or not a Subentity is a Face.

   :returns: true if the prop passed is a Face, false otherwise.


   :rtype: boolean

.. rst-class:: ts-api-section

isLineElement
-------------

.. js:function:: isLineElement( prop)

   :param prop: the Subentity to check.
   :type prop: object


   Check whether or not a Subentity is a LineElement.

   :returns: true if the prop passed is a LineElement, false otherwise.


   :rtype: boolean

.. rst-class:: ts-api-section

isOtherEdgeElement
------------------

.. js:function:: isOtherEdgeElement( prop)

   :param prop: the Subentity to check.
   :type prop: object


   Check whether or not a Subentity is a OtherEdgeElement.

   :returns: true if the prop passed is a OtherEdgeElement, false otherwise.


   :rtype: boolean

.. rst-class:: ts-api-section

isPlaneElement
--------------

.. js:function:: isPlaneElement( prop)

   :param prop: the Subentity to check.
   :type prop: object


   Check whether or not a Subentity is a PlaneElement.

   :returns: true if the prop passed is a PlaneElement, false otherwise.


   :rtype: boolean

.. rst-class:: ts-api-section

setSubtraction
--------------

.. js:function:: setSubtraction( setA, setB)

   :param setA: The starting set to start subtracting from.
   :type setA: Set <T>
   :param setB: The set used to reject values from ``setA``.
   :type setB: Set <T>


   Returns a new set consisting of all elements in ``setA`` not found in ``setB``.

   :returns: The resulting set.


   :rtype: Set <T>

.. rst-class:: ts-api-section

setToArray
----------

.. js:function:: setToArray( set)

   :param set: The set to convert.
   :type set: Set <T>


   Turns a Set<T> into an Array<T>.

   :returns: The resulting array.


   :rtype: [T]

.. rst-class:: ts-api-section

sleep
-----

.. js:function:: sleep( duration)

   :param duration: number of milliseconds until the returned promise can resolve
   :type duration: number


   Returns a promise that resolves after the provided number of milliseconds


   :rtype: Promise <void>

.. rst-class:: ts-api-section

toSet
-----

.. js:function:: toSet( xs)

   :param xs: Array to create a Set from
   :type xs: [T]


   Creates a Set from the provided array.


   :rtype: Set <T>

.. rst-class:: ts-api-section

waitForAll
----------

.. js:function:: waitForAll( promises)

   :param promises: array of promises.
   :type promises: [Promise <void>]


   This function behaves like writing [[Promise.all(promises).then(no_op)]] but does not incur the overhead of creating a [[.then]] promise.
   Using this function can provide a performance boost when doing large amounts of batch processing with groups of promises.


   :rtype: Promise <void>

