[1.5.0] Promote ZSTD_c_literalCompressionMode to stable params

[senhuang42]

Promotes ZSTD_c_literalCompressionMode to stable, removes it from the experimental section, and adjusts the rest of the experimentalParams numberings accordingly.

[Cyan4973]

Changing the enum nb of a parameter might lead to some downstream issues.

Some binders in other languages, such as Java,
may not access the enum definition, and use the known integer value directly.
In which case, changing the meaning of this integer can lead to downstream surprises.

Of course, this is a very niche scenario, so I don't anticipate a lot of real-life issues,
but we also have nothing to gain from introducing this disruption.

So I would keep the other numbers "as is", and accept holes in the number scheme.

edit : reading about it again,
it seems you kept the integer value,
but changed instead the associated intermediate enum.
This is milder, since the above scenario (using integer value directly) is properly covered.
Yet, I fail to see a benefit from doing this update of intermediate enum. Is there one ?

[senhuang42]

It was more just a visual decision, so that the whole range of ZSTD_c_experimentalParam[1-n] is represented. But, I can see why it might just be preferable to delete it, since it shouldn't really matter to anyone experimentalParam* wouldn't be consecutive.

[ghost]

Just take this opportunity to make a suggestion.
It's better not to use the same values in ZSTD_cParameter and ZSTD_dParameter.
For example, these two values are both 100:

typedef enum {
    ZSTD_c_compressionLevel=100,
    ...
} ZSTD_cParameter;

typedef enum {
    ZSTD_d_windowLogMax=100, 
    ...
} ZSTD_dParameter;

If an user incorrectly sets the decompression parameter to a compression context, it's very hard to find such bug.

In addition, please create a meta issue for v1.5.0, then the users can know changes and feedback earlier.

[terrelln]

If an user incorrectly sets the decompression parameter to a compression context, it's very hard to find such bug.

We can try to avoid it in the future, but we cannot change the values which are already stable. This will be caught in C++ source code, because an implicit conversion from ZSTD_cParameter to ZSTD_dParameters is disallowed. Additionally, passing -Werror=enum-conversion to clang/gcc will also raise an error for this bug.

[Cyan4973]

The documentation states that The value must be of type ZSTD_literalCompressionMode_e.

This implies that ZSTD_literalCompressionMode_e must also be part of "stable" public API.

[Cyan4973]

Likely a typo:
ZSTD_literalCompressionMode_t => ZSTD_literalCompressionMode_e

[ghost]

This will be caught in C++ source code, because an implicit conversion from ZSTD_cParameter to ZSTD_dParameters is disallowed. Additionally, passing -Werror=enum-conversion to clang/gcc will also raise an error for this bug.

For some language bindings, this may be a problem, especially for dynamic languages.
On the whole, it's not a big problem, just a suggestion for the future.