nested_struct_copy

nested_struct_copy(d, s, opt, parent)

nested_struct_copy() - Copies values from one nested struct to another.

ds = nested_struct_copy(d, s)
ds = nested_struct_copy(d, s, opt)
ds = nested_struct_copy(d, s, opt, parent)

Copy values from a source struct s to a destination struct d in a nested, recursive manner. That is, the value of each field in s is copied directly to the corresponding field in d, unless that value is itself a struct, in which case the copy is done via a recursive call to nested_struct_copy().

Inputs:

• d (struct) – the destination struct that values are copied to

• s (struct) – the source struct containing the values to be copied from

• opt (struct) – (optional) options struct controlling copy behavior, with fields:

  • check — check that field name is valid, by looking for it in opt.valid_fields, before copying

    • 0 — (default) do not do any field name checking

    • 1 — fatal error if s contains an invalid field name

    • -1 — skip any invalid fields in s

  • copy_mode — how to handle assignment of fields that are structs

    • '' — (default) recursive call to nested_struct_copy()

    • '=' — direct assignment, d.<field> = s.<field>

    • @<function> — pointer to a function to be called with field from s, returning field to assign to d, d.<field> = <function>(s.<field>)

  • valid_fields — (default = d ) struct containing the heirarchy of all of (and only) the valid field names (field values are ignored)

  • exceptions — a struct array, with the following fields, defining exceptions to the top-level options

    • name — name (can be multi-level) of field to which exception applies

    • check — same as opt.check, only for specified field

    • copy_mode — same as opt.copy_mode, only for specified field

    • valid_fields — same as opt.valid_fields, only for specified field

• parent (cell array) – (optional) parent field names used internally by nested_struct_copy() with recursive calls to allow checking of multi-level field names in exceptions, e.g. when called recursively to assign the field s.info.address.home, the value of parent would be {'info', 'address'}.

Output:

ds (struct) – the combined destination struct

Examples

See t_nested_struct_copy() source code for numerous examples.

To Do:

• Finish example.

• Implement an error that passes back the full field string of an invalid field so that :func:`mpoption` can refer to it as option foo.