enum SUModelUnits lacks a member for the new yards unit

[DanRathbun]

SketchUp C API Issue

In 2020 Docs (not yet online) "documentation/sketchup/model_8h.html":
enum SUModelUnits lacks a member for the new yards unit.

---

NOTE (2022-07-31) : See comment below for more information.

The maintained units value constant enumerations for the C API are located in file:
https://extensions.sketchup.com/developers/sketchup_c_api/sketchup/length__formatter_8h.html

[thomthom]

This enum appear to be used by SUModelGetUnits
https://extensions.sketchup.com/developers/sketchup_c_api/sketchup/model_8h.html#a51311ad09f5581f26a55193fd11eaa51

I don't understand why we have a function for that, since the same info is accessed via the options providers.

The values for the options provider includes the new units (in the SDK package).
https://extensions.sketchup.com/developers/sketchup_c_api/sketchup/options__provider_8h.html#a0374fb272f9f2acf0959eeabac3da6f3
(The online docs appear to be out of date. I've logged an issue for that.)

I'm leaning towards deprecating SUModelUnits and SUModelGetUnits as it appear to be redundant. Don't want to bloat SUModel* further by adding functions for area and volume units. SUModelGetUnits is even asymmetrical, no setter.

[DanRathbun]

@thomthom : I don't understand why we have a function (SUModelGetUnits) for that, since the same info is accessed via the options providers.

(Thinking out loud...) Perhaps a fast courtesy shortcut getter requested for some internal use or making importers easier ?

Or ... as in the units options provider documentation ...

Note that LengthUnit will be overridden by LengthFormat if LengthFormat is not set to Decimal. Architectural defaults to inches, Engineering defaults to feet, and Fractional defaults to inches.

... so I wonder if the SUModelGetUnits function is a safe(r) way to get the Length units without knowing the pitfalls of the options provider.

@thomthom : I'm leaning towards deprecating SUModelUnits ...

But I'd think that the members of this enumeration would be used to compare the value received from the units option provider ? ... or are they just integers and coders need to create their own constants to mimic the SUModelUnits enumeration ?

I'm think parity here. The Ruby API has constants for the units values to make code more readable. Shouldn't the C API also ?
EDIT: Actually, I can't find the constants for the Ruby API. (I'd swear they exist?)

[thomthom]

Yea, good point that there should be enums for the units.

For the Ruby API these constants are under the Length class:
https://ruby.sketchup.com/Length.html

But yea, not easy to locate, could benefit from a reference in the options provider documentation.

[sketchupbot]

SKOR-12926

[DanRathbun]

@thomthom ... please note:

Yea, good point that there should be enums for the units.

Your clue about where the Ruby API defined units constants, led me to find the C API units enums:
https://extensions.sketchup.com/developers/sketchup_c_api/sketchup/length__formatter_8h.html

SULengthUnitType enum has already had the yards unit added as SU_LUNIT_YARD.

But yea, not easy to locate, could benefit from a reference in the options provider documentation.

Yes the table of ordinal values at the bottom of the SUOptionsProviderGetValue() function doc, could get another column listing the enum constants.

I'm leaning towards deprecating SUModelUnits and SUModelGetUnits as it appear to be redundant. Don't want to bloat SUModel* further by adding functions for area and volume units. SUModelGetUnits is even asymmetrical, no setter.

I would say to deprecate the SUModelUnits enumeration with a note to use the newer SULengthUnitType enumeration, and leave the SUModelGetUnits() function as is. (It is probably used by importers or 3D Warehouse like sites to more easily get the model length units for display.)

You could add a note to the SUModelGetUnits() function documentation for consumers to use the SUModelGetOptionsManager(), SUOptionsManagerGetOptionsProviderByName() and SUOptionsProviderRef struct to access more detailed units settings.

---

So if you follow this advice for this issue, the bug and parity labels can be removed and replaced with a documentation label.

?