(P) Kansalaisopisto¶

Alkukommentti ja palautteen kieli¶

Samoin kuin ensimmäisessä projektissa, tässäkin projektissa vaaditaan alkukommentti. Tällä kertaa alkukommenttia ei anneta valmiina, vaan sinun pitää kirjoittaa se itse. Mallia voit katsoa ensimmäisen projektin tehtävänannosta (4.5 (P) Binairo).

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.

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

Ohjelman käsittelemä tieto¶

Ajatellaan seuraavan kaltaista informaatiota kurssitarjonnasta ja ilmoittautumismääristä eri paikkakunnilla:

Lempäälä
    Languages
        English             20
    Exercise
        Hiit                10
        Pilates             5
        Yoga                3
    Handcraft
        Hammering           full
    Music
        Karaoke             full
Pirkkala
    Handcraft
        Weawing             2
    Exercise
        Hiit                full
    Languages
        German              3
    Music
        Karaoke             1
    Cooking
        Christmas food      3
Vesilahti
    Dance
        Zumba               8
    Information technology
        Excel               full
    Handcraft
        Weawing             full
        Hammering           10
        Dressmaking         4
    Cooking
        Baking              full
    Music
        Guitar              3
    Exercise
        Fitness boxing      7
    Languages
        English             3
Nokia
    Exercise
        Hiit                1
    Dance
        Zumba               2

Yllä olevassa esimerkissä eri paikkakunnilla voi olla samoja kursseja, mutta niiden osallistujamäärät voivat vaihdella, ja eri paikkakunnilla ei välttämässä ole saatavilla kaikkia kursseja.

Edellä olevan listan tiedot voidaan esittää csv-tiedostona, jonka rivit ovat muotoa:

<paikkakunta>;<teema>;<kurssin_nimi>;<osallistujien_määrä>

jossa <osallistujien_määrä> voi olla positiivinen kokonaisluku tai literaalinen merkkijono “full”. Kurssi on täynnä, jos sille on ilmoittautunut 50 osallistujaa.

Voit olettaa, että <paikkakunta> koostuu vain yhdestä sanasta. Sen sijaan <teema> ja <kurssin_nimi> voivat koostua useista sanoista.

Yllä käytetty esimerkki näyttäisi syötetiedostoksi kuvattuna siis esimerkiksi seuraavalta:

Lempaala;Languages;English;14
Pirkkala;Handcraft;Weawing;2
Pirkkala;Exercise;Hiit;full
Vesilahti;Dance;Zumba;8
Pirkkala;Languages;German;3
Vesilahti;Information technology;Excel;full
Lempaala;Exercise;Hiit;10
Vesilahti;Handcraft;Weawing;full
Lempaala;Handcraft;Hammering;full
Vesilahti;Cooking;Baking;full
Pirkkala;Music;Karaoke;1
Vesilahti;Handcraft;Hammering;10
Vesilahti;Handcraft;Dressmaking;4
Lempaala;Exercise;Pilates;5
Lempaala;Exercise;Yoga;3
Lempaala;Languages;English;20
Pirkkala;Cooking;Christmas food;3
Lempaala;Music;Karaoke;full
Vesilahti;Music;Guitar;3
Vesilahti;Exercise;Fitness boxing;7
Vesilahti;Languages;English;3
Nokia;Exercise;Hiit;1
Nokia;Dance;Zumba;2

Kenttiä on rivillä neljä kappaletta, ja mikään kenttä ei saa olla tyhjä tai muodostua pelkistä välilyöntimerkeistä. Viimeisen kentän on oltava positiivista kokonaislukua esittävä merkkijono tai sana “full”.

Huomaa, kuinka rivien ei tarvitse csv-tiedostossa olla missään erityisessä järjestyksessä. Syötetiedostossa ei myöskään käytetä skandinaavisia kirjaimia.

