bricabrac-single-file-modules

Table of Contents generated with DocToc

• Bric-A-Brac Standard Brics
  • To Do
    • Random
      • Random: Implementation Structure
    • Errors
    • Other

Bric-A-Brac Standard Brics

To Do

Random

• [—] Provide alternative to ditched unique, such as filling a Set to a certain size with characters
• [—] Provide internal implementations that capture attempt counts for testing, better insights
• [—] use custom class for stats that handles excessive retry counts
• [—] implement iterators
• [—] should on_exhaustion, on_stats, max_retries be implemented for each method?

Random: Implementation Structure

• the library currently supports four data types to generate instance values for: float, integer, chr, text

• for each case, instance values can be produced...

  • ...that are not smaller than a given minimum and not larger than a given maximum
  • ...that are filtered according to a given RegEx pattern or an arbitrary function
  • ...that, in the case of texts, are not shorter and not longer than a given pair of minimum_length and maximum_length
  • ...that are unique in relation to a given collection (IOW that are new to a given collection)

• the foundational Pseudo-Random Number Generator (PRNG) that enables the generation of pseudo-random values is piece of code that I found on the Internet (duh), is called SplitMix32 and is, according to the poster,

  A 32-bit state PRNG that was made by taking MurmurHash3's mixing function, adding a incrementor and tweaking the constants. It's potentially one of the better 32-bit PRNGs so far; even the author of Mulberry32 considers it to be the better choice. It's also just as fast.

• Like JavaScript's built-in Math.random() generator, this PRNG will generate evenly distributed values t between 0 (inclusive) and 1 (exclusive) (i.e. 0 < t ≤ 1), but other than Math.random(), it allows to be given a seed to set its state to a known fixed point, from whence the series of random numbers to be generated will remain constant for each instantiation. This randomly-deterministic (or deterministically random, or 'random but foreseeable') operation is valuable for testing.

• Since the random core value t (accessible as Get_random::_float()) is always in the interval [0,1), it's straightforward to both scale (stretch or shrink) it to any other length [0,p) and / or transpose (shift left or right) it to any other starting point [q,q+1), meaning it can be projected into any interval [min,max) by computing j = min + ( t * ( max - min ) ). That projected value j can then be rounded e.g. to an integer number n, and that integer n can be interpreted as a Unicode Code Point and be used in String.fromCodePoint() to obtain a 'character'. Since many Unicode codepoints are unassigned or contain control characters, Get_random methods will filter codepoints to include only 'printable' characters. Lastly, characters can be concatenated to strings which, again, can be made shorter or longer, be built from filtered codepoints from a narrowed set like, say, /^[a-zA-ZäöüÄÖÜß]$/ (most commonly used letters to write German), or adhere to some predefined pattern or other arbitrary restrictions. It all comes out of [0,1) which I find amazing.

• A further desirable restriction on random values that is sometimes encountered is the exclusion of duplicates; Get_random can help with that.

• each type has dedicated methods to produce instances of each type:

  • a convenience function bearing the name of the type: Get_random::float(), Get_random::chr() and so on. These convenience functions will call the associated 'producer methods' Get_random::float_producer(), Get_random::chr_producer() and so on which will analyze the arguments given and return a function that in turn will produce random values according to the specs indicated by the arguments.

References

• Proposal to add new Random.Seeded() to JS

To Do

• [—] implement a 'raw codepoint' convenience method?
• [—] adapt Get_random::float(), Get_random::integer() to match Get_random::chr(), Get_random::text()
• [—] ensure Get_random::cfgon_stats is called when given even when missing or null in method call
• [—] need better rpr()
  • [—] one rpr() for use in texts such as error messages, one rpr() ('show()'?) for use in presentational contexts

Benchmark

• [—] implement ?min_count / ?max_count / ?min_dt / ?max_dt, prioritize: ( 'dt' | 'count' )
  • probably best to stick with min or max for both count and dt

Errors

• [—] custom error base class

  • [—] or multiple ones, each derived from a built-in class such as RangeError, TypeError, AggregateError

• [—] solution to capture existing error, issue new one a la Python's raise Error_2 from Error_1

• [—] omit repeated lines when displaying error.cause?

Remap

• [—] provide facility to retrieve all own keys (strings+symbols)
• [—] use property descriptors
• [—] can be expanded to provide shallow_clone(), deep_clone()

Other

• [—] publish clean() solution to the 'Assign-Problem with Intermediate Nulls and Undefineds' in the context of a Bric-A-Brac SFModule