stb_lib proposal (replacing stb.h)

[nothings]

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
  • these might become available again if you #define an extra symbol
• 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
• 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 in stb_new_sdict will be (temporarily) removed
    • to be rewritten to support use_arena without using hierarchical allocator
• 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
• 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.
  • 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.
• algorithms
  • sorting
    • stb_define_sort
  • binary search toolkit
    • stb_search_binary, stb_probe etc.
• 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, and stb_fclose becomes irrelevant and fclose 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.
• 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.
• 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.
• 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.
• 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.

[scashews]

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,

[kindofblue]

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.

[ennorehling]

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?

[rygo6]

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?

[rygorous]

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.

[rygo6]

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?