Mikäli syötetiedostossa on saman paikkakunnan samalle kurssille esitetty tiedot useammin kuin kerran, voimaan jää se tieto joka tuli vastaan tiedostossa viimeisimpänä. Esimerkiksi yllä olevassa syötetiedossa Lempäälän English-kurssi esiintyy kaksi kertaa. Ensimmäisellä rivillä osanottajamäärä on 14 ja tiedoston loppupäästä löytyvällä rivillä 20. Osanottajamäärä 20 jää voimaan siksi, että se oli jäljempänä, ei siksi että se oli luvuista suurempi.

Ohjelman toiminta¶

Kun ohjelma käynnistyy, se lukee käyttäjältä syötetiedoston nimen:

Input file: courses.input

Mikäli syötetiedostoa ei saa avattua luettavaksi, tulostetaan käyttäjälle teksti:

Error: the input file cannot be opened

Tämän jälkeen ohjelman suoritus päättyy ilman mitään muita tulosteita paluuarvoon EXIT_FAILURE.

Mikäli syötetiedosto saadaan avattua, mutta tiedosto ei ole määritelmän mukainen, esimerkiksi kenttiä ei ole neljää tai kentästä puuttuu arvo, tulostetaan käyttäjälle virheilmoitus Error: empty field, ja lopetetaan ohjelman suoritus paluuarvoon EXIT_FAILURE. Esimerkiksi:

Input file: courses-not-enough-fields.input
Error: empty field

Ohjelma jäsentelee tiedostosta lukemansa rivit ja tallentaa eri paikkakuntien kurssitiedot sopivaan sisäiseen tietorakenteeseen. Tietorakenne on ohjelmoijan itsensä päätettävissä, kunhan se noudattaa kaikkia kohdassa “Erityisvaatimukset” asetettuja lisäehtoja.

Kun tiedosto on luettu, ohjelma aloittaa varsinaisen suorituksensa. Aina kun käyttäjältä odotetaan syötettä, tulostetaan rivin alkuun > (> ja välilyönti):

>

Tähän kehotteeseen ohjelman käyttäjä voi syöttää seuraavia käskyjä:

1. quit - Ohjelman suoritus päätty paluuarvoon EXIT_SUCCESS ilman, että ohjelma tulostaa mitään.

2. locations - Tulostaa aakkosjärjestyksessä allekkain kaikki tunnetut paikkakunnat. Esimerkiksi:

   > locations
   Lempaala
   Nokia
   Pirkkala
   Vesilahti
   >
   

3. themes_in_location <paikkakunta> - Tulostaa aakkosjärjestyksessä allekkain kaikki annetun paikkakunnan teemat. Esimerkiksi:

   > themes_in_location Vesilahti
   Cooking
   Dance
   Exercise
   Handcraft
   Information technology
   Languages
   Music
   >
   

4. courses <paikkakunta> <teema> - Komento tulostaa kurssin nimen mukaisessa aakkosjärjestyksessä kaikki kyseisen paikkakunnan kurssit, jotka löytyvät kyseiseltä paikkakunnalta ja kyseisestä teemasta sekä osallistujamäärät. Esimerkiksi:

   > courses Lempaala Exercise
   Hiit --- 10 enrollments
   Pilates --- 5 enrollments
   Yoga --- 3 enrollments
   >
   

   Tai jos kurssi on täynnä, tulostus näyttää seuraavalta:

   > courses Vesilahti "Information technology"
   Excel --- full
   >
   

   Yllä olevassa esimerkissä näkyy myös, että useasta sanasta koostuva parametri pitää ympäröidä lainausmerkeillä. Ainoastaan teema on sellainen parametri, joka voi koostua useasta sanasta. (Myös kurssin nimi voi koostua useasta sanasta, mutta sitä ei käytetä minkään komennon parametrina.)

   Vaikka teema ei koostuisikaan useasta sanasta, se voidaan silti ympäröidä lainausmerkeillä. Esimerkiksi:

   > courses Nokia "Dance"
   Zumba --- 2 enrollments
   >
   

