Skip to content

Calculul valorii unei mâini

Nivel: începător

Prima noastră provocare este să corectăm calculul valorii unei mâini.

Atunci când pe masă se află mai multe cărți, jucătorul are voie să plaseze doar cărți cu o valoare mai mare.

De exemplu, dacă următoarea carte 3 este pusă pe masă, este permis să fie jucată 4 (deoarece 4 este strict mai mare decât 3), dar nu este o mutare permisă 2 , deoarece 2 nu este strict mai mare decât 3.

Știu deja Kotlin și vreau să rezolv asta fără ajutor.

Scopul este de a implementa regula de plasare. Poți rula testele folosind Check (JVM-only). Trebuie modificat un singur fișier; provocarea este considerată reușită atunci când toate testele trec.

1. Citirea codului existent

Să începem prin a analiza codul existent în core/src/commonMain/kotlin/Deck.kt. Un pachet reprezintă mai multe cărți grupate împreună.

Fișierul începe cu:

/*
 * Copyright (c) 2026, BordeauxKt and contributors.
 * 
 * …
 */
Acesta este un comentariu. Comentariile sunt mesaje pe care dezvoltatorii le lasă pentru alți dezvoltatori; ele sunt ignorate de limbajul de programare. Există trei tipuri de comentarii:

  • Orice se află în dreapta secvenței // este un comentariu, pe aceeași linie.
  • Tot ce se află între /* și */ este un comentariu, chiar dacă ocupă mai multe linii.

package io.bordeauxkt.kotlin15

Această linie declară că fișierul aparține pachetului io.bordeauxkt.kotlin15. Un pachet este similar unui folder: ajută la organizarea codului înrudit, astfel încât acesta să fie grupat laolaltă.


/**
 * Mai multe cărți plasate împreună.
 *
 * Cărțile trebuie **ori**:
 * - Toate să aibă aceeași [valoare][Card.value].
 * - Toate să aibă aceeași [culoare][Card.color].
 *
 * Un pachet are o [valoare].
 *
 * Pentru a stoca arbitrar diverse cărți, vezi [Mâna].
 */
data class Deck(
    val cards: Set<Card>,
) {

    // …
}

Aici creăm o data class numită Deck. O data class este o entitate compusă din anumite date. Datele care o compun sunt declarate între paranteze. Acestea poartă numele de proprietate. Deck are o singură proprietate:

    val cards: Set<Card>,

  • val reprezintă "valoarea". O valoare nu se schimbă în timp.
  • cards este numele proprietății.
  • Caracterul : reprezintă faptul că ce urmează este tipul proprietății. Tipul specifică ce fel de date stochează proprietatea.
  • Set<Card> set citește "set de cărți". Un set este o colecție de cărți care nu poate conține duplicate: toate cărțile trebuie să fie diferite între ele.

În concluzie, definim un Deck (pachet) ca fiind un element compus din mai multe cărți (stocate într-o proprietate numită cards), precizând că un pachet nu poate conține aceeași carte de mai multe ori.

Declarația clasei se încheie cu acolade: { și } – câteva linii mai jos. Acoladele definesc un „bloc” care oferă informații suplimentare despre un anumit element. În acest caz, tot conținutul blocului descrie funcționalitatea unui pachet de cărți.


init {
    require(isLegal(cards)) { "All cards in a deck must either have the same color, or have the same value, but this deck has neither: $cards" }
}

init {} este un bloc special dintr-o clasă care specifică ce cod trebuie executat atunci când clasa este creată.

Aici, codul apelează funcția require(), care verifică o constrângere și provoacă terminarea forțată a aplicației atunci când verificarea eșuează. Verificarea constă într-un apel la isLegal(cards), care verifică dacă pachetul conține cărți valide. Putem ignora acest aspect pentru moment.


    /**
     * Valoarea unui pachet.
     *
     * Un pachet `[2 Roșu, 3 Roșu]` are valoarea 32:
     * - Cărțile sunt sortate în ordine descrescătoare.
     * - Valorile cărților este concatenată.
     */
    val value: Int = 0 // TODO!

Aceasta este proprietatea care ne interesează!

Ca o reamintire:

  • /** … */ este un comentariu: reprezintă documentație pentru ceilalți dezvoltatori.
  • val declară o valoare: o proprietate care nu se modifică.
  • value îi este numele.
  • : Int este tipul său. Int este un întreg: un număr care nu are parte zecimală. De exemplu, 1, 19 sau -7.
  • = 0 este valoarea efectivă a proprietății value. În forma actuală, indiferent de circumstanțe, valoarea este 0.

În prezent, codul calculează valoarea 0 pentru orice pachet de cărți. Prima noastră provocare va fi să corectăm calculul valorii, astfel încât jocul să poată funcționa corespunzător.

