From ac35959a87d2d1ff6e45db326f8ab48ce1a1d93b Mon Sep 17 00:00:00 2001 From: Dnomd343 Date: Fri, 27 Jan 2023 16:01:35 +0800 Subject: [PATCH] docs: description of CommonCode --- src/klotski/common_code/common_code.h | 51 +++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/src/klotski/common_code/common_code.h b/src/klotski/common_code/common_code.h index bfb415a..ac65413 100644 --- a/src/klotski/common_code/common_code.h +++ b/src/klotski/common_code/common_code.h @@ -1,5 +1,56 @@ #pragma once +/// CommonCode is a generic klotski encoding that records an valid case using +/// 36-bits lengths, and stored in a `uint64_t`. + +/// Since there is only one `2x2` block, it is encoded separately. Its upper +/// left corner is called `head`, it has 12 possible positions and is encoded +/// using 4-bits length (0 ~ 15). +/// +/// 00 01 02 03 +/// 04 05 06 07 00 01 02 +/// 08 09 10 11 04 05 06 <- head of 2x2 block +/// 12 13 14 15 08 09 10 (without 03/07/11/15) +/// 16 17 18 19 12 13 14 + +/// Treat spaces as special blocks, there can be four kinds of blocks in total, +/// namely `space`, `1x2`, `2x1`, `1x1`. Each of them is represented by 2-bits, +/// which are `00` `01` `10` `11`. Arrange them according to their position and +/// size, and we can get a binary sequence. +/// 2x2 -> # # | 2x1 -> # | 1x2 -> # # | 1x1 -> # +/// # # | # | | + +/// This sequence can have up to 16 blocks, aka 32-bits in length. Therefore, in +/// order to be compatible with all cases, the length of this part of the code +/// is set to 32-bits. In addition, for the convenience of reading, it is +/// stipulated that the sequence starts from the high bit, and the remaining bits +/// should be filled with `0`. + +/// Putting the content of the `head` in the upper 4-bits, and the lower 32-bits +/// to store the sequence content, a 36-bits length code can be obtained, which +/// corresponds to any valid layout one-to-one. When CommonCode is converted into +/// a string, just directly export the hexadecimal data, and get a 9-bits string +/// encoding. Characters are not case-sensitive, but it is recommended to use +/// uppercase letters. In addition, the last `0` of the string is allowed to be +/// omitted, and it can be completed to 9 digits when decoding, but note that if +/// the encoding is all `0`, it should be reduced to the remaining one `0`. + +/// Eg1: +/// % # # % 2x2 -> head = 1 +/// % # # % 2x1 2x1 2x1 1x2 2x1 1x1 1x1 1x1 space space 1x1 ... ... ... ... ... +/// @ $ $ @ 10 10 10 01 10 11 11 11 00 00 11 00 00 00 00 00 +/// @ & * @ 1010 1001 1011 1111 0000 1100 0000 0000 +/// * & A 9 B F 0 C 0 0 +/// CommonCode = 0x1A9BF0C00 -> "1A9BF0C" + +/// Eg2: +/// * @ & % 2x2 -> head = 4 +/// # # $ % 1x1 1x1 1x1 2x1 2x1 2x1 space 1x2 space 1x1 1x2 ... ... ... ... ... +/// # # $ ^ 11 11 11 10 10 10 00 01 00 11 01 00 00 00 00 00 +/// ~ ~ ^ 1111 1110 1010 0001 0011 0100 0000 0000 +/// @ % % F E A 1 3 4 0 0 +/// CommonCode = 0x4FEA13400 -> "4FEA134" + #include #include #include