• rpn32_init()
• rpn32_view()
  • Znaky formátovacího řetězce:
    • zástupné
    • řídicí
• rpn32_list()
• rpn32_mem()
• rpn32_enter()
• rpn32_tenter()
• rpn32_rdn()
• rpn32_regx()
• rpn32_run()
• rpn32_gto()
• rpn32_now()

Seznam funkcí

Popis funkcí se v souladu s novým řešením nese v duchu úspor a zjednodušení. Chybí zde samostatné stránky věnované každé funkci API, jak tomu bylo v případě RPNPROC. Všechno (konstanty, typy, prototypy funkcí a jejich návratové hodnoty) je srozumitelně popsáno v headeru rpn32.h a pouhý přepis náležitostí se sofistikovanější grafickou úpravou by byl nošením dříví do lesa. Obsahem této kapitoly proto bude slovní popis činností funkcí a zdůraznění rozdílů mezi API předchozího a současného provedení (tedy opět duel RPN32 vs. RPNPROC).

Následující tabulka sumarizuje funkce obou vrstev s přihlédnutím na jejich určení. Ve sloupci DRUH jsou zkratková slova členící celý sortiment. Jejich významy jsou jasné, přesto: STK je RPN stack, DBG znamená debug. (Za povšimnutí stojí fakt, že sufixy názvů funkcí se ve většině případů shodují s nápisy na/okolo tlačítek skutečných kalkulátorů.)

Popisy funkcí

Funkce rpn32_init()

Jediným zástupcem druhu INIT je právě tato inicializační funkce. Samotné její použití není třeba nijak zvlášť rozebírat. Co funkci prostřednictvím argumentů dát a co od ní v podobě návratové hodnoty očekávat, je jasné z headeru rpn32.h. Daleko zajímavější bude seznámení se s posláním uživatelské funkce, jejíž adresou je naplněn argument __fncp této funkce. Tento callback volá vrstva RPN32 ze tří různých důvodů rozlišených hodnotou argumentu __type:

1. RPN32_INIT_CB_TYPE_MEMORY  - Pro inicializační proceduru je třeba (další) příděl paměti.
2. RPN32_INIT_CB_TYPE_LINE    - Žádost o další RPN instrukci v textové podobě (programová řádka).
3. RPN32_INIT_CB_TYPE_UNKNOWN - Oznámení o neúspěšném pokusu o převod instrukce (z předchozího bodu) do binární formy.

V případě žádosti o paměť (argument __type == RPN32_INIT_CB_TYPE_MEMORY) je při vstupu do callbacku platný pouze člen __iap->memoryv.size. Obsahuje doporučené množství paměťového prostoru. Při výstupu tato hodnota může být aktualizována (je-li množství alokované paměti jiné než doporučené) a člen __iap->memoryv.memp musí ukazovat na začátek bloku přidělené paměti.

V ostatních případech je používán pouze člen __iap->linep. Rozlišení jeho role (vstup nebo výstup) je dané kontextem.

Funkce rpn32_view()

Tato funkce „nabídne“ callbacku formou argumentu __linep řádku textu, který popisuje okamžitý stav interpreteru. Maximální délka řádky textu je 240 znaků. Je-li tento počet vlivem složení formátovacího řetězce překročen, neúplná řádka končí sekvencí ">>>".

Ve sloupci RPN32 souhrnné tabulky zasahuje buňka s názvem této funkce přes dva řádky sloupce Činnost. První obsahuje text Výpis obsahu paměťových registrů, ..., ve druhém je napsáno Výpis instrukcí RPN programu. A právě to jsou ty stavové informace. Instrukce RPN programu je vypsána (není-li tato část výpisu záměrně potlačena) aktuální, tedy ta na kterou právě „míří“ vnitřní ukazatel.

Že je činnost, jakou jsou informace pro výstup/výpis požadovány a následně poskytovány, řízena formátovacím řetězcem, naznačuje už úvodní odstavec Nové řízení výpisu. Zde je prostor pro detaily.

Znaky, ze kterých je formátovací řetězec složen, lze rozdělit do dvou skupin:

1. Zástupné. Jak už název napovídá, jde o znaky, které zastupují nějaké složky výpisu.
2. Řídicí. Tyto znaky ovlivňují konkrétní podobu (některých) číselných hodnot výpisu.

» Znaky zástupné

Pozn.: Mnemonický tvar instrukce je vždy poslední částí/složkou vypisované řádky. Pořadí ostatních znaků ve formátovacím řetězci určuje i pořadí ve výpisu.

» Znaky řídicí

Pozn.: Znaky signed, unsigned a radix mají trvalou platnost až do dalšího výskytu.

Funkce rpn32_list()