2. Executarea testelor

Proiectul include o suită extinsă de teste pe care o putem folosi pentru a verifica dacă modificările noastre sunt corecte.

Pentru a rula testele, caută săgeata verde din partea dreaptă sus. Din meniul derulant, alege Check (JVM-only); aceasta va rula toate testele folosind JVM-ul.

Pentru a rula toate testele pe toate platformele suportate (JVM, JS în browser, Node.js și iOS), poți executa Check. Totuși, în acest proiect, toate platformele utilizează exact același cod, astfel că rularea exclusivă a testelor pentru JVM oferă suficiente informații și este mai rapidă.

Prima rulare poate dura ceva timp, dar următoarele ar trebui să dureze doar câteva secunde.

Ar trebui să vezi 21 de teste eșuate, primul fiind:

java.lang.IllegalStateException: 
check(deck.value == 1)
      |    |     |
      |    0     false
      [1 Red]

    at io.bordeauxkt.kotlin15.DeckTestKt$DeckTest$2$2$2.invokeSuspend(DeckTest.kt:76)
    at io.bordeauxkt.kotlin15.DeckTestKt$DeckTest$2$2$2.invoke(DeckTest.kt)
    at io.bordeauxkt.kotlin15.DeckTestKt$DeckTest$2$2$2.invoke(DeckTest.kt)

Tip

Dacă numele testelor arată astfel: <tb<io.bordeauxkt.kotlin15.DeckTest↘Value↘A deck with a single card…>tb>, instalează pluginul TestBalloon accesând (stânga sus) | File | Settings | Plugins, căutând „TestBalloon” și făcând clic pe „Install”. După instalarea pluginului, poți rula din nou configurația Check (JVM-only) pentru a vedea numele reale ale testelor.

Să citim textul testului eșuat.


java.lang.IllegalStateException:
Prima linie ne indică faptul că eroarea este IllegalStateException din Java. IllegalStateException înseamnă că „programul a detectat că se află într-o stare incorectă”.


check(deck.value == 1)
      |    |     |
      |    0     false
      [1 Red]
  • check() este o funcție care verifică o condiție. Dacă respectiva condiție este false, testul eșuează și se generează o excepție IllegalStateException. Deoarece aceasta este excepția întâlnită, știm că verificarea condiției a eșuat.
  • Începem linia cu deck. Urmărind simbolul | în jos, observăm că deck-ul conținea o singură carte: 1 .
  • Apoi, testul accesează valoarea pachetului: deck.value. Urmărind simbolul | în jos, putem vedea că valoarea pachetului este 0. Exact asta am văzut și în cod!
  • În schimb, == 1 înseamnă că testul se aștepta ca valoarea să fie 1 în această situație.

Tip

Această vizualizare a rezultatelor testelor este oferită de pluginul Power Assert, care este deja configurat în proiect.


    at io.bordeauxkt.kotlin15.DeckTestKt$DeckTest$2$2$2.invokeSuspend(DeckTest.kt:76)
    at io.bordeauxkt.kotlin15.DeckTestKt$DeckTest$2$2$2.invoke(DeckTest.kt)
    at io.bordeauxkt.kotlin15.DeckTestKt$DeckTest$2$2$2.invoke(DeckTest.kt)
Aceasta este stiva de apeluri. Îți spune de unde provine codul care rulează în timpul testului. Dacă descompunem prima linie:

  • at io.bordeauxkt.kotlin15 înseamnă că respectivul cod provine din pachetul io.bordeauxkt.kotlin15, care este același pachet cu cel al codului pe care îl scriem.
  • DeckTestKt înseamnă că respectivul cod provine din clasa DeckTestKt, generată de fișierul DeckTest.kt.
  • $DeckTest$2$2$2.invokeSuspend() este identificatorul metodei, dar nu este deosebit de util pentru teste, așa că nu îl vom explica aici.
  • DeckTest.kt:76 ne indică faptul că este vorba despre fișierul DeckTest.kt, linia 76. În Android Studio, poți da clic pe această referință pentru a accesa fișierul respectiv, dacă dorești să vezi cum este scris testul. Nu vom modifica testele în cadrul acestei provocări.

3. Valoarea unei singure cărți

Valoarea unei singure cărți, de exemplu 3 , este valoarea cărții, în acest caz 3. Haideți să o implementăm!

Să revenim la core/src/commonMain/kotlin/Deck.kt.

În prezent, codul arată astfel:

val value: Int = 0 // TODO!

Vrem să înlocuim 0 cu valoarea cărții.

Deocamdată, dacă un pachet conține mai multe cărți sau nicio carte, vom continua să returnăm 0.

