Main Page | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

finflect.h

Go to the documentation of this file.
00001 /*
00002  * finflect - Algorithms and tools for inflecting Finnish nouns
00003  * Copyright (C) 2004, 2005  The FinFlect Team
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Lesser General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2.1 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Lesser General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Lesser General Public
00016  * License along with this library; if not, write to the Free Software
00017  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00018  *
00019  *
00020  * For the complete legal text of the GNU Lesser General Public License,
00021  * see the file LICENSE. For a complete list of authors and copyright
00022  * holders, see the file AUTHORS.
00023  */
00024 
00025 /**
00026  * @file finflect.h The primary header of the FinFlect public API. Defines the inflection functions.
00027  * @todo Remove impossible case/count combinations (any other than comitative singular?)
00028  * @todo Check case names
00029  * @todo Move the mainpage section somewhere else
00030  */
00031  
00032 /**
00033  * @mainpage
00034  * 
00035  * @section Introduction
00036  * This is the source-level documentation and cross-referenced source broser of FinFlect,
00037  * a free software library of tools and algorithms for inflecting Finnish nouns, pronouns,
00038  * adjectives and numerals.
00039  *
00040  * FinFlect is being developed and maintained by a small group of volunteering programmers
00041  * that are in no way professionals in the Finnish language (despite of being native speakers)
00042  * nor are they professional programmers (yet?). Therefore the quality of the documentation and code might
00043  * vary significantly.
00044  *
00045  * @section Background
00046  * Finnish is a Fenno-Ugric language that mostly uses suffixes where many languages (e.g. English)
00047  * use prepositions. This particular trait makes it fairly difficult to translate electronically -
00048  * and also very difficult to learn.
00049  *
00050  * Finnish nouns are inflected in fifteen cases:
00051  *
00052  * @subsection Nominative
00053  * Nominative is the basic form of nouns. It often answers the question "what?" or "which?" and is
00054  * usually used in the subject part of a sentence. As you might imagine, nominative singular forms
00055  * do not differ in any way from the forms you can find in English-Finnish dictionaries; the plurals
00056  * of most words only add -t to the singular form.
00057  *
00058  * @b Example: koira (singular), koirat (plural)
00059  *
00060  * Nominative forms of Finnish nouns can be obtained using the functions ff_nominative_singular
00061  * (which is practically useless because nominative is the most basic form) and ff_nominative_plural.
00062  *
00063  * @subsection Accusative
00064  * Accusative is the object part of nouns. It often answers the question "what?" or "which?" when
00065  * the noun at hands is in the object part of a sentence. The accusative usually looks like genitive
00066  * or partitive.
00067  *
00068  * @b Example: koira -> koiran (genitive-like singular) or koiraa (partitive-like singular), koirien (genitive-like plural) or koiria (partitive-like plural)
00069  *
00070  * Because the accusative forms depend on the context, accusative can not be implemented as a function.  Use
00071  * ff_genitive_singular, ff_genitive_plural, ff_partitive_singular and ff_partitive_plural where applicable.
00072  *
00073  * @subsection Genitive
00074  * Genitive expresses ownership. It answers the question "whose?". Genitives can usually be
00075  * recognized from the suffix -n or -en.
00076  *
00077  * @b Examples: koira -> koiran, koirien
00078  *
00079  * Genitive forms of Finnish nouns can be obtained using the functions ff_genitive_singular and
00080  * ff_genitive_plural.
00081  *
00082  * @subsection Essive
00083  * Essives can usually be recognized from the suffix -na or -nä.
00084  *
00085  * @b Example: koira -> koirana, koirina 
00086  *
00087  * @subsection Partitive
00088  * Suffix -a, -ä, -ta or -tä.
00089  *
00090  * @b Example: koira -> koiraa, koiria
00091  *
00092  * @subsection Translative
00093  * Translative expresses change of state. It carries the suffix -ksi.
00094  *
00095  * @b Example: koira -> koiraksi, koiriksi
00096  *
00097  * @subsection Inessive
00098  * Suffix -ssa or -ssä.
00099  *
00100  * @b Example: koira -> koirassa, koirissa
00101  * 
00102  * @subsection Elative
00103  * Suffix -sta or -stä.
00104  *
00105  * @b Example: koira -> koirasta, koirista
00106  *
00107  * @subsection Illative
00108  * Suffix -aan and the like.
00109  *
00110  * @b Example: koira -> koiraan, koiriin
00111  *
00112  * @subsection Adessive
00113  * Suffix -lla or -llä.
00114  * 
00115  * @b Example: koira -> koiralla, koirilla
00116  *
00117  * @subsection Ablative
00118  * Suffix -lta or -ltä.
00119  *
00120  * @b Example: koira -> koiralta, koirilta
00121  *
00122  * @subsection Allative
00123  * Suffix -lle.
00124  *
00125  * @b Example: koira -> koiralle, koirille
00126  *
00127  * @subsection Abessive
00128  * Abessive expresses lack of something. It is not very commonly used and is even less common in
00129  * singular than in plural. It can be recognized from the part -tta- which is often followed by
00130  * a possessive suffix.
00131  *
00132  * @b Example: koira -> koiratta, koiritta
00133  *
00134  * @subsection Instructive
00135  * Suffix -n and -in.
00136  * 
00137  * @b Example: jalka -> jalan, jaloin
00138  *
00139  * @subsection Comitative
00140  * Suffix -ne- and a possessive suffix, only plural
00141  *
00142  * @b Example: koira -> koirineen (third person)
00143  *
00144  * @todo Do some bla-bla humanism for the cases
00145  * @todo Find out how on Earth do we get those function names properly linked to the respective functions
00146  */
00147  
00148 #ifndef __FINFLECT_H
00149 #define __FINFLECT_H
00150 
00151 #ifdef __cplusplus
00152 extern "C"
00153 {
00154 #endif
00155         
00156 #include "ffcase.h"
00157 #include "fftypes.h"
00158 
00159 /**
00160  * Returns the desired form of the given word.
00161  * @param word The word to inflect
00162  * @param thecase The case
00163  * @param count The count; enter 1 to get the singular or anything else to get the plural
00164  * @return The inflected word
00165  */
00166 ffchar* ff_inflect(const ffchar* word, ffcase thecase, ffint32 count);
00167 
00168 
00169 /**
00170  * Returns the nominative singular of the given word.
00171  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00172  * @param word The word to inflect
00173  * @return The inflected word
00174  */
00175 ffchar* ff_nominative_singular(const ffchar* word);
00176 
00177 /**
00178  * Returns the nominative plural of the given word.
00179  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00180  * @param word The word to inflect
00181  * @return The inflected word
00182  */
00183 ffchar* ff_nominative_plural(const ffchar* word);
00184 
00185 /**
00186  * Returns the genitive singular of the given word.
00187  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00188  * @param word The word to inflect
00189  * @return The inflected word
00190  */
00191 ffchar* ff_genitive_singular(const ffchar* word);
00192 
00193 /**
00194  * Returns the genitive plural of the given word.
00195  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00196  * @param word The word to inflect
00197  * @return The inflected word
00198  */
00199 ffchar* ff_genitive_plural(const ffchar* word);
00200 
00201 /**
00202  * Returns the essive singular of the given word.
00203  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00204  * @param word The word to inflect
00205  * @return The inflected word
00206  */
00207 ffchar* ff_essive_singular(const ffchar* word);
00208 
00209 /**
00210  * Returns the essive plural of the given word.
00211  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00212  * @param word The word to inflect
00213  * @return The inflected word
00214  */
00215 ffchar* ff_essive_plural(const ffchar* word);
00216 
00217 /**
00218  * Returns the partitive singular of the given word.
00219  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00220  * @param word The word to inflect
00221  * @return The inflected word
00222  */
00223 ffchar* ff_partitive_singular(const ffchar* word);
00224 
00225 /**
00226  * Returns the partitive plural of the given word.
00227  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00228  * @param word The word to inflect
00229  * @return The inflected word
00230  */
00231 ffchar* ff_partitive_plural(const ffchar* word);
00232 
00233 /**
00234  * Returns the translative singular of the given word.
00235  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00236  * @param word The word to inflect
00237  * @return The inflected word
00238  */
00239 ffchar* ff_translative_singular(const ffchar* word);
00240 
00241 /**
00242  * Returns the translative plural of the given word.
00243  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00244  * @param word The word to inflect
00245  * @return The inflected word
00246  */
00247 ffchar* ff_translative_plural(const ffchar* word);
00248 
00249 /**
00250  * Returns the inessive singular of the given word.
00251  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00252  * @param word The word to inflect
00253  * @return The inflected word
00254  */
00255 ffchar* ff_inessive_singular(const ffchar* word);
00256 
00257 /**
00258  * Returns the inessive plural of the given word.
00259  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00260  * @param word The word to inflect
00261  * @return The inflected word
00262  */
00263 ffchar* ff_inessive_plural(const ffchar* word);
00264 
00265 /**
00266  * Returns the elative singular of the given word.
00267  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00268  * @param word The word to inflect
00269  * @return The inflected word
00270  */
00271 ffchar* ff_elative_singular(const ffchar* word);
00272 
00273 /**
00274  * Returns the elative plural of the given word.
00275  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00276  * @param word The word to inflect
00277  * @return The inflected word
00278  */
00279 ffchar* ff_elative_plural(const ffchar* word);
00280 
00281 /**
00282  * Returns the illative singular of the given word.
00283  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00284  * @param word The word to inflect
00285  * @return The inflected word
00286  */
00287 ffchar* ff_illative_singular(const ffchar* word);
00288 
00289 /**
00290  * Returns the illative plural of the given word.
00291  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00292  * @param word The word to inflect
00293  * @return The inflected word
00294  */
00295 ffchar* ff_illative_plural(const ffchar* word);
00296 
00297 /**
00298  * Returns the adessive singular of the given word.
00299  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00300  * @param word The word to inflect
00301  * @return The inflected word
00302  */
00303 ffchar* ff_adessive_singular(const ffchar* word);
00304 
00305 /**
00306  * Returns the adessive plural of the given word.
00307  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00308  * @param word The word to inflect
00309  * @return The inflected word
00310  */
00311 ffchar* ff_adessive_plural(const ffchar* word);
00312 
00313 /**
00314  * Returns the ablative singular of the given word.
00315  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00316  * @param word The word to inflect
00317  * @return The inflected word
00318  */
00319 ffchar* ff_ablative_singular(const ffchar* word);
00320 
00321 /**
00322  * Returns the ablative plural of the given word.
00323  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00324  * @param word The word to inflect
00325  * @return The inflected word
00326  */
00327 ffchar* ff_ablative_plural(const ffchar* word);
00328 
00329 /**
00330  * Returns the allative singular of the given word.
00331  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00332  * @param word The word to inflect
00333  * @return The inflected word
00334  */
00335 ffchar* ff_allative_singular(const ffchar* word);
00336 
00337 /**
00338  * Returns the allative plural of the given word.
00339  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00340  * @param word The word to inflect
00341  * @return The inflected word
00342  */
00343 ffchar* ff_allative_plural(const ffchar* word);
00344 
00345 /**
00346  * Returns the abessive singular of the given word.
00347  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00348  * @param word The word to inflect
00349  * @return The inflected word
00350  */
00351 ffchar* ff_abessive_singular(const ffchar* word);
00352 
00353 /**
00354  * Returns the abessive plural of the given word.
00355  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00356  * @param word The word to inflect
00357  * @return The inflected word
00358  */
00359 ffchar* ff_abessive_plural(const ffchar* word);
00360 
00361 /**
00362  * Returns the instructive singular of the given word.
00363  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00364  * @param word The word to inflect
00365  * @return The inflected word
00366  */
00367 ffchar* ff_instructive_singular(const ffchar* word);
00368 
00369 /**
00370  * Returns the instructive plural of the given word.
00371  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00372  * @param word The word to inflect
00373  * @return The inflected word
00374  */
00375 ffchar* ff_instructive_plural(const ffchar* word);
00376 
00377 /**
00378  * Returns the comitative singular of the given word.
00379  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00380  * @param word The word to inflect
00381  * @return The inflected word
00382  */
00383 ffchar* ff_comitative_singular(const ffchar* word);
00384 
00385 /**
00386  * Returns the comitative plural of the given word.
00387  * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
00388  * @param word The word to inflect
00389  * @return The inflected word
00390  */
00391 ffchar* ff_comitative_plural(const ffchar* word);
00392 
00393 #ifdef __cplusplus
00394 }
00395 #endif
00396 
00397 #endif

Generated on Sun May 15 21:50:47 2005 for FinFlect by  doxygen 1.4.1