stb
stb copied to clipboard
stb_lib proposal (replacing stb.h)
Overview
I am proposing to replace stb.h with a new smaller library, stb_lib.h. I am looking for feedback from people currently using stb.h.
Background
stb.h wasn't originally intended for public consumption; it is a collection of things I use for myself to make my life programming easier, and includes a large number of things I added experimentally to see if having them would make my life easier (most of which I never use).
Some things in stb.h make it easy to shoot yourself in the foot; for example a number of convenient functions like stb_sprintf
and stb_fopen
are not thread-safe. Use of the stb_arr array type is subtle because if the underlying pointer is reallocated, the stb_arr itself changes values. Because I wrote them and know about the limitations, these issues generally don't bite me.
At some point, I went ahead and released stb.h for public consumption, despite the caveats. As expected, it didn't see as large uptake as other libraries.
Plan
I am proposing to condense stb.h into a new library, stb_lib.h, which will eliminate 75% of stb.h, hopefully elimintating parts nobody uses.
This will be done primarily to make maintenance easier, as stb.h currently accounts for more than one-quarter of the total lines of code in the released stb libraries. See https://github.com/nothings/stb/issues/540 for an example of the maintenance issues.
stb.h itself will be deprecated and moved out of the main support libraries. It will remain in the tree and I may continue to use it myself, or I may refactor the deleted stuff into a new lib for my personal use, unclear.
Your role
I would like feedback on whether anything proposed for elimination is actually used by people in the wild. In most cases these are things I don't use very much personally, though in some cases (e.g. stb_fopen
) they are important functions but they are partially broken so risky if used by others (e.g. stb_fopen
isn't thread-safe).
Proposed eliminations
- certain types & macros
- all symbols without
stb_
prefixes- sized-integer types
uint16
,int32
, etc. -
min
,max
-
swap
-
M_PI
- sized-integer types
- these might become available again if you #define an extra symbol
- all symbols without
- miscellaneous types
-
stb_uintptr
,stb_uinta
-
- malloc-related things
- hierarchical allocator
-
stb_malloc
,stb_realloc
,stb_free
etc. -
stb_malloc_leaf
,stb_reassign
etc.
-
-
STB_FASTMALLOC
-
STB_MALLOC_WRAPPER
-
stb_wrapper_malloc
etc.
-
-
stb_temp
- hierarchical allocator
- clients of hierarchical allocator
- regular expression
-
stb_regex
etc. - to be rewritten to not use hierarchical allocator and be released as a separate lib
-
- sdict with use_arena=1
-
use_arena
flag instb_new_sdict
will be (temporarily) removed - to be rewritten to support use_arena without using hierarchical allocator
-
- regular expression
- some printf functionality
-
stb_print
console display -
stb_mprintf
mallocing sprintf - logging functions (
stb_log
,stb_
, etc.)
-
- math functions
- 3d helpers
-
stb_newell_normal
-
stb_box_face_vertex_axis_side
-
- primes
-
stb_is_prime
,stb_power_of_two_nearest_prime
-
- general utils
-
stb_linear_controller
-
stb_float_eq
-
stb_smoothstep
,stb_cubic_bezier_1d
-
- random numbers
-
stb_rand_defined
- keep other functions
-
- hash values
-
stb_sha1_readable
which isn't a standard format anyway
-
- keep
stb_linear_remap
- 3d helpers
- data structures
- perfect hashing
-
stb_perfect_create
,stb_perfect_hash
, etc.
-
- hash tables
- stb_sparse_ptr_matrix
- aka hash from pairs of pointers to pointer
-
stb_sparse_ptr_matrix_new
etc.
- stb_sparse_ptr_matrix
- binary search tree
-
stb_bst
,stb_bst_parent
-
- pointer-NULLing-backtracker
-
stb_nptr_set
etc. -
stb_nptr_free
etc.
-
- sets of pointers (like a hash table on pointers, but keys w/o values)
-
stb_ps_add
,stb_ps_find
etc.
-
-
stb_bitset
, sets of booleans-
stb_bitset_new
,stb_bitset_setbit
, etc.
-
- stb_dupe, duplicate finding w/o sorting
-
stb_dupe_create
,stb_dupe_add
, etc.
-
- perfect hashing
- algorithms
- sorting
-
stb_define_sort
-
- binary search toolkit
-
stb_search_binary
,stb_probe
etc.
-
- sorting
- file I/O
- file reading special-cases
-
stb_file_max
-
stb_stringfile_trimmed
-
- file I/O using automatic tempfile
-
stb_fopen
,stb_fclose
- These functions are not thread-safe because they have to store the extra information for a FILE* somewhere, and currently use a global table w/o locking
- They also have the behavior of supporting UTF8 filenames on Windows, so
stb_fopen
will be preserved but only providing that functionality, andstb_fclose
becomes irrelevant andfclose
can be used instead.
-
- integer packing file operations
-
stb_fput_ranged
etc. -
stb_fput_varlen
etc.
-
- virtualized method file system
stbfile
-
stb_open
,stb_open_inbuffer
, etc.
-
- file reading special-cases
- configuration-y stuff
- options parsing
-
stb_getopt
etc.
-
- Windows registry read/write
-
stb_reg_open
,stb_reg_read
, etc.
-
- config file handler
-
stb_cfg_open
,stb_cfg_read
, etc.
-
- options parsing
- directory tree
- database
- this is separate from directory reading; this API writes a "database" to disk and refreshes it more efficiently on future use
-
stb_dirtree_get
etc.
- creating tree summaries from list of filenames
-
stb_dirtree2
etc.
-
- database
- monospaced word wrapping
-
stb_wordwrap
,stb_wordwrapalloc
-
- regular expressions
-
stb_matcher
-
stb_regex_matcher
,stb_matcher_match
, etc. -
stb_lex
,stb_lex_matcher
, etc. - above functions to (hopefully) be released as a standalone library
- keep wildcard matching such as
stb_wildmatch
-
- compression
- low-quality LZ compression
-
stb_compress
,stb_compress_to_file
etc. -
stb_decompress
,stb_decompress_from_file
etc.
-
- arithmetic range-coder
stb_arith
-
stb_artih_init_encode
,stb_arith_encode
etc. -
stb_arith_init_decode
,stb_arith_decode_value
*etc.
-
- low-quality LZ compression
- Threading
-
stb_thread
,stb_create_thread
etc. -
stb_semaphore
,stb_sem_new
etc. -
stb_mutex
,stb_mutex_new
etc. -
stb_sync
,stb_sync_new
etc. -
stb_threadqueue
stb_threadq_new
etc. -
stb_work
etc. -
stb_workqueue
etc. -
stb_bgio_read
,stb_bgio_read_to
, etc.
-
- Source-code constant dynamic modification
-
STB_I
,STB_F
etc. -
STB_CONVENIENT_H
-
- stua scripting language
-
STB_STUA
etc.
-
The proposed stb_lib.h appears in "tests/prerelease/stb_lib.h", except I accidentally deleted the bit math operations such as stb_ceil_log2
, which need to be re-added.
Is this still going to happen? I'd like to use this library, but I noticed it's about 2 years since this was posted, and since there were any edits. Thanks,
I do not think stb.h is not popular, it is just too convenient to use. So people just copy and use it without coming back.
What is the plan for string functions like stb_stricmp and stb_p_strdup? I don't see them in the new library, are they going away?
Excuse me for necro'ing this post but it's quite interesting to me that the intent of stb was to be a general-purpose lib to replace libc. I was thinking stb was just a collection of random use case specific libs. I am wondering what happened to this effort? Was there a reason to not continue on with a general-purpose libc alternative?
Where are you getting that from? stb.h
was never meant to replace libc. It's a library of utility functions building on top of (among other things) libc functionality.
I shouldn't say 'replace' but rather supersede. It looked to be something to streamline many common things you'd typically go straight to libc for?