Prin urmare, avem nevoie de:

  • O modalitate de a lua o decizie: dorim un comportament diferit dacă există exact o carte sau dacă există 0 ori mai mult de o carte.
  • O modalitate de a număra cărțile dintr-un set: trebuie să știm dacă există exact o carte pentru a putea lua decizia.
  • O modalitate de a obține valoarea unei cărți, deoarece acesta este rezultatul dorit.
Luarea unei decizii

Deciziile reprezintă cea mai importantă parte a programării: astfel îi spunem calculatorului ce să facă. Există multe modalități de a exprima decizii, dar cea mai simplă este cuvântul-cheie if.

if (condition) {
    code-true
} else {
    code-false
}
Înlocuiește:

  • condiția din codul care decide ce ramură să urmeze. De exemplu, am văzut anterior o astfel de condiție în test: deck.value == 1, care verifică dacă proprietatea value a obiectului deck este egală cu 1. Rețineți că folosim două simboluri =, nu doar unul, pentru a face distincția față de atribuirea unei valori, așa cum se întâmplă în val value: Int = 0.
  • code-true reprezintă orice cod pe care dorești să îl rulezi dacă condition este true (succes).
  • code-false – orice cod pe care doriți să îl executați dacă condition este false (eșec).
Numărarea cărților

O mulțime de cărți poate conține orice număr de cărți. Deocamdată, dorim să gestionăm doar cazul cu o singură carte, așa că trebuie să le putem număra. Kotlin oferă unul dintre cele mai bogate API-uri dintre toate limbajele de programare pentru lucrul cu colecții, inclusiv mulțimi. Poți găsi proprietatea corectă?

De asemenea, găsește o modalitate de a accesa prima carte dintr-un set.

Obținerea valorii unei cărți

Cărțile sunt definite în fișierul Card.kt.

Acum că ai toate piesele, nu mai trebuie decât să asamblezi puzzle-ul!

Pentru a-ți verifica soluția, rulează din nou Check (JVM-only). Ar trebui să mai existe doar 13 teste eșuate, iar toate acestea ar trebui să implice, în mod obligatoriu, pachete cu mai mult de o carte.

După ce ai reușit să parcurgi această etapă, poți trece la următoarea. Dacă ai întrebări, nu ezita să îi întrebi pe organizatori!

4. Cărți multiple

Felicitări pentru primul pas!

Totuși, nu am terminat încă: un jucător poate plasa cu o carte mai mult decât cele aflate pe masă.

De exemplu, dacă pe masă se află cărțile 7 3 , un jucător trebuie să joace fie 2 cărți (același număr de cărți ca pe masă), fie 3 cărți (cu o carte mai mult decât pe masă).

Atunci când joci mai multe cărți simultan, toate cărțile trebuie:

  • Să fie de aceeași culoare, de exemplu 2 1 , sau
  • Să aibă aceeași valoare, de exemplu 3 3 .

Această verificare este deja implementată prin metoda isLegal() din Deck.kt.

Totuși, codul nostru calculează o valoare de 0 pentru orice pachet cu mai multe cărți. În schimb, valoarea ar trebui calculată folosind următoarele reguli:

Cărțile jucate trebuie să aibă o valoare mai mare decât cea de pe masă. Valoarea unui set de cărți este rezultatul concatenării valorilor cărților individuale, în ordine descrescătoare.

Exemple:

  • 7 3 are valoarea 73 (concatenarea cifrelor 7 și 3).
  • 3 3 are valoarea 33 (concatenarea cifrelor 3 și 3).
  • 1 2 are valoarea 21 (concatenarea cifrelor 2 și 1: cifra cea mai mare este prima).
  • 3 9 2 6 5 are valoarea 96532.

Observă că nu contează culoarea cărților. Nici ordinea cărților nu contează, întrucât valorile sunt întotdeauna în ordine descrescătoare.

Pentru a rezolva această provocare, avem nevoie de:

  • Deoarece ne interesează doar valoarea cărților, o modalitate de a transforma o listă de cărți într-o listă de valori.
  • O modalitate de a sorta valorile, pentru a ne asigura că le citim de la cea mai mare la cea mai mică.
  • O modalitate de a concatena valorile.
Conversia unei colecții în alta

Atunci când avem o listă cu elemente de un anumit tip, o putem transforma într-o listă cu elemente de alt tip, oferind o modalitate de a converti un element în altul. Aceasta este una dintre capacitățile programării funcționale: putem efectua orice operație asupra unei colecții dacă știm cum să o aplicăm unui singur element, folosind funcția .map {}.

De exemplu, putem obține prenumele unui jucător scris integral cu majuscule folosind player.name.uppercase().

