docs: update README

DESCRIPTION

@@ -1,14 +1,18 @@
 Package: shikakusphere
 Title: Miscellaneous Functions for Japanese Mahjong
-Version: 0.0.3.9006
+Version: 0.0.4
 Authors@R: c(
     person("Akiru", "Kato", , "paithiov909@gmail.com", role = c("aut", "cre")),
-    person("tomo","hxx", role = "ctb", comment = "shanten-number"),
-    person("Tadao", "Yamaoka", role = "ctb", comment = "cmajiang"),
-    person("Lee", "Thomason", role = "ctb", comment = "tinyxml2")
+    person("tomo", "hxx", role = "ctb",
+           comment = "shanten-number"),
+    person("Tadao", "Yamaoka", role = "ctb",
+           comment = "cmajiang"),
+    person("Lee", "Thomason", role = "ctb",
+           comment = "tinyxml2")
   )
 Description: A collection of miscellaneous functions for Japanese mahjong
-    that wraps C++ sources of 'cmajiang'
+    that wraps C++ sources of 'shanten-number'
+    <https://github.com/tomohxx/shanten-number> and 'cmajiang'
     <https://github.com/TadaoYamaoka/cmajiang>.
 License: GPL (>= 3)
 BugReports: https://github.com/paithiov909/shikakusphere/issues

README.Rmd

@@ -37,7 +37,9 @@ pak::pak("paithiov909/shikakusphere")
 
 ## Example
 
