SYNOPSIS
        mixed to_struct(mixed *|mapping data)
        mixed to_struct(mixed *|mapping data, struct template)
        mixed to_struct(struct data)
        mixed to_struct(struct data, struct template)

DESCRIPTION
        The given array, mapping or struct <data> is returned as a struct.
        If a <template> struct is given, the returned struct is of the same
        type. Without a template, an anonymous struct is returned in case of
        arrays and mappings and in case of structs <data> is returned
        unchanged.

        If <data> is an array, its elements are assigned in order to the
        resulting struct. For an anonymous struct, all elements of <data>
        are assigned, for a templated struct only as many as fit into
        the struct.

        If <data> is a mapping and no template is given, the resulting
        anonymous struct contains all elements from <data> with a string
        key; the key name is used as struct member name.

        If <data> is a mapping and a template is given, the struct
        member names are used as keys for lookups in <data>; the found
        data is assigned to the struct members.

        If <data> is a struct and a template is given, a struct of the type
        of template is created and all members from <data> are copied to the
        new struct, which exist in both structs. This conversion is only
        allowed between a struct and one of its base structs or a base struct
        and one of its children. Otherwise an error is raised.

        Neither <data> nor <template> will be changed in this process - the
        result is a new struct value. The actual value of <template> does not
        matter, only its type.

        Since the returned struct can't be known at compile time, the
        efun is declared to return 'mixed'.

HISTORY
        Introduced in LDMud 3.3.250 .
        LDMud 3.3.344 added the template argument.
        LDMud 3.3.433 added the conversion from mappings.
        LDMud 3.3.720 added the conversion of structs into another struct.

SEE ALSO
        to_array(E), to_string(E), mkmapping(E), structs(LPC)