Dacă avem mai mulți jucători într-o colecție de tip List<Player> sau Set<Player> numită players, putem scrie players.map { it.name.uppercase() }; rezultatul va fi o listă de tip List<String> (String înseamnă text). În interiorul acoladelor, folosim același cod ca pentru un singur jucător, dar utilizăm variabila specială it. Codul se va executa de mai multe ori (o dată pentru fiecare jucător). La fiecare execuție, jucătorul curent va fi reprezentat de it.

Sortarea

Sortarea este una dintre cele mai frecvente probleme în programare. Desigur, Kotlin oferă multiple modalități de a sorta elemente.

Cea mai simplă metodă este utilizarea funcției .sorted(), care poate sorta orice listă, cu condiția ca elementele acesteia să poată fi sortate într-o ordine naturală. Astfel de elemente sunt considerate „comparabile” (de tip Comparable). Unele tipuri de date sunt comparabile, altele nu. Tipurile numerice (precum Int, Float etc.) sunt comparabile și se sortează de la cea mai mică la cea mai mare valoare. Tipurile de text (Char, String) sunt comparabile și se sortează în ordine alfanumerică, pe baza codurilor Unicode (ordine lexicografică). Totuși, un obiect de tip Card nu este, prin natura sa, comparabil: care ar fi ordinea implicită? După valoare, după culoare sau după o combinație a celor două?

Rețineți că dorim valorile în ordine descrescătoare (de la cea mai mare la cea mai mică), însă funcțiile de sortare returnează implicit valorile în ordine crescătoare (de la cea mai mică la cea mai mare). Puteți găsi funcții utile în list.

Concatenarea valorilor

Atunci când avem valorile 5 și 4, dorim să obținem numărul 54. Acest proces se numește concatenare. Concatenarea nu este un operator matematic standard pentru tipurile numerice, ci unul standard pentru tipurile de text. Acest lucru conduce la două modalități principale și diferite de a rezolva problema: prin abordare textuală sau numerică.

Soluția bazată pe text este cea mai simplă de implementat. Aceasta utilizează funcția .joinToString() aplicată unei liste pentru a concatena toate elementele acesteia. Totuși, în mod implicit, rezultatul obținut este de forma 5, 4, nu 54. În plus, rezultatul este un String, dar noi trebuie să returnăm un Int; cum putem realiza acest lucru?

Soluția numerică este ceva mai complexă, dar este mai rapidă și consumă mai puțină memorie. Ea se bazează pe observația că concatenarea a două numere, 5 și 4, poate fi scrisă sub forma 5 * 10 + 4, ceea ce oferă rezultatul scontat, 54 (în limbajele de programare, simbolul * este adesea folosit pentru operatorul de înmulțire ×). Această regulă este valabilă și pentru mai multe numere: concatenarea numerelor 8, 3 și 2 poate fi scrisă astfel: (8 * 10 + 3) * 10 + 2. Pentru a combina elementele unei liste într-o singură valoare folosind un operator matematic, putem utiliza funcția .reduce {}.

Acum că deții toate piesele puzzle-ului, îl poți rezolva?

Odată ce codul tău este corect, toate testele ar trebui să ruleze cu succes.

Acum poți juca jocul pe bune! Felicitări!

5. Optimizează

Nivel: începător cu mai multă autonomie

Dacă dorești să mergi mai departe, putem parcurge câțiva pași pentru a optimiza și mai mult soluția noastră. Nu uita să rulezi din nou testele după fiecare modificare, pentru a te asigura că nu ai compromis soluția.

  1. În prezent, value este calculat o singură dată pentru fiecare Deck. Unele instanțe de Deck sunt create fără ca value să fie vreodată accesat. În schimb, am putea calcula value „lazy” (la cerere), adică în momentul în care este nevoie de el pentru prima dată.
  2. Dacă ai folosit concatenarea de tip text, înlocuiește-o cu concatenarea numerică; aceasta consumă mai puțină memorie și este puțin mai rapidă.
  3. Dacă ai folosit cod diferit pentru cazul cu o singură carte și pentru cel cu mai multe cărți, încearcă să le unifici astfel încât să folosești același cod pentru ambele situații.
  4. Dacă ai folosit cod diferit pentru cazul în care nu există nicio carte și pentru celelalte cazuri, încearcă să le unifici pentru a folosi același cod în toate situațiile. S-ar putea să te intereseze să afli mai multe despre null safety.
  5. Încearcă să eviți listele intermediare. De exemplu, .map {} creează o listă temporară. value poate fi implementat folosind o singură listă intermediară.
  6. Încearcă să simplifici codul cât mai mult posibil. În Kotlin, adesea, cel mai scurt cod este și cel mai ușor de înțeles, dar și cel mai eficient.

Cea mai simplă soluție găsită de noi utilizează doar două apeluri de funcție și o singură listă intermediară. Spune-ne dacă găsești o variantă mai bună!