(P) Binairo¶

Alkukommentti ja palautteen kieli¶

Tämän osion kohdassa Arviointi vaaditaan kooditiedoston alkukommentti. Sillä tarkoitetaan esimerkiksi seuraavan tyylistä kommenttia:

/* Binairo
 *
 * Kuvaus:
 *   Ohjelma toteuttaa Binairo-pelin. Pelissä on peliruudukko kooltaan 6 x 6.
 * Kukin ruutu sisältää nollan, ykkösen tai tyhjän. Tarkoituksena on lisätä
 * tyhjiin ruutuihin nollia ja ykkösiä seuraavien sääntöjen mukaisesti:
 * - kullakin vaaka- ja pystyrivillä saa olla korkeintaan kolme samaa lukua
 * - kullakin vaaka- ja pystyrivillä saa olla peräkkäin korkeintaan kaksi
 *   samaa lukua.
 *   Aluksi käyttäjältä kysytään, täytetäänkö peliruudukko satunnaisesti
 * arvottavilla merkeillä vai käyttäjän valitsemilla 36 merkillä.
 * Ensimmäisessä vaihtoehdossa käyttäjältä kysytään satunnaisluku-
 * generaattorin siemenlukua ja jälkimmäisessä häntä pyydetään syöttämään
 * 36 merkkiä, joiden oikeellisuus tarkistetaan.
 *   Joka kierroksella käyttäjältä kysytään lisättävän merkin koordinaatteja
 * sekä lisättävää merkkiä eli kolmea merkkiä. Peli päättyy pelaajan voittoon,
 * jos peliruudukko on saatu täytettyä e.m. sääntöjen mukaisesti. Ohjelma ei
 * salli tehdä lisäyksiä, jotka rikkovat e.m. sääntöjä, mutta on mahdollista
 * päätyä tilanteeseen, jossa mikään lisäys ei ole enää mahdollinen.
 *   Ohjelma tarkistaa annetut syötteet. Lisättävän merkin pitää olla nolla
 * tai ykkönen. Koordinaattien pitää olla peliruudukon sisällä, ja niiden
 * osoittaman ruudun pitää olla tyhjä.
 *
 * Ohjelman kirjoittaja ( Täytä omilla tiedoillasi )
 * Nimi: Teemu Teekkari
 * Opiskelijanumero: 123456
 * Käyttäjätunnus: teekkart ( Git-repositorion hakemistonimi. )
 * E-Mail: teemu.teekkari@tuni.fi
 *
 * Huomioita ohjelmasta ja sen toteutuksesta:
 *
 * */

Lisää siis yllä olevan tapainen kommentti tiedoston main.cpp ihan alkuun. Myös muissa kooditiedostoissa pitää olla opiskelijakohtaiset tiedot, mutta kuvausosuutta ei tarvitse toistaa jokaisessa tiedostossa, riittää, että se on pääohjelmatiedostossa.

Voit kirjoittaa kommentin myös englanniksi (ks. englannikielinen tehtävänanto), mutta kirjoita kaikki kommentit samalla kielellä. Muista vaihtaa yllä olevaan kommenttiin omat henkilökohtaiset tietosi.

Jos teette parityötä, muistakaa lisätä molempien henkilökohtaiset tiedot.

Pohjakoodi on kommentoitu sekä suomeksi että englanniksi, voit poistaa tarpeettomat kommentit.

Palautteen kieli valitaan palautuslaatikossa (tämän sivun lopussa). Palautteen kielenä on oletuksena suomi, mutta voit vaihtaa sen, jos haluat assistenttien antaman palautteen englanniksi. Kielivalinta määräytyy sen perusteella, minkä kielivalinnan olet tehnyt viimeisimmän palautuksen palautuslaatikossa.

Pelin säännöt¶

Pelin säännöt ovat hyvin yksinkertaiset, ja ne on selitetty edellä esitetyssä alkukommentissa sekä koottuna tässä. Pelin tavoitteena on saada aikaiseksi pelilauta, joka täyttää seuraavat vaatimukset:

