.. default-domain:: chpl

.. module:: MultiTypeSymEntry

MultiTypeSymEntry
=================
**Usage**

.. code-block:: chapel

   use MultiTypeSymEntry;


or

.. code-block:: chapel

   import MultiTypeSymEntry;

.. data:: const genLogger = new Logger(logLevel, logChannel)

.. enum:: enum SymbolEntryType { AbstractSymEntry, TypedArraySymEntry, PrimitiveTypedArraySymEntry, ComplexTypedArraySymEntry, GenSymEntry, SegStringSymEntry, CompositeSymEntry, GeneratorSymEntry, AnythingSymEntry, UnknownSymEntry, None }

   *
   * Internal Types we can use to build our Symbol type hierarchy.
   * We are making the types a little more concrete than using Strings
   

   .. enumconstant:: enum constant AbstractSymEntry

   .. enumconstant:: enum constant TypedArraySymEntry

   .. enumconstant:: enum constant PrimitiveTypedArraySymEntry

   .. enumconstant:: enum constant ComplexTypedArraySymEntry

   .. enumconstant:: enum constant GenSymEntry

   .. enumconstant:: enum constant SegStringSymEntry

   .. enumconstant:: enum constant CompositeSymEntry

   .. enumconstant:: enum constant GeneratorSymEntry

   .. enumconstant:: enum constant AnythingSymEntry

   .. enumconstant:: enum constant UnknownSymEntry

   .. enumconstant:: enum constant None

.. class:: AbstractSymEntry

   *
   * This is the root of our SymbolTable Entry / Typing system.
   * All other SymEntry classes should inherit from this class
   * or one of its ancestors and ultimately everything should
   * be assignable/coercible to this class.
   * 
   * All subclasses should set & add their type to the `assignableTypes`
   * set so we can maintain & determine the type hierarchy.
   

   .. attribute:: var entryType: SymbolEntryType

   .. attribute:: var assignableTypes: set(SymbolEntryType)

   .. attribute:: var name = ""

   .. method:: proc init()

   .. method:: proc init(input)

   .. method:: proc setName(name: string)

      
      Sets the name of the entry when it is added to the Symbol Table
      

   .. method:: proc isAssignableTo(entryType: SymbolEntryType): bool

      *
      * This can be used to help determine if a class can be
      * assigned / coerced / cast to another one in its hierarchy.
      

   .. method:: proc getSizeEstimate(): int

      *
      * This is a hook for the ServerConfig.overMemLimit procedure
      * All concrete classes should override this method
      

   .. method:: proc entry__str__(thresh: int = 1, prefix: string = "", suffix: string = "", baseFormat: string = ""): string throws

      *
      * Formats and returns data in this entry up to the specified threshold. 
      * Arrays of size less than threshold will be printed in their entirety. 
      * Arrays of size greater than or equal to threshold will print the first 3 and last 3 elements
      *
      * :arg thresh: threshold for data to return
      * :type thresh: int
      *
      * :arg prefix: String to prepend to the front of the data string
      * :type prefix: string
      *
      * :arg suffix: String to append to the tail of the data string
      * :type suffix: string
      *
      * :arg baseFormat: String which represents the base format string for the data type
      * :type baseFormat: string
      *
      * :returns: s (string) containing the array data
      

.. function:: proc toSymEntry(gse: borrowed GenSymEntry, type etype, param dimensions = 1)

   Casts a GenSymEntry to the specified type and returns it.
   
   :arg gse: generic sym entry
   :type gse: borrowed GenSymEntry
   
    :arg etype: type for gse to be cast to
    :type etype: type
   

.. class:: GenSymEntry : AbstractSymEntry

    
   This is a dummy class to avoid having to talk about specific
   instantiations of SymEntry. 
   GenSymEntries can contain multiple SymEntries, but they represent a singular object.
   For example, SegArray contains the offsets and values array, but only the values are 
   considered data.
   

   .. attribute:: var dtype: DType

   .. attribute:: var itemsize: int

   .. attribute:: var size: int = 0

   .. attribute:: var ndim: int = 1

   .. attribute:: var shape: string = "[0]"

   .. method:: override proc getSizeEstimate(): int

   .. method:: proc toSymEntry(type etype, param dimensions = 1)

      Cast this `GenSymEntry` to `borrowed SymEntry(etype)`
      
      This function will halt if the cast fails.
      
      :arg etype: `SymEntry` type parameter
      :type etype: type
      

   .. method:: override proc entry__str__(thresh: int = 1, prefix: string = "", suffix: string = "", baseFormat: string = ""): string throws

       
      Formats and returns data in this entry up to the specified threshold. 
      Arrays of size less than threshold will be printed in their entirety. 
      Arrays of size greater than or equal to threshold will print the first 3 and last 3 elements
      
        :arg thresh: threshold for data to return
        :type thresh: int
      
        :arg prefix: String to prepend to the front of the data string
        :type prefix: string
      
        :arg suffix: String to append to the tail of the data string
        :type suffix: string
      
        :arg baseFormat: String which represents the base format string for the data type
        :type baseFormat: string
      
        :returns: s (string) containing the array data
      

