Man page of tw_add_category(3), tw_delete_category(3) and tw_rename_category(3)

tw_add_category, tw_delete_category, tw_rename_category - category management

C/C++ #include <tw.h>

 tw_errno_t tw_add_category(tw_t *tw, const char *name);

 tw_errno_t tw_delete_category(tw_t *tw, const char *name);

 tw_errno_t tw_rename_category(tw_t *tw, const char *cur_name,
                               const char *new_name);

Categories can (optionally) be organized mono-hierarchical. Textweiser takes care of the hierarchical structure and all necessary modifications when adding, deleting or renaming categories. See MONO-HIERARCHICAL CATEGORIES below.

tw_add_category() adds a new, empty category to Textweiser's database. Any nonexistent top-level category will be added as well.

tw_delete_category() deletes an existing category and all its data from Textweiser's database. Any subcategory of the deleted category will be deleted as well.

tw_rename_category() renames an exisiting category within Textweiser's database. Any subcategory will be renamed accordingly as well.

All of the three functions have their first parameter in common:

tw (tw_t *)

Pointer to an initialized Textweiser object.

tw_add_category() and tw_delete_category() expect as a second parameter:

name (const char *)

Name of the category to add or delete (UTF-8 encoded).

tw_rename_category() expects as a second and third parameter:

cur_name (const char *)

Current name of the category to rename (UTF-8 encoded).

new_name (const char *)

New name of the category currently named cur_name (UTF-8 encoded).

tw_add_category(), tw_delete_category() and tw_rename_category() return an error indicator (tw_errno_t). A return value of TW_OK indicates success, any other value discriminates the occurred error.

The function tw_strerror(3) can be used to obtain a natural language error message.

Textweiser handles mono-hierarchical categories ("taxonomies") in an intuitive manner that allows to use them with ease. Categories and their subcategories are separated using the sequence "::".

 Sports::Football::Managers
 ^^^^^^  ^^^^^^^^  ^^^^^^^^
 top-    sub-      sub-sub- category

Any maintenance steps required are automatically done by Textweiser.

For an in-depth description on how to use mono-hierarchical categories with Textweiser, see the examples given in NOTES below and have a look at the Textweiser User Manual.

The use of mono-hierarchical category structures is optional.

o

All category names have to be encoded in UTF-8 and have to be of 255 bytes in length at most.

o

The sequence "::" is used to separate mono-hierarchical categories.

o

tw_add_category() adds a new category and any of its nonexistent top-level categories to the Textweiser database.

EXAMPLE:

Given a category hierarchy before, adding the category IT::Projects will result in after:

 +------------------------+-----------------------+
 | before                 | after                 |
 +------------------------+-----------------------+
 | Sales                  | IT                    |
 | Sales::Invoices        | IT::Projects          |
 | Sales::Correspondence  | Sales                 |
 |                        | Sales::Invoices       |
 |                        | Sales::Correspondence |
 +------------------------+-----------------------+

The top-level category, IT, has been added automatically.

To make use of the new category, a set of representative documents of the category has to be learned using either tw-learn(1), tw_learn(3) or tw_learn_file(3).

o

tw_delete_category() permanently deletes all data of the category itself and any of its subcategories.

EXAMPLE:

Given a category hierarchy before, deleting the category IT will result in after:

 +------------------------+-----------------------+
 | before                 | after                 |
 +------------------------+-----------------------+
 | IT                     | Sales                 |
 | IT::Projects           | Sales::Invoices       |
 | IT::Support            | Sales::Correspondence |
 | Sales                  |                       |
 | Sales::Invoices        |                       |
 | Sales::Correspondence  |                       |
 +------------------------+-----------------------+

The subcategories of IT (Projects and Support) have been deleted automatically.

o

IMPORTANT NOTE: After deleting a category, the database should be optimized using tw_optimize_db(3).

o

tw_rename_category() does not move categories between hierarchical category subtrees. As a result, any renaming operation has to fulfill the constraint of keeping the same top-level category. If the constraint is violated by a renaming operation, TW_ECONSTR will be returned as an error.

EXAMPLE:

Given a category hierarchy before, renaming the category IT to XXX will result in after:

 +------------------------+-----------------------+
 | before                 | after                 |
 +------------------------+-----------------------+
 | IT                     | Sales                 |
 | IT::Projects           | Sales::Invoices       |
 | IT::Support            | Sales::Correspondence |
 | Sales                  | XXX                   |
 | Sales::Invoices        | XXX::Projects         |
 | Sales::Correspondence  | XXX::Support          |
 +------------------------+-----------------------+

The subcategories of IT (Projects and Support) have been renamed automatically.

Renaming IT::Support to Sales::Support is not allowed, because it violates the constraint that Support still keeps the same top-level category.

tw-admin(1), tw-learn(1)

tw_create_db(3), tw_init(3), tw_strerror(3), tw_learn(3), tw_learn_file(3)

Textweiser User Manual

http://www.lingua-systems.com/text-classifier/textweiser-library/

Copyright (c) 2010-2011 Lingua-Systems Software GmbH