Tato funkce poskytuje výpis celého RPN programu. Téměř vše, co bylo obsaženo v popisu funkce rpn32_view() platí i pro ni. Rozdíl je pouze v jednom detailu. Funkce rpn32_view() proběhne „jednorázově“, tj. způsobí pouze jednu jedinou řádku výpisu. Funkce rpn32_list() volá svůj callback opakovaně, od první po poslední RPN instrukci (nebo také ani jednou, není-li žádná, viz interaktivní provádění). Návratová hodnota callbacku RPN32_RTNVAL_STOP celou sekvenci (předčasně) zastaví.

Funkce rpn32_mem()

Poslední ze skupiny funkcí druhu INFO je tato. Prostřednictvím opakovaně volaného callbacku zveřejňuje informace o

• počtu alokovaných paměťových registrů,
• výskytu návěští (label),
• velikosti zásobníku návratových adres.

Funkce rpn32_enter()

Funkce vloží hodnotu danou jejím argumentem __value do X-registru RPN stacku. Ještě předtím provede posun celého RPN stacku směrem vzhůru (v originále lifting of the stack's contents). Nelze však říci, že tato funkce je přímým ekvivalentem stejnojmenné instrukce ENTER obsažené v instrukční sadě. Tato funkce (na rozdíl od instrukce) nastaví příznak pro právě zmíněný „zdvih“ celého RPN stacku při jeho následném použití.

Funkce rpn32_tenter()

Tahle funkce dělá naprosto to samé, co předchozí rpn32_enter(). Rozdíl je pouze v tom, že argument nesoucí hodnotu vkládanou na RPN stack je typu (char const *) místo předchozího (rpn32value_t). Výhoda je zřejmá: pokud je vstupem do programu využívajícího knihovnu RPN32 text, není třeba ho převádět na binární hodnotu. Funkce převod zajistí sama. Příjemným návdavkem je možnost zadat vícesložkovou hodnotu Loop Control-number.

Funkce rpn32_rdn()

Činnost této funkce lze popsat třemi elementárními kroky:

1. Vyzvednutí hodnoty z X-registru RPN stacku,
2. Roll Down RPN stacku,
3. Návrat s vyzvednutou hodnotou.

Funkce rpn32_regx()

Je to skoro trapné, ale tahle funkce je ještě jednodušší, než ta předchozí. Ze tří uvedených elementárních kroků dělá pouze dva! Ten prostřední (Roll Down) je v tomto případě vynechán. Jinak řečeno - funkce pouze vrátí hodnotu X-registru RPN stacku. Vypadá to sice banálně, ale existence této funkce je velice důležitá. Bez ní by nebylo možné zjistit výsledek výpočtu bez zásahu do „vnitřností“ interpreteru.

Funkce rpn32_run()

Když už je konečně RPN program napsán, úspěšně přeložen/zkompilován do binární formy, která je uložena do paměti počítače, zbývá poslední krůček. K jeho uskutečnění slouží funkce, která je de facto základním kamenem celé této stavby: spuštění vytvořeného RPN programu. Funkce má (podobně jako některé předchozí: rpn32_init(), rpn32_view(), rpn32_list(), rpn32_mem()) argument - callback. Ten však není volán za všech okolností, jako u funkcí předchozích. Co je míněno těmi okolnostmi?

U předchozích případů lze prohlásit, že callback plní úlohu funkční nebo provozní, chcete-li. Bez callbacku by daná funkce neplnila svůj účel. Jinak je tomu v případě funkce rpn32_run(). Zde je callback volán

• vyskytne-li se v RPN programu instrukce instrukce PSE (což nemusí být),
• je-li požadován režim TRACE, kdy je callback volán bezprostředně před provedením aktuální instrukce (což rovněž nemusí být).

RPN program se rozeběhne od aktuální instrukce. Tou může být nejen ta úplně první v pořadí, ale třeba i ta, která

• následuje po instrukci STOP (ta ukončí provádění funkce rpn32_run(), následné opětovné volání této funkce způsobí pokračování v běhu RPN programu),
• následuje po instrukci, při které volaný callback nevrátil hodnotu RPN32_RTNVAL_DONE, ale RPN32_RTNVAL_STOP,
• byla nastavena funkcí rpn32_gto() (tou aktuální instrukcí je zde pochopitelně LBL).

Funkce rpn32_gto()

Funkce nastaví aktuální pozici pro spuštění v RPN programu podle argumentu __lblno ve významu číslo návěští (label). Provede vlastně totéž, co instrukce GTO. Navíc vyprázdní zásobník návratových adres.

Funkce rpn32_now()

Poslední funkce ze seznamu provede jednu instrukci a svoji činnost tím ukončí. Prováděná instrukce však není z programového toku, ale je v mnemonickém tvaru zadána přímo jako její argument __linep. Více v kapitole interaktivního provádění.