• kullakin vaaka- ja pystyrivillä pitää olla sama määrä nollia ja ykkösiä
• kullakin vaaka- ja pystyrivillä saa olla peräkkäin korkeintaan kaksi samaa lukua.

Alkuperäisessä Binairo-pelissä on vielä kolmaskin sääntö. Lisäksi alkuperäisessä pelissä erikokoiset peliruudukot ovat mahdollisia, mutta projektissa käytetään 6 x 6 -kokoista ruudukkoa.

Binairo vs vesipisarapeli¶

Tällä kierroksella kuvataan vesipisarapeli, jossa on käytetty vektoreita, jonka alkiot ovat vektoreita. Edelleen sisemmän vektorin alkiot ovat ruutuja (Square-olioita). Tässä projektissa on samanlainen rakenne siinä mielessä, että myös Binairon peliruudukko on vektori, jonka alkiot ovat vektoreita. Tässä kuitenkin sisemmän vektorin alkiot ovat luettelotyypin (enum) arvoja, eli ne ovat yksinkertaisempia kuin vesipisarapelin ruudut, ja siksi niitä ei tarvitse kuvata luokkana.

Vesipisarapelissä jokaisella ruudulla on osoitin pelilautaan, koska jokaisen ruudun pitää tuntea viereiset ruudut. Projektissa ei ole tarvetta tällaiseen eikä osoittimiin muutenkaan.

Pelilaudan alustava täyttäminen¶

Tehtävänä on toteuttaa Binairo-peli, joka noudattaa edellä kuvattuja sääntöjä. Tarkastellaan ensin peliruudukon alustavaa täyttämistä.

Ohjelman alussa käyttäjältä kysytään ruudukon täyttötapaa:

Select start (R for random, I for input): x
Select start (R for random, I for input): yy
Select start (R for random, I for input): x y z
Select start (R for random, I for input): r
Enter a seed value: 2
Bad seed
Select start (R for random, I for input):

Kysymystä toistetaan, kunnes käyttää antaa merkkijonon "R" tai "I" (isoilla tai pienillä kirjaimilla).

Koska käyttäjä valitsi täyttämisen satunnaisesti valituilla luvuilla, ohjelma kysyy seuraavaksi satunnaislukugeneraattorin siemenlukua. Annetusta siemenluvusta tarkistetaan, ettei se kuulu huonoihin siemenlukuihin eli sellaisiin, jotka (ilmiselvästi) tuottavat ratkeamattoman pelilaudan. Huonot siemenluvut välillä [1..50] on koottu pohjakoodissa olevaan vektoriin BAD_SEEDS, joka löytyy tiedostosta gameboard.hh. Edellä nähdään, että esimerkiksi 2 on huono. Huonon siemenluvun tapauksessa ohjelma tulostaa virheilmoituksen Bad seed, ja sen jälkeen aloitustapaa kysytään uudelleen.

Sen sijaan 1 ei ole huono siemenluku:

Select start (R for random, I for input): r
Enter seed value: 1
===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 | 0 1       1 |
| 2 | 0           |
| 3 |   0 0     0 |
| 4 |   0         |
| 5 |     0       |
| 6 |       0     |
===================
Enter two coordinates and a fill symbol, or q to quit:

(Siemenluku 1 ei ole huono, koska alkutilanteessa pelilauta noudattaa pelin sääntöjä. Ei-huonoillakin siemenluvuilla voidaan myöhemmin päätyä ratkeamattomiin tilanteisiin, mutta tästä ei tarvitse mitenkään välittää.)

Ei-huonon siemenluvun antamisen jälkeen tulostetaan siemenluvun tuottamilla satunnaisluvuilla täytetty pelilauta.

Jos käyttäjä olisi valinnut ei-satunnaisen täyttötavan, ohjelma olisi edennyt esimerkiksi näin:

