finflect.h

Go to the documentation of this file.

/*
 * finflect - Algorithms and tools for inflecting Finnish nouns
 * Copyright (C) 2004, 2005  The FinFlect Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *
 * For the complete legal text of the GNU Lesser General Public License,
 * see the file LICENSE. For a complete list of authors and copyright
 * holders, see the file AUTHORS.
 */

/**
 * @file finflect.h The primary header of the FinFlect public API. Defines the inflection functions.
 * @todo Remove impossible case/count combinations (any other than comitative singular?)
 * @todo Check case names
 * @todo Move the mainpage section somewhere else
 */
 
/**
 * @mainpage
 * 
 * @section Introduction
 * This is the source-level documentation and cross-referenced source broser of FinFlect,
 * a free software library of tools and algorithms for inflecting Finnish nouns, pronouns,
 * adjectives and numerals.
 *
 * FinFlect is being developed and maintained by a small group of volunteering programmers
 * that are in no way professionals in the Finnish language (despite of being native speakers)
 * nor are they professional programmers (yet?). Therefore the quality of the documentation and code might
 * vary significantly.
 *
 * @section Background
 * Finnish is a Fenno-Ugric language that mostly uses suffixes where many languages (e.g. English)
 * use prepositions. This particular trait makes it fairly difficult to translate electronically -
 * and also very difficult to learn.
 *
 * Finnish nouns are inflected in fifteen cases:
 *
 * @subsection Nominative
 * Nominative is the basic form of nouns. It often answers the question "what?" or "which?" and is
 * usually used in the subject part of a sentence. As you might imagine, nominative singular forms
 * do not differ in any way from the forms you can find in English-Finnish dictionaries; the plurals
 * of most words only add -t to the singular form.
 *
 * @b Example: koira (singular), koirat (plural)
 *
 * Nominative forms of Finnish nouns can be obtained using the functions ff_nominative_singular
 * (which is practically useless because nominative is the most basic form) and ff_nominative_plural.
 *
 * @subsection Accusative
 * Accusative is the object part of nouns. It often answers the question "what?" or "which?" when
 * the noun at hands is in the object part of a sentence. The accusative usually looks like genitive
 * or partitive.
 *
 * @b Example: koira -> koiran (genitive-like singular) or koiraa (partitive-like singular), koirien (genitive-like plural) or koiria (partitive-like plural)
 *
 * Because the accusative forms depend on the context, accusative can not be implemented as a function.  Use
 * ff_genitive_singular, ff_genitive_plural, ff_partitive_singular and ff_partitive_plural where applicable.
 *
 * @subsection Genitive
 * Genitive expresses ownership. It answers the question "whose?". Genitives can usually be
 * recognized from the suffix -n or -en.
 *
 * @b Examples: koira -> koiran, koirien
 *
 * Genitive forms of Finnish nouns can be obtained using the functions ff_genitive_singular and
 * ff_genitive_plural.
 *
 * @subsection Essive
 * Essives can usually be recognized from the suffix -na or -nä.
 *
 * @b Example: koira -> koirana, koirina 
 *
 * @subsection Partitive
 * Suffix -a, -ä, -ta or -tä.
 *
 * @b Example: koira -> koiraa, koiria
 *
 * @subsection Translative
 * Translative expresses change of state. It carries the suffix -ksi.
 *
 * @b Example: koira -> koiraksi, koiriksi
 *
 * @subsection Inessive
 * Suffix -ssa or -ssä.
 *
 * @b Example: koira -> koirassa, koirissa
 * 
 * @subsection Elative
 * Suffix -sta or -stä.
 *
 * @b Example: koira -> koirasta, koirista
 *
 * @subsection Illative
 * Suffix -aan and the like.
 *
 * @b Example: koira -> koiraan, koiriin
 *
 * @subsection Adessive
 * Suffix -lla or -llä.
 * 
 * @b Example: koira -> koiralla, koirilla
 *
 * @subsection Ablative
 * Suffix -lta or -ltä.
 *
 * @b Example: koira -> koiralta, koirilta
 *
 * @subsection Allative
 * Suffix -lle.
 *
 * @b Example: koira -> koiralle, koirille
 *
 * @subsection Abessive
 * Abessive expresses lack of something. It is not very commonly used and is even less common in
 * singular than in plural. It can be recognized from the part -tta- which is often followed by
 * a possessive suffix.
 *
 * @b Example: koira -> koiratta, koiritta
 *
 * @subsection Instructive
 * Suffix -n and -in.
 * 
 * @b Example: jalka -> jalan, jaloin
 *
 * @subsection Comitative
 * Suffix -ne- and a possessive suffix, only plural
 *
 * @b Example: koira -> koirineen (third person)
 *
 * @todo Do some bla-bla humanism for the cases
 * @todo Find out how on Earth do we get those function names properly linked to the respective functions
 */
 
#ifndef __FINFLECT_H
#define __FINFLECT_H

#ifdef __cplusplus
extern "C"
{
#endif
        
#include "ffcase.h"
#include "fftypes.h"

/**
 * Returns the desired form of the given word.
 * @param word The word to inflect
 * @param thecase The case
 * @param count The count; enter 1 to get the singular or anything else to get the plural
 * @return The inflected word
 */
ffchar* ff_inflect(const ffchar* word, ffcase thecase, ffint32 count);


/**
 * Returns the nominative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_nominative_singular(const ffchar* word);

/**
 * Returns the nominative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_nominative_plural(const ffchar* word);

/**
 * Returns the genitive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_genitive_singular(const ffchar* word);

/**
 * Returns the genitive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_genitive_plural(const ffchar* word);

/**
 * Returns the essive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_essive_singular(const ffchar* word);

/**
 * Returns the essive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_essive_plural(const ffchar* word);

/**
 * Returns the partitive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_partitive_singular(const ffchar* word);

/**
 * Returns the partitive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_partitive_plural(const ffchar* word);

/**
 * Returns the translative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_translative_singular(const ffchar* word);

/**
 * Returns the translative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_translative_plural(const ffchar* word);

/**
 * Returns the inessive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_inessive_singular(const ffchar* word);

/**
 * Returns the inessive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_inessive_plural(const ffchar* word);

/**
 * Returns the elative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_elative_singular(const ffchar* word);

/**
 * Returns the elative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_elative_plural(const ffchar* word);

/**
 * Returns the illative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_illative_singular(const ffchar* word);

/**
 * Returns the illative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_illative_plural(const ffchar* word);

/**
 * Returns the adessive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_adessive_singular(const ffchar* word);

/**
 * Returns the adessive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_adessive_plural(const ffchar* word);

/**
 * Returns the ablative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_ablative_singular(const ffchar* word);

/**
 * Returns the ablative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_ablative_plural(const ffchar* word);

/**
 * Returns the allative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_allative_singular(const ffchar* word);

/**
 * Returns the allative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_allative_plural(const ffchar* word);

/**
 * Returns the abessive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_abessive_singular(const ffchar* word);

/**
 * Returns the abessive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_abessive_plural(const ffchar* word);

/**
 * Returns the instructive singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_instructive_singular(const ffchar* word);

/**
 * Returns the instructive plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_instructive_plural(const ffchar* word);

/**
 * Returns the comitative singular of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_comitative_singular(const ffchar* word);

/**
 * Returns the comitative plural of the given word.
 * The returned string is a malloc(3)'d C-style string that can be freed with free(3).
 * @param word The word to inflect
 * @return The inflected word
 */
ffchar* ff_comitative_plural(const ffchar* word);

#ifdef __cplusplus
}
#endif

#endif

---