.. default-domain:: chpl .. module:: MemMove :synopsis: Support for move-initializing and deinitializing values. MemMove ======= **Usage** .. code-block:: chapel use MemMove; or .. code-block:: chapel import MemMove; Support for move-initializing and deinitializing values. The :mod:`MemMove` module provides functions which enable users to move-initialize and deinitialize values. The functionality provided by this module can be used to implement collections in a manner similar to those implemented by the Chapel standard modules (such as :mod:`List` or :mod:`Map`). .. note:: Throughout documentation, the term `variable` also includes non-const formals, array elements, record or class fields, and tuple components. .. function:: proc needsDeinit(type t) param .. warning:: 'needsDeinit' is deprecated; please use 'needsDestroy' instead Check to see if a given type needs to be deinitialized. :arg t: A type to check for deinitialization :type t: `type` :return: ``true`` if ``t`` needs to be deinitialized :rtype: param bool .. function:: proc needsDestroy(type t) param: bool Check to see if a given type would normally be destroyed automatically by the compiler when its lifetime ends. For example, passing an ``owned`` class would see this function return ``true``, whereas passing an ``unmanaged`` class would result in ``false``. A ``shared`` class would also result in ``true`` because the compiler destroys ``shared`` variables to decrement the reference count (and possibly the object being managed, as well). :arg t: A type to check :type t: `type` :return: ``true`` if ``t`` needs to be automatically destroyed :rtype: param bool .. function:: proc explicitDeinit(ref arg: ?t) .. warning:: 'explicitDeinit' is now deprecated; please use 'destroy' instead Explicitly deinitialize a variable. The variable referred to by ``arg`` should be considered uninitialized after a call to this function. .. warning:: At present the compiler does not account for deinitialization performed upon a call to :proc:`explicitDeinit()`. It should only be called when deinitialization would not occur otherwise. :arg arg: A variable to deinitialize .. function:: proc destroy(ref obj: ?t) Explicitly destroy a variable as the compiler would when its lifetime ends. The variable referred to by ``obj`` should be considered unusable after a call to this function, and its particular state is undefined. This function has no effect if :proc:`needsDestroy` returns ``false`` for the argument's type. .. warning:: At present the compiler does not account for manual destruction performed upon a call to :proc:`destroy()`. It should only be called when automatic destruction would not occur otherwise. :arg obj: A variable to deinitialize .. function:: proc moveInitialize(ref dst, in src) Move-initialize ``dst`` with the value in ``src``. The contents of ``dst`` are not deinitialized before the move, and ``src`` is not deinitialized after the move. .. warning:: If ``dst`` references an already initialized variable, it will be overwritten by the contents of ``src`` without being deinitialized first. Call :proc:`destroy()` to deinitialize ``dst`` if necessary. .. warning:: The static types of ``dst`` and ``src`` must match, or else a compile-time error will be issued. .. note:: If the compiler inserts a copy for the argument to ``src``, then a compile-time error will be issued. The most likely cause is that the argument is used elsewhere following the call to ``moveInitialize``. The ``moveFrom`` function can be used with the ``src`` argument to avoid the copy when certain of the variable's usage: moveInitialize(myDst, moveFrom(mySrc)); :arg dst: A variable to move-initialize, whose type matches ``src`` :arg src: A value to move-initialize from .. function:: proc moveFrom(const ref src: ?t) Move the contents of the variable or constant referred to by ``src`` into a new returned value. .. warning:: The variable or constant referred to by ``src`` should be considered uninitialized after a call to this function. :arg src: A variable or constant to move :return: The contents of ``src`` moved into a new value .. function:: proc moveSwap(ref x: ?t, ref y: t) Swap the contents of the variables referred to by ``x`` and ``y``. This function does not call the ``<=>`` operator. Unlike the ``<=>`` operator, :proc:`moveSwap()` does not perform assignment or initialization. :arg x: A variable to swap :arg y: A variable to swap .. function:: proc moveArrayElements(ref dst: [] ?eltType, const dstRegion, const ref src: [] eltType, const srcRegion): void throws .. warning:: 'moveArrayElements' is unstable and subject to change in the future Move-initialize a group of array elements from a group of elements in another array. This function is equivalent to a sequence of individual calls to :proc:`moveInitialize()`. This function only accepts rectangular arrays, rectangular domains, or ranges. The index type of the regions must also match the index type of their corresponding arrays. Any range arguments must have both an upper and lower bound. :arg dst: The destination array :arg dstRegion: A domain or range of indices in ``dst`` :arg src: The source array :arg srcRegion: A domain or range of indices in ``src`` :throws IllegalArgumentError: if region sizes do not match, if a region contains indices not in the corresponding array, if ``src`` and ``dst`` are determined to be aliases and the regions overlap. .. function:: proc moveArrayElements(ref dst: [] ?eltType, const ref src: [] eltType): void throws .. warning:: 'moveArrayElements' is unstable and subject to change in the future Move-initialize a group of array elements from a group of elements in another array. This function is equivalent to a sequence of individual calls to :proc:`moveInitialize()`. This function only accepts rectangular arrays. :arg dst: The destination array :arg src: The source array :throws IllegalArgumentError: if the array sizes do not match, if ``src`` and ``dst`` are determined to be aliases and overlap. .. function:: proc moveInitializeArrayElements(ref a: [?d], dstStartIndex: a.idxType, srcStartIndex: a.idxType, numElements: int) .. warning:: 'moveInitializeArrayElements' is deprecated; please use 'moveArrayElements' instead Move-initialize a group of array elements from a group of elements in the same array. This function is equivalent to a sequence of individual calls to :proc:`moveInitialize()`. .. warning:: This function will halt if the value of ``numElements`` is negative, or if any of the elements in ``dstStartIndex..#numElements`` or ``srcStartIndex..#numElements`` are out of bounds. This function will halt if the ranges ``dstStartIndex..#numElements`` and ``srcStartIndex..#numElements`` intersect. No checks will occur when the `--fast` or `--no-checks` flags are used. :arg a: The array with source and destination elements :arg dstStartIndex: Destination index of elements to move-initialize :type dstStartIndex: `a.idxType` :arg srcStartIndex: Source index of elements to move-initialize from :type srcStartIndex: `a.idxType` :arg numElements: The number of elements to move-initialize :type numElements: int .. function:: proc moveInitializeArrayElements(ref dstA: [] ?t, dstStartIndex: dstA.idxType, srcA: [] t, srcStartIndex: srcA.idxType, numElements: int) .. warning:: 'moveInitializeArrayElements' is deprecated; please use 'moveArrayElements' instead Move-initialize a group of array elements from a group of elements in another array. This function is equivalent to a sequence of individual calls to :proc:`moveInitialize()`. .. warning:: This function will halt if the value of ``numElements`` is negative, or if any of the elements in ``dstStartIndex..#numElements`` or ``srcStartIndex..#numElements`` are out of bounds. This function will halt if ``dstA`` and ``srcA`` are the same array and the ranges ``dstStartIndex..#numElements`` and ``srcStartIndex..#numElements`` intersect. No checks will occur when the `--fast` or `--no-checks` flags are used. :arg dstA: The array with destination elements :arg dstStartIndex: Destination index of elements to move-initialize :type dstStartIndex: `dstA.idxType` :arg srcA: The array with source elements :type srcA: An array with the same element type as `dstA.eltType` :arg srcStartIndex: Source index of elements to move-initialize from :type srcStartIndex: `srcA.idxType` :arg numElements: The number of elements to move-initialize :type numElements: int