Select start (R for random, I for input): i
Input: " 1     10 0   0   0   0          10 "
===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 |   1         |
| 2 |   1 0   0   |
| 3 |     0       |
| 4 | 0       0   |
| 5 |             |
| 6 |       1 0   |
===================
Enter two coordinates and a fill symbol, or q to quit:

Tällöin käyttäjän antamat merkit sijoitellaan pelilaudalle riveittäin.

Käyttäjän antamasta syötteestä pitää tarkistaa, että syöte sisältää vain nollia, ykkösiä ja välilyöntejä ja että näitä merkkejä on oikea määrä. Lisäksi syötteen alussa ja lopussa on jokin merkki (esim. lainausmerkki kuten yllä), sillä muutenhan olisi vaikea tietää, mihin varsinainen syöte päättyy, jos sen lopussa on tyhjiä merkkejä. Näin ollen syötteen oikea pituus on 38 (6 * 6 + 2) merkkiä, mutta ensimmäinen ja viimeinen jätetään huomioimatta, ne voivat siis olla mitä tahansa. (Huomaa erityisesti, että pohjakoodin funktiossa select_start, sen else-haarassa getline-funktion kutsun jälkeen lainausmerkit tms. ovat vielä mukana.)

Syöte voi olla kahdella tavalla virheellinen:

Select start (R for random, I for input): i
Input: "   0  1"
Wrong size of input
Select start (R for random, I for input): i
Input: " 1     10 0   0   0   0          12 "
Wrong character
Select start (R for random, I for input): r
Enter a seed value: 1
===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 | 0 1       1 |
| 2 | 0           |
| 3 |   0 0     0 |
| 4 |   0         |
| 5 |     0       |
| 6 |       0     |
===================
Enter two coordinates and a fill symbol, or q to quit:

Kuten edellisessä esimerkkiajossa nähdään, ohjelma tulostaa joko virheilmoituksen Wrong size of input tai Wrong character. Tämän jälkeen käyttäjä voi valita aloitustavan uudelleen.

Merkkien lisääminen pelilaudalle¶

Kun pelilauta on saatu valmiiksi varsinaista pelaamista varten, käyttäjä voi syöttää lisättävän merkin koordinaatteineen. Jos jompikumpi koordinaateista ei ole välillä [1..6], ohjelma tulostaa:

Out of board

Jos lisättävä merkki on jotakin muuta kuin nolla tai ykkönen, ohjelma tulostaa:

Invalid input

Jos käyttäjä antaa epätyhjän ruudun koordinaatit, tai jos lisääminen rikkoisi pelin sääntöjä, ohjelma tulostaa:

Can't add

Kaikkien edellä mainittujen virheilmoitusten jälkeen ohjelma kysyy syötteitä uudelleen.

Nämä tilanteet näkyvät seuraavassa ajoesimerkissä:

===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 |   1         |
| 2 |   1 0   0   |
| 3 |     0       |
| 4 | 0       0   |
| 5 |             |
| 6 |       1 0   |
===================
Enter two coordinates and a fill symbol, or q to quit: 1 7 0
Out of board
Enter two coordinates and a fill symbol, or q to quit: xx yy 0
Out of board
Enter two coordinates and a fill symbol, or q to quit: 2 3 xx yy
Invalid input
Enter two coordinates and a fill symbol, or q to quit: 2 3 4
Invalid input
Enter two coordinates and a fill symbol, or q to quit: 2 3
Invalid input
Enter two coordinates and a fill symbol, or q to quit: 2 2 1
Can't add
Enter two coordinates and a fill symbol, or q to quit: 5 1 0
Can't add
Enter two coordinates and a fill symbol, or q to quit: 2 3 1
Can't add
Enter two coordinates and a fill symbol, or q to quit: 2 3 0
===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 |   1         |
| 2 |   1 0   0   |
| 3 |   0 0       |
| 4 | 0       0   |
| 5 |             |
| 6 |       1 0   |
===================
Enter two coordinates and a fill symbol, or q to quit:

