zg module, casing improvements

1 files changed, 75 insertions, 19 deletions

diff --git a/NEWS.md b/NEWS.md
index c484b62..ada1405 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,6 @@
 # News
 
+
 ## zg v0.16.0-pre Release Notes
 
 This brings another major change to `zg`, touching basically everything.
@@ -24,6 +25,10 @@ I did manage to dispose of one last allocation in `CanonData`, by
 integrating Vexu's very clever [comptime hash map][chm], so, that's
 nice.
 
+[uucode]: https://github.com/jacobsandlund/uucode
+[chm]: https://github.com/Vexu/comptime_hash_map/blob/master/src/main.zig
+
+
 ### Migration
 
 Is simplicity itself: just call the module instead of calling the
@@ -33,41 +38,73 @@ disposing of it when you're done with it.
 Technically the laws of style dictate that, since these are now
 containers, and not instantiable types, they should be lowercased.
 
-I did not do that in the README.  But feel free!
+I didn't see the point in changing all those names, it would add labor
+to what should be a very brief and pleasant upgrade (but see below).
+But feel free!
 
 Pro tip: use LSP superpowers to rename the instance to the name of the
 module, then just delete the initializer.  Couldn't be simpler.
 
+
+### zg: The Module
+
+The take-what-you-need approach, of packaging the interface in a bunch of
+separate modules, remains available for those who prefer it.
+
+Or, your code can just import `"zg"`, a module containing all of the
+other modules.  Zig's lazy compilation model gives us take-what-you-need
+already, so while there's no reason to remove the submodules, there's no
+reason to prefer using them either.
+
+As mentioned above, none of these are instance types any longer, and that
+dictates that they take lower-case (as `code_point` and `ascii` always
+have, for that reason).  So in `zg`, the modules are styled in lower case.
+
+I did not want to combine a purely stylistic change, and one which would
+require editing build scripts, with the functional changes needed to use
+the (much nicer!) allocation-free interface.  It is possible that later
+releases will lowercase the submodules as well, or maybe just remove
+them in favor of importing `zg`.  Then again, maybe not.
+
+
 ### Emoji Module
 
-Also Jacob's work.
+Also Jacob's work.  Exposes the basic useful Unicode emoji properties.
 
-[uucode]: https://github.com/jacobsandlund/uucode
-[chm]: https://github.com/Vexu/comptime_hash_map/blob/master/src/main.zig
 
-### graphemeClusterWidth
+### `graphemeClusterWidth`
 
 @lch361 submitted a minor refactor which makes it cleaner to obtain the
 display width of a grapheme cluster.  Thanks Lich!
 
-### The Future
 
-I hope I don't jinx it, but this is the last major change I've wanted
-to make to `zg`.  I brought it up with José before he handed over
-maintainence to me, we agreed that compressing and decompressing and
-heap-allocating was one of those ideas which turned out not to pencil
-out.  Hey, it happens.
+### Better Fast-pathing in Caseless Comparison
+
+Caseless comparison only tries the ASCII fast-path when strings are the
+same size, which is the only time it can work.  The fast path has also
+been SIMD accelerated when possible.
+
+Canonicalization, and caseless comparision (which uses it), are in need
+of attention.  They do things in the most expensive possible fashion,
+without taking advantage of any opportunities to do the cheaper thing.
+While the result is correct, even in pathological cases, it is not
+optimal, especially given the reality that Unicode text is, in a modern
+context, nearly always in canonical form already.
+
+Changes to that will have to wait for another release, despite my
+inclinations to the contrary.
+
+
+### code_point.decode fully deprecated
 
-Features?  There are few left, sure.  Bugfixes?  Always, of course.
-But major API changes are now unlikely.
+Slicing to decode a point is an anti-pattern, and calling this
+deprecated function is now a `@compileError`, suggesting `decodeAtIndex`
+instead.  I suggest taking a look at `decodeAtCursor` as well, which
+takes a pointer to an index and moves it to the next codepoint while
+decoding, this is often what you want.
 
-I have a "no 1.0 until Zig 1.0" policy, because no one can guarantee the
-stability of anything until that happens.  Nor is `zg` actually ready
-for a stability policy; if I decide to break apart a module, or move
-something where it makes more sense, I'm going to do that.
+A future release will remove the function entirely.
 
-But it is _likely_ that this is the last 'global' refactor of the
-library.
 
 ## zg v0.15.2-4 Release Notes
 
@@ -82,6 +119,7 @@ but we could have vendored it: more importantly, it turned out to be
 basically useless.  Savings per data set were in the bytes to low
 KiB range, and startup time was negatively affected.
 
+
 ## zg v0.14.1 Release Notes
 
 In a flurry of activity during and after the `v0.14.0` beta, several
@@ -92,6 +130,7 @@ Presenting `zg v0.14.1`.  As should be expected from a patch release,
 there are no breaking changes to the interface, just bug fixes and
 features.
 
