# c-struct

Definition: | struct identifier "<c-string>" end struct -- or -- struct|identifier variable ( ';' | ('='|':=') ( new() | expr ) ) [ ',' ... ] -- or -- bool res = struct|identifier(object o)
Description: | For interfacing to C, the field definitions should be defined using a single C string, usually triple-quoted, copied verbatim from eg MSDN or some .h file. Note that embedded TCHAR[] and similar fields are not handled by struct’s use of cffi.e. The field definitions may contain comments, however they must be C-style, ie/eg `// comment` or `/* comment */`, not `-- comment`. This allows similar mechanisms for creation and dot-notation access of fields, however passing the final structure to a C function now needs to use the struct_mem() routine, but is otherwise unchanged.
pwa/p2js: | Not supported.
Example: |
    struct rect """
    typedef struct _RECT {
      LONG left;
      LONG top;
      LONG right;
      LONG bottom;
    } RECT, *PRECT;
    """
    end struct
    rect q = new({10,10,350,200}),
         r = new()
    r.left = 10     --\   equivalent to using the
    r.top = 10      -- }   {10,10,350,200} above
    r.right = 350   -- }  and/or m = allocate(16)
    r.bottom = 200  --/    & poke4(m+0/4/8/12,..).

    -- then eg c_proc(xFillRect,{hDC,struct_mem(r|q)|m,hBrush})
The above definition of RECT was originally copied completely unaltered from http://msdn.microsoft.com/en-us/library/dd162897. Using a C string allows you to specify byte/char/uchar/short/ushort/int/uint/long/ulong/long long, etc as well as things like unions and nested [C] structs, without the tedious and error-prone manual conversion to machine_word()-specific offsets and sizes, however the actual routine call remains via c_func() or c_proc(), although you can also still use define_cffi_func() and define_cffi_proc(). Typically I would expect any interface to C routines to be written once in a separate re-usable library component and pretty much never looked at again (sort of like a few things in builtins and Other Libraries, not that any use c-structs yet), that is rather than scattered thoughout the source code of an application (or several). As such, the slightly-nicer syntax for accessing fields is probably not really all that helpful, in hindsight, although it has long been a fairly regular request.
Implementation: | As per struct, which goes on to use the pre-existing cffi.
Technicalia | The pre-existing cffi library has not been significantly altered, this (dot notation) is just a thin wrapper to it. These C-structs are utterly static and cannot be abstract, extended, or dynamic (and you can blame C for that, not Phix!). They normally only ever contain atoms and can only be embedded using the verbatim copied C syntax (ditto). No attempt has been made to support methods (/call_backs) beyond a simple store, and apart from new(), dot notation, and struct_mem(), much remains unaltered - see the original cffi documentation for more details.