Huomaa, että jos koordinaateiksi annetaan jotakin muuta kuin numeroita, ohjelma tulostaa tällöinkin Out of board. Tässä koodipohjan funktio stoi_with_check on kätevä: Se palauttaa nollan, jos parametrina oleva merkkijono ei ole numeerinen, ja nollahan on pelilaudan ulkopuolella.

Huomaa myös, että pelilauta tulostetaan ohjelman alussa ja sen jälkeen vain muutosten jälkeen.

Jatkamalla yllä olevasta tilanteesta saadaan peli pelattua onnistuneesti loppuun esimerkiksi seuraavasti:

===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 | 0 1 1 0 1 0 |
| 2 | 0 1 0 1 0 1 |
| 3 | 1 0 0 1 1 0 |
| 4 | 0 1 1 0 0 1 |
| 5 | 1 0 1 0 1 0 |
| 6 | 1 0 0 1 0   |
===================
Enter two coordinates and a fill symbol, or q to quit: 6 6 1
===================
|   | 1 2 3 4 5 6 |
-------------------
| 1 | 0 1 1 0 1 0 |
| 2 | 0 1 0 1 0 1 |
| 3 | 1 0 0 1 1 0 |
| 4 | 0 1 1 0 0 1 |
| 5 | 1 0 1 0 1 0 |
| 6 | 1 0 0 1 0 1 |
===================
You won!

Viimeisimmässä pelilaudan tilanteessa edellä kerrotut vaatimukset täyttyvät, joten pelaaja voitti, ja ohjelma tulosti tekstin You won!.

Pelaaja voi myös lopettaa pelin kesken:

Enter two coordinates and a fill symbol, or q to quit: q
Quitting ...

Tällöin ohjelma tulostaa yllä näkyvän tekstin Quitting ... ja lopettaa toimintansa.

Erilaiset täyttötavat ohjelman alussa¶

Kuten edellä on nähty, ruudukon täyttämiseen on kaksi tapaa. Satunnaisesti valituilla luvuilla ruudukko voidaan täyttää helposti, mutta tässä tavassa on se huono puoli, että pelistä ei juuri koskaan (ei edes ei-huonoilla satunnaisluvuilla) tule ratkeava, vaan päädytään mahdottomaan tilanteeseen, eikä peliä voi pelata loppuun.

Jos haluat testata peliäsi ratkeavilla syötteillä (mikä on tietenkin erittäin suositeltavaa), täytä pelilauta ei-satunnaisesti joillakin seuraavista syötteistä:

" 1     10 0   0   0   0          10 "
"      1   0   11  1      0 0    1  0"
"  0 0 1        1    11         0  0 "
"   1       0    0 0  00   1  1      "
"   11  00   00          1  0       1"
"  01     1 1      01    0  0    0   "
" 1   1 00  0      1     00  0     0 "
"1    0   1  0 0    1  1    11       "
"        1 11 0    1  0      101 0   "
" 1 1  1    1      1  11  1  11      "

Huomaa, että ei-satunnaisessa täytössä annetut luvut pitää sijoittaa pelilaudalle riveittäin. Jos sijoitat ne sarakkeittain, ohjelmasi ei läpäise automaattitestejä.

Kun luet 36 (38) merkin rivin, voit käyttää funktiota getline ja erotella sitten syötemerkkijonon erillisiksi numeroiksi. Toinen vaihtoehto on käyttää operaattoria >> 36 (38) kertaa (esimerkiksi for-silmukassa).

Voit olettaa, että ei-satunnaisessa täytössä käytetään vain ratkeavia syötteitä esim. yllä lueteltuja rivejä. Ohjelmassa ei siis tarvitse tarkistaa, noudattaako syöterivi pelin sääntöjä.

