From 4caee54c07acbca74c136889c1534aaafe3e9214 Mon Sep 17 00:00:00 2001 From: Dnomd343 Date: Fri, 27 Jan 2023 16:20:31 +0800 Subject: [PATCH] docs: description of ShortCode --- src/klotski/short_code/short_code.h | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/src/klotski/short_code/short_code.h b/src/klotski/short_code/short_code.h index 44ba4cd..529589b 100644 --- a/src/klotski/short_code/short_code.h +++ b/src/klotski/short_code/short_code.h @@ -1,5 +1,27 @@ #pragma once +/// ShortCode is a high-compression encoding scheme based on CommonCode. Since there +/// are a total of 29334498 valid klotski layouts, arrange their CommonCodes from +/// small to large (36-bits positive integers), and use the index as the ShortCode. + +/// Therefore, the valid value of ShortCode is [0, 29334498), stored in `uint32_t`. +/// The goal of high compression ratio is to facilitate verbal sharing, so it is +/// necessary to represent it in a suitable string. Similar to Bitcoin's base58, +/// in ShortCode, 4 confusing characters `0` `O` `I` `l` are removed from 10 numbers +/// and 26 characters, forming a private base32 scheme. + +/// Coincidentally, log(32, 29334498) is approximately equal to `4.96`, so using +/// 5-bits base32 can make good use of space, so any valid klotski layout can be +/// represented by a 5-bits length code. As in CommonCode, the characters here are +/// case insensitive, but uppercase is still recommended. + +/// Eg1: 0x1A9BF0C00 -> 4091296 -> "4WVE1" +/// Eg2: 0x4FEA13400 -> 10399732 -> "AXCZN" + +/// Compared with CommonCode, although ShortCode saves space, it completely loses +/// readability. The former can directly get the layout without the help of a computer, +/// while the latter is almost impossible to complete by the human brain. + #include #include #include