+
 ### Grapheme Zalgo Text Bugfix
 
 Until this release, `zg` was using a `u8` to store the length of a
@@ -109,6 +148,7 @@ Actually, both fields are now `uoffset`, for reasons described next.
 
 [Zalgo]: https://stackoverflow.com/questions/1732348/regex-match-open-tags-except-xhtml-self-contained-tags/1732454#1732454
 
+
 ### Limits Section Added to README
 
 The README now clearly documents that some data structures and iterators
@@ -125,6 +165,7 @@ I believe this to be neither necessary nor sufficient for handling data of
 that size.  But I can't anticipate every requirement, and don't want to
 preclude it as a solution.
 
+
 ### Iterators, Back and Forth
 
 A new contributor, Nemoos, took on the challenge of adding a reverse
@@ -158,6 +199,7 @@ of those functions.  For codepoints, starting an iterator at either
 `.offset` or `.offset + .len` will suffice, since the `CodePoint`
 iterator is otherwise stateless.
 
+
 ### Words Module
 
 The [Unicode annex][tr29] with the canonical grapheme segmentation
@@ -173,6 +215,7 @@ segmentation and [line breaking][tr14].
 [tr29]: https://www.unicode.org/reports/tr29/
 [tr14]: https://www.unicode.org/reports/tr14/
 
+
 #### Runeset Used
 
 As a point of interest:
@@ -190,6 +233,7 @@ transitive dependencies.
 [UCD]: https://www.unicode.org/reports/tr44/
 [Rune]: https://github.com/mnemnion/runeset
 
+
 ## zg v0.14.0 Release Notes
 
 This is the first minor point release since Sam Atman (me) took over
@@ -201,12 +245,14 @@ The changes are fairly large, and most user code will need to be updated.
 The result is substantially streamlined and easier to use, and updating
 will mainly take place around importing, creating, and deinitializing.
 
+
 ### The Great Renaming
 
 The most obvious change is on the surface API: more than half of the
 modules have been renamed.  There are no user-facing modules with `Data`
 in the name, and some abbreviations have been spelled in full.
 
+
 ### No More Separation of Data and Functionality
 
 It is no longer necessary to separately create, for example, a
@@ -222,6 +268,7 @@ This would make user structs larger in some cases, while eliminating a
 pointer chase.  If that isn't a desirable trade off for your code,
 read on.
 
+
 ### All Allocated Data is Unmanaged
 
 Prior to `v0.14`, all structs which need heap allocation no longer
@@ -235,6 +282,7 @@ Getting up to speed is a matter of passing the allocator to `deinit`.
 This change comes courtesy of [lch361](https://lch361.net), in his
 first contribution to the repo.  Thanks Lich!
 
+
 ### `code_point` Now Unicode-Compliant
 
 The `v0.15.x` decoder used a simple, fast, but naïve method to decode
@@ -267,6 +315,7 @@ is good for the fetch pipeline, and more ergonomic in many cases.
 [^1]: A bit more than twice as fast as the standard library for
 decoding, according to my (limited) benchmarks.
 
+
 ### DisplayWidth and CaseFolding Can Share Data
 
 Both of these modules use another module to get the job done,
@@ -276,6 +325,7 @@ It is now possible to initialize them with a borrowed copy of those
 modules, to make it simpler to write code which also needs the base
 modules.
 
+
 ### Grapheme Iterator Creation
 
 This is a modest streamlining of how a grapheme iterator is created.
@@ -304,6 +354,7 @@ var iter = Graphemes.Iterator.init("stri̵̫̗̗̱̳̼̖͚͉͂̌̈́̓̄͋̇̎͠ͅ
 
 If one were to prefer doing so.
 
+
 ### Initialization vs. Setup
 
 Every allocating module now has both an `init` function, which
@@ -321,6 +372,7 @@ have been turned `unreachable`, leaving only `error.OutOfMemory`.
 Encountering any of the other errors would indicate an internal problem,
 so we no longer make user code deal with that unlikely event.
 
+
 ### New DisplayWidth options
 
 A `DisplayWidth` can now be compiled to treat `c0` and `c1` control codes
@@ -330,18 +382,21 @@ need to escape control codes to make them visible.  Setting these
 options will let `DisplayWidth` return the correct widths when this
 is done.
 
+
 ### Unicode 16.0
 
 This updates `zg` to use the latest Unicode edition.  This should be
 the only change which will change behavior of user code, other than
 through the use of the new `DisplayWidth` options.
 
+
 ### Tests
 
 It is now possible to run all the tests, not just the `unicode-test`
 subset. Accordingly, that step is removed, and `zig build test`
 runs everything.
 
+
 #### Allocations Tested
 
 Every allocate-able now has a `checkAllAllocationFailures` test.  This
@@ -349,6 +404,7 @@ process turned up two bugs.  Also discovered were 8,663 allocations,
 which were reduced to two, these were also being individually freed
 on deinit.  So that's nice.
 
+
 #### That's It!
 
 I hope you find converting over `zg v0.13` code to be fairly painless