-手牌（`hands`）は[kobalab/majiang-core](https://github.com/kobalab/majiang-core)の記法で表現する。
+### 手牌の表現
+
+手牌は[kobalab/majiang-core](https://github.com/kobalab/majiang-core)の記法で文字列として表現します。
 
 **参考**
 
@@ -46,6 +48,8 @@ pak::pak("paithiov909/shikakusphere")
 - [牌姿 · kobalab/majiang-core Wiki](https://github.com/kobalab/majiang-core/wiki/%E7%89%8C%E5%A7%BF)
 - [電脳麻将のプログラム中の中国語一覧 - koba::blog](https://blog.kobalab.net/entry/20170722/1500688645)
 
+`paistr()`は、こうした手牌の文字列表現を扱いやすくするためのS3クラス（`<skksph_paistr>`）です。`print()`したときに、その文字列に含まれる牌の枚数を表示します。また、`plot(<skksph_paistr>)`で牌姿を画像としてプロットできます。
+
 ```{r}
 library(shikakusphere)
 
@@ -56,15 +60,51 @@ hands <- c(
   "m123p055s789z1117*"
 )
 
+hands <- paistr(hands)
+hands
+
+plot(hands[3])
+```
+
+`<skksph_paistr>`を`print()`したときに表示される牌の枚数は不正確な場合があります。手牌の表現にどの牌が何枚含まれるかを正確に確認するには、`tidy(<skksph_paistr>)`を使うことができます。
+
+```{r}
+tidy(hands)
+```
+
+このかたちの表現は`lineup()`でlist of factorsにすることができます。
+
+```{r}
+tidy(hands) |>
+  lineup()
+```
+
+さらに、このかたちのlist of factors（またはlist of characters）は`lipai()`で文字列表現に変換できます（ただし、`lipai()`では`_*+=-,`は扱えません）。
+
+```{r}
+c(paste0("m", 1:9), paste0("s", 4:6), paste0("z", c(1, 1))) |>
+  lipai()
+```
+
+### シャンテン数・有効牌の確認
+
+「有効牌」については、ない場合`character(0)`を返します。
+
+```{r}
 # シャンテン数
 n_xiangting <- calc_xiangting(hands)
 n_xiangting
 
-# 有効牌（シャンテン数が減る牌）
+# 有効牌
 collect_tingpai(hands[n_xiangting >= 0])
+```
+
+### 得点・あがり役の確認
 
-# 得点. この関数はvectorizeされていないので注意！
-# baopaiはドラ表示牌、libaopaiは裏ドラ表示牌
+`calc_defen()`はvectorizeされていないため、必ず、長さが1の文字列表現を渡してください。
+
+```{r}
+# 得点
 score <- calc_defen(hands[n_xiangting == -1][1], baopai = "z1")
 score
 
@@ -73,9 +113,6 @@ calc_defen("m345567p234s3378", baopai = "z1", rongpai = "s9=")
 
 # あがり役の表示
 parse_hupai(score$hupai, "jp")
-
-# 牌姿を表示する
-hand2img(score$shoupai[1])
 ```
 
 # License

README.md

@@ -32,7 +32,9 @@ pak::pak("paithiov909/shikakusphere")
 
 ## Example
 
-手牌（`hands`）は[kobalab/majiang-core](https://github.com/kobalab/majiang-core)の記法で表現する。
+### 手牌の表現
+
+手牌は[kobalab/majiang-core](https://github.com/kobalab/majiang-core)の記法で文字列として表現します。
 
 **参考**
 
@@ -45,6 +47,8 @@ pak::pak("paithiov909/shikakusphere")
 - [電脳麻将のプログラム中の中国語一覧 -
   koba::blog](https://blog.kobalab.net/entry/20170722/1500688645)
 
+`paistr()`は、こうした手牌の文字列表現を扱いやすくするためのS3クラス（`<skksph_paistr>`）です。`print()`したときに、その文字列に含まれる牌の枚数を表示します。また、`plot(<skksph_paistr>)`で牌姿を画像としてプロットできます。
+
 ``` r
 library(shikakusphere)
 
@@ -55,12 +59,79 @@ hands <- c(
   "m123p055s789z1117*"
 )
 
+hands <- paistr(hands)
+hands
+#> <skksph_paistr[4]>
+#> [1] <13>'p222345z1234567'            <13>'p11222345z12345'           
+#> [3] <15>'m055z7z7,m78-9,z5555,z666=' <13>'m123p055s789z1117*'
+
+plot(hands[3])
+```
+
+<img src="man/figures/README-unnamed-chunk-2-1.png" width="100%" />
+
+`<skksph_paistr>`を`print()`したときに表示される牌の枚数は不正確な場合があります。手牌の表現にどの牌が何枚含まれるかを正確に確認するには、`tidy(<skksph_paistr>)`を使うことができます。
+
+``` r
+tidy(hands)
+#> # A tibble: 38 × 3
+#>       id tile      n
+#>    <int> <fct> <int>
+#>  1     1 p2        3
+#>  2     1 p3        1
+#>  3     1 p4        1
+#>  4     1 p5        1
+#>  5     1 z1        1
+#>  6     1 z2        1
+#>  7     1 z3        1
+#>  8     1 z4        1
+#>  9     1 z5        1
+#> 10     1 z6        1
+#> # ℹ 28 more rows
+```
+
+このかたちの表現は`lineup()`でlist of factorsにすることができます。
+
+``` r
+tidy(hands) |>
+  lineup()
+#> [[1]]
+#>  [1] p2 p2 p2 p3 p4 p5 z1 z2 z3 z4 z5 z6 z7
+#> 37 Levels: m0 m1 m2 m3 m4 m5 m6 m7 m8 m9 p0 p1 p2 p3 p4 p5 p6 p7 p8 p9 ... z7
+#> 
+#> [[2]]
+#>  [1] p1 p1 p2 p2 p2 p3 p4 p5 z1 z2 z3 z4 z5
+#> 37 Levels: m0 m1 m2 m3 m4 m5 m6 m7 m8 m9 p0 p1 p2 p3 p4 p5 p6 p7 p8 p9 ... z7
+#> 
+#> [[3]]
+#>  [1] m0 m5 m5 m7 m8 z5 z5 z5 z5 z6 z6 z6 z7 z7
+#> 37 Levels: m0 m1 m2 m3 m4 m5 m6 m7 m8 m9 p0 p1 p2 p3 p4 p5 p6 p7 p8 p9 ... z7
+#> 
+#> [[4]]
+#>  [1] m1 m2 m3 p0 p5 p5 s7 s8 s9 z1 z1 z1 z7
+#> 37 Levels: m0 m1 m2 m3 m4 m5 m6 m7 m8 m9 p0 p1 p2 p3 p4 p5 p6 p7 p8 p9 ... z7
+```
+
+さらに、このかたちのlist of factors（またはlist of
+characters）は`lipai()`で文字列表現に変換できます（ただし、`lipai()`では`_*+=-,`は扱えません）。
+
+``` r
+c(paste0("m", 1:9), paste0("s", 4:6), paste0("z", c(1, 1))) |>
+  lipai()
+#> [1] "m123456789s456z11"
+```
+
+### シャンテン数・有効牌の確認
+
+「有効牌」については、ない場合`character(0)`を返します。
+
+``` r
 # シャンテン数
 n_xiangting <- calc_xiangting(hands)
 n_xiangting
 #> [1]  4  3 -1  0
 
-# 有効牌（シャンテン数が減る牌）
+# 有効牌
 collect_tingpai(hands[n_xiangting >= 0])
 #> [[1]]
 #> [1] "z1" "z2" "z3" "z4" "z5" "z6" "z7"
@@ -70,9 +141,14 @@ collect_tingpai(hands[n_xiangting >= 0])
 #> 
 #> [[3]]
 #> [1] "z7"
+```
+
+### 得点・あがり役の確認
+
+`calc_defen()`はvectorizeされていないため、必ず、長さが1の文字列表現を渡してください。
 
-# 得点. この関数はvectorizeされていないので注意！
-# baopaiはドラ表示牌、libaopaiは裏ドラ表示牌
+``` r
+# 得点
 score <- calc_defen(hands[n_xiangting == -1][1], baopai = "z1")
 score
 #>                      shoupai        hupai fu fanshu damanguan defen menfeng
@@ -88,13 +164,8 @@ parse_hupai(score$hupai, "jp")
 #> [[1]]
 #> [1] 翻牌 白 翻牌 發 小三元  混一色  赤ドラ 
 #> 54 Levels: 場風 東 場風 南 場風 西 場風 北 自風 東 自風 南 自風 西 ... 地和
-
-# 牌姿を表示する
-hand2img(score$shoupai[1])
 ```
 
-<img src="man/figures/README-unnamed-chunk-2-1.png" width="100%" />
-
 # License
 
 GPL (\>= 3). This package contains the