.. default-domain:: chpl .. module:: Types :synopsis: Functions related to predefined types. Types ===== .. note:: All Chapel programs automatically ``use`` this module by default. An explicit ``use`` statement is not necessary. Functions related to predefined types. .. function:: proc isType(e) param Returns ``true`` if the argument is a type. .. function:: proc isParam(e) param Returns ``true`` if the argument is a param. .. function:: proc isPrimitiveType(type t) param Returns ``true`` if the type ``t`` is a primitive type, as defined by the language specification. .. function:: proc isNumericType(type t) param Returns ``true`` if the type ``t`` is one the following types, of any width: ``int``, ``uint``, ``real``, ``imag``, ``complex``. .. function:: proc isIntegralType(type t) param Returns ``true`` if the type ``t`` is one the following types, of any width: ``int``, ``uint``. .. function:: proc isNothingType(type t) param Returns ``true`` if the type ``t`` is the ``nothing`` type. .. function:: proc isBoolType(type t) param Returns ``true`` if the type ``t`` is a ``bool`` type, of any width. .. function:: proc isIntType(type t) param Returns ``true`` if the type ``t`` is an ``int`` type, of any width. .. function:: proc isUintType(type t) param Returns ``true`` if the type ``t`` is a ``uint`` type, of any width. .. function:: proc isRealType(type t) param Returns ``true`` if the type ``t`` is a ``real`` type, of any width. .. function:: proc isImagType(type t) param Returns ``true`` if the type ``t`` is an ``imag`` type, of any width. .. function:: proc isComplexType(type t) param Returns ``true`` if the type ``t`` is a ``complex`` type, of any width. .. function:: proc isStringType(type t) param Returns ``true`` if the type ``t`` is the ``string`` type. .. function:: proc isBytesType(type t) param Returns ``true`` if the type ``t`` is the ``bytes`` type. .. function:: proc isEnumType(type t) param Returns ``true`` if the type ``t`` is an ``enum`` type. .. function:: proc isClassType(type t) param Return true if ``t`` is a class type. Otherwise return false. .. function:: proc isRecordType(type t) param Return true if ``t`` is a record type. Otherwise return false. .. function:: proc isUnionType(type t) param Return true if ``t`` is a union type. Otherwise return false. .. function:: proc isTupleType(type t) param Returns ``true`` if its argument is a tuple type. .. function:: proc isRangeType(type t) param Return true if argument ``t`` is a range type, false otherwise .. function:: proc isDomainType(type t) param Return true if ``t`` is a domain type. Otherwise return false. .. function:: proc isArrayType(type t) param Return true if ``t`` is an array type. Otherwise return false. .. function:: proc isDmapType(type t) param Return true if ``t`` is a domain map type. Otherwise return false. .. function:: proc isSyncType(type t) param Returns true if ``t`` is a sync type, false otherwise. .. function:: proc isSingleType(type t) param Returns true if ``t`` is a single type, false otherwise. .. function:: proc isAtomicType(type t) param Returns true if ``t`` is an atomic type, false otherwise. .. function:: proc isVoidType(type t) param Returns ``true`` if the type ``t`` is the ``void`` type. .. function:: proc isAbstractEnumType(type t) param Returns ``true`` if the type ``t`` is an abstract ``enum`` type (one in which not all symbols have associated integer values). .. function:: proc isHomogeneousTupleType(type t) param Returns ``true`` if its argument is a homogeneous tuple type. .. function:: proc isExternUnionType(type t) param Returns ``true`` if the type ``t`` is an extern union type. .. function:: proc isRefIterType(type t) param Returns ``true`` if the type ``t`` is a ref iter type. .. function:: proc isPrimitiveValue(e) param Returns ``true`` if the argument is a value of primitive type. .. function:: proc isNumericValue(e) param Returns ``true`` if the argument is a value of one the following types: ``int``, ``uint``, ``real``, ``imag``, ``complex``. .. function:: proc isIntegralValue(e) param Returns ``true`` if the argument is a value of one the following types: ``int``, ``uint``. .. function:: proc isNothingValue(e) param Returns ``true`` if the argument is a ``nothing`` value (i.e., ``none``) .. function:: proc isBoolValue(e) param Returns ``true`` if the argument is a ``bool`` value. .. function:: proc isIntValue(e) param Returns ``true`` if the argument is a ``int`` value. .. function:: proc isUintValue(e) param Returns ``true`` if the argument is a ``uint`` value. .. function:: proc isRealValue(e) param Returns ``true`` if the argument is a ``real`` value. .. function:: proc isImagValue(e) param Returns ``true`` if the argument is a ``imag`` value. .. function:: proc isComplexValue(e) param Returns ``true`` if the argument is a ``complex`` value. .. function:: proc isStringValue(e) param Returns ``true`` if the argument is a ``string`` value. .. function:: proc isBytesValue(e) param Returns ``true`` if the argument is a ``bytes`` value. .. function:: proc isEnumValue(e) param Returns ``true`` if the argument is a ``enum`` value. .. function:: proc isClassValue(e) param Returns ``true`` if the argument is a class value .. function:: proc isRecordValue(e) param Returns ``true`` if the argument is a record value .. function:: proc isUnionValue(e) param Returns ``true`` if the argument is a union value .. function:: proc isTupleValue(x) param Returns ``true`` if the argument is a tuple value .. function:: proc isRangeValue(r) param Return true if argument ``r`` is a range, false otherwise .. function:: proc isDomainValue(e) param Return true if ``e`` is a domain. Otherwise return false. .. function:: proc isArrayValue(e) param Return true if ``e`` is an array. Otherwise return false. .. function:: proc isDmapValue(e) param Return true if ``e`` is a domain map. Otherwise return false. .. function:: proc isSyncValue(x) param Returns ``true`` if the argument is a sync value .. function:: proc isSingleValue(x) param Returns ``true`` if the argument is a single value .. function:: proc isAtomicValue(e) param Returns ``true`` if the argument is an atomic value .. function:: proc isPrimitive(e) param Returns ``true`` if the argument is a primitive type, as defined by the language specification, or a value of a primitive type. .. function:: proc isNumeric(e) param Returns ``true`` if the argument is one the following types, of any width: ``int``, ``uint``, ``real``, ``imag``, ``complex``, or a value of such a type. .. function:: proc isIntegral(e) param Returns ``true`` if the argument is one the following types, of any width: ``int``, ``uint``, or a value of such a type. .. function:: proc isNothing(e) param Returns ``true`` if the argument is ``none`` or the ``nothing`` type. as defined by the language specification. .. function:: proc isBool(e) param Returns ``true`` if the argument is a ``bool`` type or value, of any width. .. function:: proc isInt(e) param Returns ``true`` if the argument is an ``int`` type or value, of any width. .. function:: proc isUint(e) param Returns ``true`` if the argument is a ``uint`` type or value, of any width. .. function:: proc isReal(e) param Returns ``true`` if the argument is a ``real`` type or value, of any width. .. function:: proc isImag(e) param Returns ``true`` if the argument is an ``imag`` type or value, of any width. .. function:: proc isComplex(e) param Returns ``true`` if the argument is a ``complex`` type or value, of any width. .. function:: proc isString(e) param Returns ``true`` if the argument is a string or the ``string`` type. .. function:: proc isBytes(e) param Returns ``true`` if the argument is a bytes or the ``bytes`` type. .. function:: proc isEnum(e) param Returns ``true`` if the argument is an ``enum`` type or value, of any width. .. function:: proc isClass(e) param Returns ``true`` if the argument is a class type or value that is not an ``extern`` class, or when the argument is ``nil``. .. function:: proc isRecord(e) param Returns ``true`` if the argument is a record type or value. .. function:: proc isUnion(e) param Returns ``true`` if the argument is a union type or value. .. function:: proc isTuple(e) param Returns ``true`` if the argument is a tuple type or value. .. function:: proc isRange(e) param Returns ``true`` if the argument is a range type or value. .. function:: proc isDomain(e) param Returns ``true`` if the argument is a domain or a domain type. .. function:: proc isArray(e) param Returns ``true`` if the argument is an array or an array type. .. function:: proc isDmap(e) param Returns ``true`` if the argument is a domain map or a domain map type. .. function:: proc isSync(e) param Returns ``true`` if the argument is a ``sync`` type or a ``sync`` variable. .. function:: proc isSingle(e) param Returns ``true`` if the argument is a ``single`` type or a ``single`` variable. .. function:: proc isAtomic(e) param Returns ``true`` if the argument is an ``atomic`` type or an ``atomic`` variable. .. function:: proc isHomogeneousTuple(e) param Returns ``true`` if the argument is a homogeneous tuple. The argument must be a tuple or any type. .. function:: proc isGeneric(e) param Returns ``true`` if the argument is a generic type, and ``false`` otherwise. .. function:: proc isOwnedClass(e) param Returns ``true`` if the argument is an ``owned`` class type. .. function:: proc isSharedClass(e) param Returns ``true`` if the argument is a ``shared`` class type. .. function:: proc isUnmanagedClass(e) param Returns ``true`` if the argument is a ``unmanaged`` class type. .. function:: proc isBorrowedClass(e) param Returns ``true`` if the argument is a ``borrowed`` class type. .. function:: proc isNilableClass(e) param Returns ``true`` if the argument is a class type that can store ``nil``. .. function:: proc isNonNilableClass(e) param Returns ``true`` if the argument is a class type that cannot store ``nil``. .. function:: proc isCopyable(e) param Returns ``true`` if the argument is a type or an expression of a type that can be copy-initialized and ``false`` otherwise. Note that even if this function returns ``true``, it might be the case that the type only supports copy-initialization from mutable values. :type:`~OwnedObject.owned` is an example of a type with that behavior. See also the specification section :ref:`Copy_Initialization_of_Records`. .. function:: proc isConstCopyable(e) param Returns ``true`` if the argument is a type or an expression of a type that can be copy-initialized from a ``const`` value and ``false`` otherwise. Returns ``false`` for :type:`~OwnedObject.owned` because copy-initialization for that type leaves the source argument storing ``nil``. See also the specification section :ref:`Copy_Initialization_of_Records`. .. function:: proc isAssignable(e) param Returns ``true`` if the argument is a type or expression of a type that can be assigned from another value and ``false`` otherwise. Note that even if this function returns ``true``, it might be the case that the type only supports assignment from mutable values. :type:`~OwnedObject.owned` is an example of a type with that behavior. See also the specification section :ref:`Record_Assignment`. .. function:: proc isConstAssignable(e) param Returns ``true`` if the argument is a type or expression of a type that can be assigned from a ``const`` value and ``false`` otherwise. Returns ``false`` for :type:`~OwnedObject.owned` because assignment for that type leaves the source argument storing ``nil``. See also the specification section :ref:`Record_Assignment`. .. function:: proc isDefaultInitializable(e) param Returns ``true`` if the argument is a type or expression of a type that can be default initialized and ``false`` otherwise. Returns ``false`` for non-nilable class types because these types do not have a default value. See also the specification section :ref:`Default_Values_For_Types`. .. function:: proc toNilableIfClassType(type arg) type If the argument is a class type, returns its nilable version like ``arg?``. Otherwise returns the argument unchanged. .. function:: proc numBits(type t) param where t == bool Returns the number of bits used to store the values of type ``t``. This is available for all numeric types and fixed-width ``bool`` types. It is not available for default-width ``bool``. .. function:: proc numBytes(type t) param Returns the number of bytes used to store the values of type ``t``. This is available for all numeric types and fixed-width ``bool`` types. It is not available for default-width ``bool``. .. function:: proc min(type t) param where isBool(t) Returns the minimum value the type ``t`` can store. ``t`` can be one of the following types, of any width: ``bool``, ``int``, ``uint``, ``real``, ``imag``, ``complex``. When ``t`` is a ``bool`` type, it returns ``false``. When ``t`` is ``real``, ``imag``, or ``complex`` type, it is a non-``param`` function. .. function:: proc max(type t) param where isBool(t) Returns the maximum value the type ``t`` can store. ``t`` can be one of the following types, of any width: ``bool``, ``int``, ``uint``, ``real``, ``imag``, ``complex``. When ``t`` is a ``bool`` type, it returns ``true``. When ``t`` is a ``real``, ``imag``, or ``complex`` type, it is a non-``param`` function. .. method:: proc integral.safeCast(type T: integral): T .. warning:: integral.safeCast() is unstable and its behavior may change in the future The following ``safeCast()`` methods return ``this`` cast to the type ``T``. At present, these halt the program if ``this`` cannot be represented by ``T``, for example ``(-1).safeCast(uint)`` or ``256.safeCast(uint(8))``. These methods perform the minimum number of runtime checks. For example, when casting from ``uint(8)`` to ``uint(64)``, no checks at all will be done. .. method:: proc integral.safeCast(type T: bool) .. warning:: integral.safeCast() is unstable and its behavior may change in the future .. method:: proc bool.safeCast(type T: integral) .. warning:: bool.safeCast() is unstable and its behavior may change in the future .. method:: proc bool.safeCast(type T: bool) .. warning:: bool.safeCast() is unstable and its behavior may change in the future .. function:: proc isCoercible(type from, type to) param Returns ``true`` if the type ``from`` is coercible to the type ``to``, or if ``isSubtype(from, to)`` would return ``true``. See :ref:`Implicit_Conversion_Call`. .. function:: proc isSubtype(type sub, type sup) param Returns ``true`` if the type ``sub`` is a subtype of the type ``sup``. See also :ref:`Subtype`. In particular, returns ``true`` in any of these cases: * ``sub`` is the same type as ``sup`` * ``sub`` is an instantiation of a generic type ``sup`` * ``sub`` is a class type inheriting from ``sup`` * ``sub`` is non-nilable class type and ``sup`` is the nilable version of the same class type .. function:: proc isProperSubtype(type sub, type sup) param Similar to :proc:`isSubtype` but returns ``false`` if ``sub`` and ``sup`` refer to the same type. .. function:: operator <(type a, type b) param .. warning:: < operator is deprecated when comparing types; use isProperSubtype() instead :returns: isProperSubtype(a,b) .. function:: operator <=(type a, type b) param .. warning:: <= operator is deprecated when comparing types; use isSubtype() instead :returns: isSubtype(a,b) .. function:: operator >(type a, type b) param .. warning:: > operator is deprecated when comparing types; use isProperSubtype() instead :returns: isProperSubtype(b,a) .. function:: operator >=(type a, type b) param .. warning:: >= operator is deprecated when comparing types; use isSubtype() instead :returns: isSubtype(b,a)