.. class:: SymEntry : GenSymEntry

   Symbol table entry 

   .. attribute:: type etype

      
      generic element type array
      etype is different from dtype (chapel vs numpy)
      

   .. attribute:: param dimensions: int

      
      number of dimensions, to be passed back to the `GenSymEntry` so that
      we are able to make it visible to the Python client
      

   .. attribute:: var tupShape: dimensions*int

      
      the actual shape of the array, this has to live here, since GenSymEntry
      has to stay generic
      

   .. attribute:: var a = makeDistArray(...tupShape, etype)

      
      'a' is the distributed array whose value and type are defined by
      makeDist{Dom,Array}() to support varying distributions
      

   .. method:: proc aD

      Removed domain accessor, use `a.domain` instead 

   .. attribute:: var max_bits: int = -1

      only used with bigint pdarrays 

   .. method:: proc init(a: [?D] ?etype) where MyDmap != Dmap.defaultRectangular && a.isDefaultRectangular()

      
      This init takes an array whose type is defaultRectangular (convenience
      function for creating a distributed array from a non-distributed one)
      
      :arg a: array
      :type a: [] ?etype
      

   .. method:: proc deinit()

      
      Verbose flag utility method
      

   .. method:: override proc entry__str__(thresh: int = 6, prefix: string = "[", suffix: string = "]", baseFormat: string = "%\?"): string throws

      
      Formats and returns data in this entry up to the specified threshold. 
      Arrays of size less than threshold will be printed in their entirety. 
      Arrays of size greater than or equal to threshold will print the first 3 and last 3 elements
      
          :arg thresh: threshold for data to return
          :type thresh: int
      
          :arg prefix: String to pre-pend to the front of the data string
          :type prefix: string
      
          :arg suffix: String to append to the tail of the data string
          :type suffix: string
      
          :arg baseFormat: String which represents the base format string for the data type
          :type baseFormat: string
      
          :returns: s (string) containing the array data
      

.. function:: proc createSymEntry(shape: int ..., type etype) throws

.. function:: proc createSymEntry(in a: [?D] ?etype, max_bits = -1) throws

.. class:: CompositeSymEntry : AbstractSymEntry

   
   Base class for any entry that consists of multiple SymEntries that have varying types.
   These entries are related, but do not represent a single object.
   For Example, group by contains multiple SymEntries that are all considered part of the dataset.
   

   .. attribute:: var ndim: int = 1

   .. attribute:: var size: int = 0

   .. method:: proc init(len: int = 0)

.. function:: proc createTypedSymEntry(len: int, type t) throws

   *
   * Factory method for creating a typed SymEntry and checking mem limits
   * :arg len: the number of elements to allocate
   * :type len: int
   * 
   * :arg t: the element type
   * :type t: type
   

.. class:: SegStringSymEntry : GenSymEntry

   .. attribute:: type etype = string

   .. attribute:: var offsetsEntry: shared SymEntry(int, 1)

   .. attribute:: var bytesEntry: shared SymEntry(uint(8), 1)

   .. method:: proc init(offsetsSymEntry: shared SymEntry(int), bytesSymEntry: shared SymEntry(uint(8)), type etype)

   .. method:: override proc getSizeEstimate(): int

   .. method:: override proc entry__str__(thresh: int = 1, prefix: string = "", suffix: string = "", baseFormat: string = ""): string throws

      *
      * Formats and returns data in this entry up to the specified threshold. 
      * Arrays of size less than threshold will be printed in their entirety. 
      * Arrays of size greater than or equal to threshold will print the first 3 and last 3 elements
      *
      * :arg thresh: threshold for data to return
      * :type thresh: int
      *
      * :arg prefix: String to prepend to the front of the data string
      * :type prefix: string
      *
      * :arg suffix: String to append to the tail of the data string
      * :type suffix: string
      *
      * :arg baseFormat: String which represents the base format string for the data type
      * :type baseFormat: string
      *
      * :returns: s (string) containing the array data
      

.. class:: GeneratorSymEntry : AbstractSymEntry

   .. attribute:: type etype

   .. attribute:: var generator: randomStream(etype)

   .. attribute:: var state: int

   .. method:: proc init(generator: randomStream(?etype), state: int = 1)

.. function:: proc toGenSymEntry(entry: borrowed AbstractSymEntry) throws

   *
   * Helper proc to cast AbstrcatSymEntry to GenSymEntry
   

.. function:: proc toCompositeSymEntry(entry: borrowed AbstractSymEntry) throws

   *
   * Helper proc to cast AbstractSymEntry to CompositeSymEntry
   

.. function:: proc toSegStringSymEntry(entry: borrowed AbstractSymEntry) throws

   *
   * Helper proc to cast AbstractSymEntry to SegStringSymEntry
   

.. function:: proc toGeneratorSymEntry(entry: borrowed AbstractSymEntry, type t) throws

   *
   * Helper proc to cast AbstractSymEntry to GeneratorSymEntry
   

.. function:: proc getArraySpecFromEntry(entry: borrowed AbstractSymEntry) throws

   *
   * Temporary shim to ease transition to Typed Symbol Table Entries.
   * This attempts to retrieve the Dtype, size/array-length, and itemsize from a SymbolTable
   * entry if the entry type supports it. Returns default tuple of valuse otherwise.
   * 
   * :arg entry: AbstractSymEntry or descendant
   * :type entry: borrowed AbstractSymEntry
   * :retruns: tuple of (dtype, entry.size, entry.itemsize)
   * 
   * Note: entry.size is generally the number of elements in the array
   *       and is more synonymous with length
   

.. function:: proc tupShapeString(shape): string

   
   Create a string to represent a JSON tuple of an array's shape
   

.. function:: proc tupShapeString(val: int, ndim: int): string