string_t: extremely confusing methods names: string_clean and string_clear about mlib

[P-p-H-d]

I agree that the suffix _clear and _clean are too similar and as such are too confusing.

I have a look at the suffix used by different C library (both containers, numbers). Here is what I get:

NAME	Constructor	Destructor	Empty Object
M*LIB	_init	_clear	_clean
C++	na	na	.clear
C11	_init	_destroy	na
POSIX	_init	_destroy	na
GMP	_init	_clear	_set_ui
MPFR	_init	_clear	_set_nan
MPC	_init	_clear	_set_nan
LIBBF	_init	_delete	na
GLIB	_alloc	_free	na
CMC	_new	_free	_clear
Collection C	_new	_destroy	na
CTL	_init	_free	_clear
KLIB	_init	_destroy	na
LIBDYNAMIC	_construct	_destruct	clear
LIBLFDS	_init	_cleanup	na
SRT	_alloc	_free	_clear / _reset
QLIBC	none	_free	_clear
UTHASH	_new / _init	_free / _done	_clear
SDS	_new	_free	na
BSTRLIB	_fromcstr	_destroy	na
SQLITE3	_initialize	_shutdown	na

I don't see any winner for the pair constructor / destructor, whereas the "clear" suffix is the winner for emptying the container.

Also, as a subjective note, I found the suffix destroy as too negative, the suffix free as unbalanced (it is associated to an _alloc), and clear/clean far from perfect (confusing with empty object).
Some people also use terminate as the opposite suffix of _init.

This opinion is comforted when I look at theses threads:

https://gist.github.com/maxtruxa/b2ca551e42d3aead2b3d
https://softwareengineering.stackexchange.com/questions/163004/what-is-the-opposite-of-initialize-or-init

The opposite of _init doesn't make consensus.
Changing the _clear suffix would have a lot of impact on the user code: nearly all user code uses such destructor. In comparison, the _clean suffix is much less used.

Therefore, what I propose is to rename _clean suffix and CLEAN operator in _reset suffix and RESET operator. This will avoid the confusion of _clear & _clean. Moreover, _reset is as good as _clean for an operation that empty the container (reset it).

This implies the following steps:

• Create the _reset suffix of the functions.
• Use then in the OPLIST.
• Mark the _clean suffix as obsolete
• Rename the operator CLEAN in RESET (this will break API compatibility but few user programs should use directly this operator of the oplist - I hope).
• Release this version of M*LIB.
• Remove the _clean suffix functions.

[skotopes]

Sounds awesome, should we wait for you or do changes and make PR?

[P-p-H-d]

should we wait for you or do changes and make PR?

I already performed the first step of renaming of _clean into _reset in master (and making _clean a deprecated function).

[P-p-H-d]

The _clean methods have been removed from the master branch.

[skotopes]

Awesome, thank you very much )