5. available - Komento tulostaa näytölle kaikkien paikkakuntien kaikista kursseista ne, joille voi vielä ilmoittautua eli jotka eivät ole täynnä. Kursseista tulostetaan paikkakunta, teema ja nimi. Tulostettavassa listassa kurssit ovat aakkosjärjestyksessä ensin paikkakunnan, sitten teeman ja lopuksi kurssin nimen mukaan.

   Esimerkki valaisee asiaa parhaiten:

   > available
   Lempaala : Exercise : Hiit
   Lempaala : Exercise : Pilates
   Lempaala : Exercise : Yoga
   Lempaala : Languages : English
   Nokia : Dance : Zumba
   Nokia : Exercise : Hiit
   Pirkkala : Cooking : Christmas food
   Pirkkala : Handcraft : Weawing
   Pirkkala : Languages : German
   Pirkkala : Music : Karaoke
   Vesilahti : Dance : Zumba
   Vesilahti : Exercise : Fitness boxing
   Vesilahti : Handcraft : Dressmaking
   Vesilahti : Handcraft : Hammering
   Vesilahti : Languages : English
   Vesilahti : Music : Guitar
   >
   

6. courses_in_theme <teema> - Komento tulostaa kaikilta paikkakunnilta annettuun teemaan kuuluvat kurssit aakkosjärjestyksessä. Esimerkiksi:

   > courses_in_theme Exercise
   Fitness boxing
   Hiit
   Pilates
   Yoga
   >
   

7. favorite_theme Komento tulostaa suosituimman teeman. Kuhunkin teemaan kuuluvien kurssien osanottajamäärät lasketaan siis yhteen ja tulostetaan tämä suurin osanottajamäärä sekä teema (tai teemat), joilla on suurin osanottajamäärä. Esimerkiksi:

   > favorite_theme
   116 enrollments in themes
   --- Handcraft
   >
   

   Komennossa oletetaan, että jos kurssi on täynnä, sillä on 50 osallistujaa.

   Katsotaan vielä lisäesimerkki tapauksesta, jossa suurin osanottajamäärä on useammalla teemalla. Jos syötetiedoston sisältö olisi:

   Lempaala;Languages;English;14
   Pirkkala;Handcraft;Weawing;2
   Vesilahti;Handcraft;Hammering;12
   Lempaala;Exercise;Pilates;5
   Lempaala;Exercise;Yoga;3
   

   komento tulostaisi:

   > favorite_theme
   14 enrollments in themes
   --- Handcraft
   --- Languages
   >
   

   Jos syötetiedosto ei ole tyhjä, niin jokin teema on suosituin. Tyhjän tiedoston tapauksessa komento tulostaa:

   > favorite_theme
   No enrollments
   >
   

Kun käyttäjän syöttämä komento on suoritettu, ohjelma tulostaa kehotteen uudelleen. Tätä jatketaan kunnes käyttäjä syöttää käskyn quit.

Virhetilanteet¶

Mikäli käyttäjän syöte on virheellinen, tulostetaan virheeseen liittyvä virheilmoitus, minkä jälkeen ohjelma palaa odottamaan käyttäjän syötettä. Ohjelman suoritus ei siis pääty käyttäjän virheelliseen syötteeseen.

Käyttäjän syöttäessä tuntemattoman komennon, tulostetaan virheilmoitus:

> jotakin
Error: Unknown command: jotakin
> joku_komento parametri
Error: Unknown command: joku_komento
>

Mikäli komennolle annetaan väärä määrä parametreja, tulostetaan virheilmoitus Error: error in command <komento> kuten alla:

> courses Lempaala
Error: error in command courses
>

Komennolle themes_in_location on mahdollista antaa paikkakunta, jota ei löydy. Tällöin käyttäjälle tulostetaan virheilmoitus:

> themes_in_location joku_paikkakunta
Error: unknown location
>

Komennolle courses_in_theme on mahdollista antaa teema, jota ei löydy. Tällöin käyttäjälle tulostetaan virheilmoitus:

> courses_in_theme joku_teema
Error: unknown theme
>

Komentoon courses liittyy kaksi erillistä virheilmoitusta. Mikäli käyttäjän syöttämää paikkakuntaa ei löydetä, tulostetaan virheilmoitus Error: unknown location name ja mikäli annettua tekijää ei löydetä, tulostetaan virheilmoitus Error: unknown theme kuten alla:

