Deprecate get_dims and set_dims!

[musm]

Base.size is what people will likely want instead of these methods.

I figured it would be a good idea to either remove these methods or rename them. Internally, we don't use them after upgrading Base.size

@jmert thoughts on this change (also open to other suggestions you might have in leu of these changes)

[musm]

we might want to move these to api_helpers ?

[jmert]

I agree with the general idea, but a few thoughts:

1. The asymmetry in get_simple_extent_dims versus set_extent seems off to me. I know the h5d_set_extent interface is what's being used, but there's also the h5s_set_extent_simple which is closer (though still annoyingly swaps the order of "simple" and "extent"...). Maybe we should just provide both setters (first acting on dataspace and second acting on actual datasets)? As mid-level routines, we could choose to normalize naming a bit, too — provide get_simple_extent_dims and set_simple_extent_dims for the dataspace operations?
2. I'd say rather than moving to api_helpers.jl which right now is pretty focused on just low-level wrappings of the low-level api, a new midlevel.jl (name TBD) would be nice — I'd still like to see src/HDF5.jl broken up more to more clearly separate the high-level interface from the mid-level interface, so maybe this will just be the first set of functions to make the move. (?)

[musm]

@jmert Updated the PR as per comment. Is that what you were more thinking of?

[jmert]

Suggested change

	maximum_size = isnothing(max_dims) ? C_NULL : hsize_t[reverse(max_dims)...]
	maximum_size = isnothing(max_dims) ? C_NULL : [reverse(max_dims .% hsize_t)...]

to support using -1 to set unlimited max size.

(Unfortunately, using max_dims::Dims makes this incompatible with unlimited sizes given as (HDF5.H5S_UNLIMITED,) ... not sure what to do about that, but it's not a regression from what set_dims! was doing already.)

[musm]

Yeah I think this will take some more careful thinking on how to address setting H5S_UNLIMITED more broadly.

[musm]

I think the simplest thing is to just document the correct way to set an unlimited dimension is to set it to -1 and not use the internal HDF5.H5S_UNLIMITED constant? A little more intrusive would be to set HDF5.H5S_UNLIMITED=-1, but I think that would require enforcing truncation to which ever inter api call excepts HDF5.H5S_UNLIMITED since cconvert to hsize_t would throw an error.

[jmert]

I agree that it's mostly a documentation issue — low-level API will want HDF5.H5S_UNLIMITED (and should remain as -1 % hsize_t to agree with the C header literal value), and everything in mid-level and high-level API will instead use -1 and do the data type conversions. I think so far we just don't have the documentation to make that clear.

[jmert]

@jmert Updated the PR as per comment. Is that what you were more thinking of?

Yeah, this is the direction I was thinking of. Just some minor comments, but I agree with the approach as a whole.