Tarkastelemalla yllä olevia ratkeavia syöterivejä, huomataan, että tyhjiä on enemmän kuin nollia ja ykkösiä. Vastaava tilanne halutaan myös satunnaistäyttöön. Nimittäin jos pelilauta täytettäisiin satunnaisesti niin, että kaikilla kolmella merkillä olisi sama todennäköisyys, pelilauta tulisi liian täyteen. Todennäköisesti jo heti alussa kävisi niin, että jossakin kohdassa olisi kolme nollaa tai kolme ykköstä peräkkäin.

Tästä syystä pohjakoodissa on vakio DISTR_UPPER_BOUND:

// Vakio todennäköisyysjakauman ylärajaa varten.
// Nollilla ja ykkösillä on sama todennäköisyys, vaikkapa x, ja tyhjien
// todennäköisyyden voidaan arvioida olevan 6x, jolloin jakaumassa
// on yhteensä kahdeksan pistettä (lukua), joten sopiva väli on esim. [0..7].
const int DISTR_UPPER_BOUND = 7;

Voit siis arpoa satunnaislukuja välillä [0..7] eli välillä [0..DISTR_UPPER_BOUND] niin, että satunnaisluvulla 0 laudalle sijoitetaan merkki 0, satunnaisluvulla 1 merkki 1 ja satunnaisluvuilla [2..7] tyhjä. Tällä tavalla saadaan yllä olevassa kommentissa kerrottu satunnaisuus.

Tästä huolimatta voi käydä niin, että pelilaudalla on heti alussa kolme nollaa tai kolme ykköstä peräkkäin. Tällöin peli ei anna lisätä yhtäkään merkkiä, mutta voit käynnistää ohjelman uudelleen ja kokeilla jotakin toista siemenlukua. (Välin [1..50] luvut on testattu, ja huonot on koottu pohjakoodin vektoriin BAD_SEEDS.)

Ohjelman toteuttaminen osissa¶

Käytä versionhallintaa projektia tehdessäsi siten, että versionhallinnasta löytyy vähintään viisi committia seuraavasti:

• Ohjelma tulostaa peliruudukon.
• Ohjelma tarkistaa, ettei vaaka- tai pystyrivillä ole liikaa samoja numeroita.
• Ohjelma tarkistaa, ettei vaaka- tai pystyriveillä ole liikaa samoja numeroita peräkkäin.
• Lisäksi sinun on tehtävä vähintään kaksi muuta committia (edellämainittuja ennen, niiden jälkeen tai niiden välissä).

Edellä mainitut välivaiheet pitää myös olla commit-viesteissä mainittu selkeästi, jotta assistentti löytää ne helposti työtä tarkastaessaan. Voit kuitenkin jakaa yllä lueteltuja committeja useaksi commitiksi.

Vinkkejä tehtävän tekemiseen¶

• Ohjelman pitää siis tarkistaa, voidaanko käyttäjän antama merkki lisätä annettuun kohtaan. Mieti, kumpi on helpompaa: tehdä tarkistus ennen lisäämistä, vai lisätä ensin ja tarkistaa sitten, onko kaikki vielä kunnossa. Tarvittaessa (jos kaikki ei ole kunnossa), niin juuri lisätty merkki pitää tietenkin poistaa. Tehokkuudesta ei tarvitse välittää.
• Ohjelmassa riittää käyttää STL:n vector-säiliöitä, mutta halutessasi voit käyttää muitakin STL:n säiliöitä.

• Vesipisarapelistä voit katsoa mallia sellaisen vektorin määrittelyyn, jonka alkiot ovat vektoreita (square.hh, rivi 12). Muilta osin esimerkki ei ole kovin oleellinen.

Erityisvaatimukset¶

Ohjelmassa pitää käyttää pohjakoodissa annettua enum-tyyppiä (Element_type tiedostossa gameboard.hh). Sen käyttämättä jättämisestä (ja korvaamisesta esim. merkkijonotyypillä) sakotetaan 10 pistettä.

