From d2c08cfed1d0d545da42a80c6deaf85fcd844cc6 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sat, 13 Apr 2024 22:19:52 -0400 Subject: doc --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..3537697 --- /dev/null +++ b/README.md @@ -0,0 +1,30 @@ +# Implementation of RFC 1982 Serial Number Arithmetic. + +Run as a program, this takes start and finish serial values and tells +you what intermediate steps (if any) are needed to make the specified +change. + +Used as a module, this implements the `Serial` class and an iterator +which returns the intermediate steps (if any) needed between two +`Serial` values. + +Per the RFC, only two operations are defined on `Serial` objects: +addition and comparision, both within a restricted range specified +by the RFC. + +The default modulus is `2**32`, you can change this by subclassing the +`Serial` and overriding the class's `modulus` variable. The modulus +must be a power of two. + +See RFC 1982 for discussion of the ways in which serial numbers do not +work like normal integers. In particular, note that there's a corner +case in which one can have a pair of serial numbers `I1` and `I2` +where `I1` is neither equal to, less than, nor greater than `I2`. +This is deliberate and is not a bug in the code. See the RFC. + +The `find_intermediate()` iterator takes two `Serial` values `start` +and `finish` and yields the sequence of intermediate values (if any) +needed to step from `start` to `finish`. + +There are also a couple of test programs that use `random.randint()` +to generate test values. Maybe someday I'll recode with `unittest`. -- cgit v1.2.3