CONCEPT
        structs

INTRODUCTION
        structs are, next to arrays and mappings, a way to group a
        collection of value together.
        
        A struct holds a fixed number of values, called 'members', and
        allows to access them by their given name. The name is resolved
        when the LPC code is compiled, making struct member access as fast
        as array member access.

        structs are passed by reference.


DEFINITION
        A new struct type has to be defined at the top level of an
        object. For example

            struct Foo {
              int        one, *two;
              struct Bar three;
            };

        defines the new struct 'Foo' with three members: integer 'one',
        integer array 'two', and struct Bar 'three'

        It is possible to 'inherit' structs from each other. Given above
        definition of struct Foo, the following definition

            struct Quux (Foo) {
              int four;
            };

        is equivalent to the definition

            struct Quux {
              int        one, *two;
              struct Bar three;
              int four;
            };


        The usual visibility modifiers apply, e.g.

            protected struct Bang {...};

        
        struct definitions are promoted through inheritance like functions,
        with the difference that all structs live in the same flat namespace.
        This means: a struct defined in a program is visible in _all_
        inherited programs, regardless of how deep the inheritance is
        nested.  This also means that in one program there must not be
        two structs, inherited or not, with the same name.


        To declare a struct without defining it, write:

            struct Quux;

        This notation is useful if you have two structs referencing
        each other:

            struct Quux;

            struct Bar {
              struct Quux quux;
            };
            struct Quux {
              struct Bar bar;
            };


USAGE
        To use a struct, its definition must be visible - either because it
        is defined in the object compiled, or it has been inherited.


        A variable to hold a struct is defined like this:

            struct Foo var;

        and similar for function arguments:

            void fun (struct Foo arg)


        A struct member is accessed using the -> operator:

            struct Foo var = ...;

            var->one = 1;


        Literal structs are written using (<>) as delimiters:

            (<Foo>)
                creates an empty instance of struct Foo

            (<Foo> 1, ({ 2 }), bar)
                creates an instance of struct Foo, and assigns 1 to member
                'one', ({ 2 }) to member 'two', and the content of variable
                bar to member 'three'.

            (<Foo> two: ({ 2 }) )
               creates an instance of struct Foo which is all empty except
               for member 'two' which is assigned the value ({ 2 }).

        It is not possible to use both named and unnamed initializers
        in the same literal.


USAGE IN CLOSURES
         Due to the special nature of structs (see below), it is
         possible only to create anonymous structs in closures using
         the operator #'(< :

           ({ #(<, 1, 2, 3 })

         creates a struct with the three members 1, 2, 3. To access
         these members within a closure, one has to use the #'[]
         operator.


MISCELLANEOUS
         structs are mostly a compile-time convenience in that the
         struct names and member names are available only to the
         LPC compiler. At runtime, structs are a special kind of array
         with a fixed number of elements (which also means that
         runtime error messages will talk about 'indexing' instead of
         'member lookup').

         Internally structs can be identified by the ID string
         returned from get_type_info(). However, do not rely on
         a particular format of this string!

         Support for structs is signaled by the macro __LPC_STRUCTS__.


HISTORY
        structs were fully implemented first in LDMud 3.3.246.


SEE ALSO
        mappings(LPC), get_type_info(E)
