Re: [PATCH] pk_struct interface for libpoke.

[Jose E. Marchesi]

Hi Kostas.

    Hello, this is the pk_struct* interface for libpoke.


Thanks for the patch.
Please see some comments below.
    
    From: kostasch <sdi1600195@di.uoa.gr>
    Date: Thu, 2 Jul 2020 16:32:36 +0300
    
Please include the changelog entry in the commit message.  See other
commits for examples.

    diff --git a/libpoke/libpoke.h b/libpoke/libpoke.h
    index b44d6715..5f3338c2 100644
    --- a/libpoke/libpoke.h
    +++ b/libpoke/libpoke.h
    @@ -488,6 +488,81 @@ pk_val pk_offset_magnitude (pk_val val);
     
     pk_val pk_offset_unit (pk_val val);
     
    +/* Structs. */
    +
    +/* Build and return a poke struct.
    +   
    +   NFIELDS is an uint<64> PK value specifying the number of fields

Please talk about 'Poke values' instead of 'PK values'.

    +   in the struct.  This can be uint<64>0 for an empty struct.
    +
    +   TYPE is a type PK value specifying the type of the struct.
    +
    +   The fields and methods in the created struct are initialized to
    +   PK_NULL.*/
    +
    +pk_val pk_make_struct (pk_val nfields, pk_val type);
    +
    +/* Get the number of fields of a struct. */
    +
    +pk_val pk_struct_nfields (pk_val sct);
    +
    +/* Get the bit-offset of the field of a struct, relative to the
    +   beginning of the struct.
    +
    +   SCT is the struct value.
    +   IDX is the index of the field in the struct.
    +
    +   The returned bit-offset is an uint<64>.  */
    +
    +pk_val pk_struct_field_boffset (pk_val sct, uint64_t idx);
    +
    +/* Set the bit-offset of the field of an struct, relative to the
    +   beginning of the struct.
    +
    +   ARRAY is the struct value.
    +   
    +   IDX is the index of the field in the struct.
    +   
    +   BOFFSET is an uint<64> value with the bit-offset of the field.  */
    +
    +void pk_struct_set_field_boffset (pk_val sct, uint64_t idx, pk_val offset);

Please use 'boffset' for the argument, instead of `offset'.  This makes
it much more clear when we are talking about offset values or uint<64>
values representing number of bits.

    +
    +/* Get the NAME of the struct field.
    +   
    +   SCT is the struct value.
    +   
    +   IDX is the index of the field in the struct. */
    +
    +pk_val pk_struct_field_name (pk_val sct, uint64_t idx);

What happens if the passed IDX is invalid?  What value is returned then?
This should be documented in the function's prototype.

Ditto for the functions below that get indexes.