> courses joku_paikkakunta Exercise
Error: unknown location name
> courses Lempaala joku_teema
Error: unknown theme
> courses joku_paikkakunta joku_teema
Error: unknown location name

Jos sekä paikkakunta että teema ovat tuntemattomia, annetaan ilmoitus tuntemattomasta paikkakunnasta, kuten näkyy yllä olevan esimerkin viimeisestä kohdasta.

Erityisvaatimukset¶

Seuraavia vaatimuksia on noudatettava, mikäli haluaa työstä hyväksytyn arvosanan:

• Syötetiedoston saa lukea vain kerran ohjelman suorituksen aikana.

• Minkä STL-tietorakenteen tai tietorakenteiden yhdistelmän valitsetkin työhösi, sinun on käytettävä ainakin yhtä map-rakennetta. Tämän map-rakenteen on oltava osana sitä rakennetta, johon tiedostosta luettu informaatio talletetaan myöhempiä hakuja varten.

• Kun tallennat tiedostosta luettuja kurssien tietoja STL-rakenteeseesi, sinun on käytettävä niiden tallentamiseen seuraavaa struct-rakennetta:

  struct Course {
      string name;
      string theme;
      int enrollments;
  };
  

  Tämän struct-rakenteen on siis oltava sen STL-rakenteen alkiotyyppinä, jonne kurssien tietoja talletetaan.

  Voit käyttää ohjelmassasi myös vastaavaa suomenkielistä struct-rakennetta.

Vihjeitä¶

• Voit käyttää syötetiedoston ja käyttäjän antamien syötteiden paloitteluun viikkoharjoituksissa toteutettua split-funktiota. Toteutus on annettu myös koodipohjassa tehtävään 6.1.2 Vektorin alkioiden summa.
• Muistathan, missä järjestyksessä map- ja set-rakenteiden alkiot käydään iteraattorilla läpi.

Ohjelman toteuttaminen osissa¶

Ohjelman toteutus muodostuu pääpiirteiltään kolmesta osasta:

• tietorakenteen valinta ja tiedoston lukeminen tietorakenteeseen
• käyttöliittymä
• hakualgoritmit.

Mieti tarkasti, missä järjestyksessä nuo kannattaa toteuttaa, jotta voit toteuttaa ja testata ne yksi kerrallaan, ennen kuin siirryt seuraavaan vaiheeseen. Vähimmäisvaatimuksena versionhallinnan käyttämiselle on, että nämä kolme osaa on toteutettu omina committeinaan, mutta parempi tietenkin olisi että committeja olisi enemmän.

Yllä luetellut commitit saa jakaa useampaan osaan.

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) sekä tehtävänannon erikoisvaatimukset täyttävistä töistä viimeisen määräajan puitteissa tehdyn commitin seuraavien arviointikriteerien mukaan:

• Ratkaisun yleisperiaate: 0-30 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 ja olioita on käytetty, ne on toteutettu olio-ohjelmoinnin periaatteita noudattaen (ks. 4-kierroksen Tyyliseikoista 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-10 pistettä:
  • Muuttujat ja funktiot nimetty selkeästi ja kuvaavasti. Nimeämisessä on käytetty vain yhtä kieltä, ei esim. suomea ja englantia sekaisin.
  • Ohjelmassa on käytetty nimettyjä vakioita taikalukujen sijasta.
  • Ohjelmakoodi on asemoitu siististi.
  • Koodirivien pituus on enintään 80 merkkiä.
  • Jokaisen tiedoston alussa on kommentti, josta käy ilmi tiedoston tarkoitus, työn tekijä(t) ja muut tarvittavat tiedot. (ks. 1-projektin tehtävänanto kierrokselta 4).
  • Jokaisen funktion/metodin alussa (otsikkotiedostossa jos sellainen on) on kommentti, joka kuvaa sen toiminnan, paluuarvon ja parametrit.
  • 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.