Ohjelmassa pitää käyttää pohjakoodissa annettua luokkaa (GameBoard). Kiinnitä huomiota siihen, mitä koodia toteutat tähän luokkaan ja mitä pääohjelmamoduuliin. Mitä attribuutteja luokalla voisi luontevasti olla? Entä mitä metodeja sillä voisi olla?

Kirjoita pelilautaa käsittelevät metodit edellä mainittuun luokkaan, kun taas esimerkiksi käyttöliittymää käsittelevä koodi (esimerkiksi syötteiden lukeminen) sopii pääohjelmamoduuliin.

Arviointi¶

Jotta työ päätyisi assistenttien arvioitavaksi, sen pitää ensin läpäistä automaattitestit. Automaattitestit eivät hyväksy ohjelmaa, jonka kääntäminen tuottaa varoituksia. Jos saat automaattitesteistä 0 pistettä, myös lopullinen pistemääräsi on 0, eikä työ mene assistenttien arvioitavaksi.

Assistentti arvioi ja pisteyttää automaattitestit läpäisseistä (= 1 p) töistä viimeisimmän Plussa-palautuksen, joka on tehty määräajan loppuun mennessä, seuraavien arviointikriteerien mukaan:

• Ratkaisun yleisperiaate: 0-20 pistettä:
  • Tehtävän osaamistavoitteet on saavutettu.
  • Ohjelmakoodi on jaettu funktioita, luokkia ja/tai metodeita käyttäen loogisiksi kokonaisuuksiksi, jotka ovat sopivan pituisia.
  • Jos luokkia/olioita on käytetty, n on toteutettu olio-ohjelmoinnin periaatteita noudattaen (ks. edellinen materiaaliosio: Tyyliseikkoja, erityisesti kohta Olio-ohjelmointi).
  • Tietorakenne ei sisällä toisteista eikä turhaa tietoa. Valittuja tietorakenteita on käytetty järkevästi.
  • Ohjelmakoodi ei sisällä turhaa toisteisuutta eikä muutakaan turhaa.
  • Ohjelmakoodi ei sisällä tarpeettomia rajoitteita tai oletuksia tai muita väkinäisiä ratkaisuita.
  • Ohjelmarakenteet on toteutettu helposti ymmärrettäviksi.
  • Ohjelmakoodissa ei ole käytetty globaaleja muuttujia (globaalit const-vakiot ovat OK).
  • Ohjelman toimintaa ei lopeteta exit-funktiota käyttäen.
• Ohjelmointityyli: 0-20 pistettä:
  • Muuttujat ja funktiot nimetty selkeästi ja kuvaavasti. Nimeämisessä on käytetty vain yhtä kieltä, ei esim. suomea ja englantia sekaisin.
  • Koodissa on käytetty nimettyjä vakioita taikalukujen sijasta.
  • Ohjelmakoodi on asemoitu siististi.
  • Ohjelmakoodirivit ovat enintään 80 merkkiä pitkiä.
  • Jokaisen tiedoston alussa on kommentti, josta käy ilmi tiedoston tarkoitus, työn tekijä(t) ja muut tarvittavat tiedot (ks. kohta Alkukommentti).
  • Jokaisen funktion/metodin alussa on kommentti, joka kuvaa sen toiminnan, paluuarvon ja parametrit. Tämä kommentti kirjoitetaan otsikkotiedostoon, jos sellainen on olemassa.
  • Kommentteja on muutenkin tarpeellisissa kohdissa.
  • Kommentit liittyvät toteutettuun ohjelmaan eivätkä johonkin sen vanhempaan versioon.
  • Kaikki kommentit on kirjoitettu samalla kielellä (fi/en), mutta kommentoinnissa saa käyttää eri kieltä kuin muuttujien ym. nimissä.
  • Kaikki muuttujat on alustettu.
  • Kääntäjä ei anna koodia käännettäessä varoituksia.
• Versionhallinnan käyttö: 0-10 pistettä:
  • Committeja on riittävä määrä.
  • Commit-viestien sisältö on selkeä ja kuvaava.