Patch title: Release 94 bulk changes
Abstract:
File: /pliant/language/compiler/type/type.page
Key:
    Removed line
    Added line
title "Types"

para
  [A type is also a simple Pliant data that can be built, transformed, and even deleted (with care)[lf]]
  [The interface for dealing with types is a bit rough (low level), but is not intended for the programmers mainstream ...[lf]]
  [To create a new data type with high level mainstream functions, please read documentation ] ; link "here" "../concept/type"


para
  listing
    method `t ¤name -> `n
      arg Type `t ; arg Str `n
  [The name of the type]

para
  listing
    method `t ¤size -> `s
      arg Type `t ; arg Int `s
  [Returns the size (in bytes) of the root part of objects with type 't']

para
  listing
    method `t ¤bitsize -> `s
      arg Type `t ; arg Int `s
  [Returns the size (in bits) of the root part of objects with type 't']

para
  listing
    method `t ¤flags -> `i
      arg Type `t ; arg Int `i
  [Returns an integer which is in fact an array of bits describing various properties of the type.]

para
  [These are a few constants that can be used to check the type properties:]
  table columns 2
    cell fixed:[type_atomic] ; cell [Data with that type can be stored in the processor registers: their size is the same as Int, and no computation is required to initialize or destroy an object with that type.]
    cell fixed:[type_scalar] ; cell [No computation is required to initialize or destroy objects with that type]
    cell fixed:[type_packed] ; cell [The fields of that type are packed: there is no space inserted between fields in order to improve alignment, and the fields are stored in the right order.]
    cell fixed:[type_do_not_copy] ; cell [The objects of such a type cannot be copied (for example streams or types)]
    cell
      [other flags]
    cell
      [All the constants are defined in ] ; link "struct.c" "../../c_source/struct.c" ; [ and have names such as type_flag_...[lf]]

  [So if you want to check if a type 't' is scalar, you'll write something like:]
  listing
    if (t:flags .and. type_scalar)<>0
      ...

para
  listing
    method `t ¤nb_fields `i -> `n
      arg Type `t ; arg Int `n
  [Returns the number of fields of the type (0 for low level types).]

para
  listing
    method `t ¤field -> `f
      arg Type `t ; arg_C TypeField `f
  [Returns a pointer to the selected field.]
  
para
  listing
    method `t ¤define_field -> `type `name
      arg_rw Type `t ; arg Type `type ; arg Str `name
  [Add a new field to the type.]

para
  listing
    method `t ¤terminate_fields
      arg_rw Type `t
  [If you build the type calling 'define_field', then you must call 'terminate_fields' once at the end in order to let Pliant compute the various fields' offsets.]

para
  listing
    ¤generate_string_functions `type1 `type2 ...
      arg_rw Type `type1 `type2
  [When you define new data types that are simple structures (set of fields), you can use this function in order to automaticaly generate the 'from string' and 'to string' functions for these new types.] ; highlight " added in release 32"


para
  listing
    method `t ¤position -> `p
      arg Type `t ; arg Str `p
  [A string specifying where the type has been defined (module name, line and column number)]

para
  [A data with type 'TypeField' is a simple structure:]
  listing
     type TypeField
       field Link:Type type
       field Int offset
       field Str name

para
  listing
    method `t ¤generic_level -> `l
      arg Type `t ; arg_C Int `l
  [The ] ; link "generic level" "../concept/generic" ; [ of the type.]

para
  listing
    method `t ¤maybe -> `l
      arg Type `t ; arg List `l
  [List of all the types that a generic type may be.]

para
  listing
    method `t ¤build_instance `a
      arg Type `t ; arg address `a
  [Builds a new instance of the type at the provided address.]

para
  listing
    method `t ¤destroy_instance `a
      arg Type `t ; arg address `a
  [Destroys the instance of the type at the provided address.[lf]]
  ['build_instance' and 'destroy_instance' are low level functions that should not be called by mainstream programs.]

para
  listing
    method `t ¤copy_instance `src `dest
      arg Type `t ; arg address `src `dest
  [Copies an instance of the type.[lf]]

para
  listing
    method `t ¤real_data_type `t2
      arg Type `t ; arg_C Type `t2
  [If 't' is a kind of pointer, this function will return the type of the real object reached by dereferencing it. On the other hand, if 't' is a the type of a real object, on return 't2' will point 't']

para
  listing
    method `t ¤maybe `atype
      arg_rw Type `t ; arg Type `atype
  [Specifies that 't' is a generic data type and that one of the possible real types is 'atype']