Puid 2.3

Puid 2.3 adds four functions to Puid generated modules:

• total: total puids which can be generated at a specified risk
• risk: risk in generating a specified total puids
• encode: encode a bitstring to a puid
• decode: decode a puid into the representative bitstring

total and risk are useful for after-the-fact considerations. You created a puid generator, and now want to know:

• with this generator, what is the risk of repeat if I generate total puids
• with this generator, what is the total number of puids I can generate at some risk

encode and decode were added to facilitate the creation of an ecto-puid package that allows Puid generation for DB ids. These function are not robust. They expect to be used with Puid generated values, and as such those values must be valid with respect to the Puid generator in use.

Puid 2.2

Puid 2.2 introduces three new pre-defined character sets:

• :base16 from RFC 4648
• :crockford32 from Crockford
• :wordSafe32, another strategy for avoiding English words in a manner similar to the exiting :safe32 characters

Puid 2.1

Puid 2.1 implements a minor optimization in bit slicing that does not change general external functionality. The change could effect the results of testing with fixed byte input for puid generation, and therefore warranted a minor version update to alert any user that used fixed byte entropy input for testing purposes.

Puid 2.0

Puid 2.0

Puid 2.0 brings significant optimizations to the speed and efficiency of generating random strings for use a probably unique IDs.

Breaking Changes

Module Creation

The charset option was folded into the chars option. Since Puid 1.x prevented using both options, upgrading to 2.x should be as easy as renaming any prior use of charset to chars.

Utility Function Arguments

The order of arguments for utility functions in the Puid.Entropy module were reversed to facilitate idiomatic Elixir usage. These functions were primarily used internally so it is anticipated there will be little impact on existing usage. Modifying code to use the new argument order should be trivial.

Notable Changes

puid String Construction

The strategy in building a puid from random bits has been significantly optimized across all choices of characters. The speed of creating a puid is now the same for any of two character set categories: :ascii and :utf8. Although all Elixir strings are utf8 encoded, Puid takes advantage of the fact ascii is encoded as 1-byte in utf8. If any character used has a utf8 encoding of more than 1-byte, the puid construction is still optimized but less so.

This optimization is a adaptation and generalization of code in the Elixir.Base module. Thanks goes to the Elixir team for the development of that strategy.

:ascii

If all the source characters are 1-byte ascii, puid construction is optimized using cross-product character pairs, allowing a puid to be built two characters at a time when possible.

:utf8

If any character requires more than 1-byte for utf8 encoding, the cross-product strategy is not applicable. The puid string building still uses an optimized construction, but without the advantage of cross-product pairs.

Entropy Source Bit Usage

The strategy for using entropy source bits during puid construction is optimized to "lose" as few bits as possible when the bit-slicing scheme encounters indexes beyond the source character count. The strategy is to bit-shift only by as many bits as absolutely necessary to determine that the next index would actually be out-of-bounds, and maintain the remaining bits for further use.

Unused source entropy bits are "saved" between puid generation.