README.API

           streetmangler - реестр и конвертер названий улиц
          ==================================================

Библиотека состоит по большей части из 3 классов.

StreetMangler::Locale
=====================

  Определяет локаль - набор правил для определённого языка/региона.
  На данный момент в локали хранится список статусных частей и их
  возможных сокращений.

  Задание локали
  --------------

  Данные локали задаются в исходном файле в виде массива структур
  StatusPartData, определяющий различные виды написания статусной
  части:

    StatusPartData status_parts[] = {
        { "улица", nullptr, "ул.", { "улица", "ул" } },
        { "проспект", "просп.", "пр-т.", { "проспект", "просп", "пр-кт", "пр-т" } },
        { "просека", nullptr, nullptr, { "просека" } },
    }

  Поля структуры следующие:

  - полное написание - используется при указании флага EXPAND_STATUS
    в Name::Join, а также для сравнения названий в Database
  - каноническая форма - используется при указании флага
    CANONICALIZE_STATUS в Name::Join, а также в Database
    если nullptr, используется полная форма
  - сокращённое написание - используется при указании флага
    SHRINK_STATUS в Name::Join
    если nullptr, используется каноническая форма
  - список форм - используется для распознавания статусной части
    (предыдущие поля сюда не включаются, поэтому в большинстве случаев
    в этом списке должна присутствовать полная форма, а также все
    возможные сокращения без точки).

  Следует заметить, что совпадение форм разных статусных частей
  запрещено (т.е. "пр" сразу для проспекта и проезда), и проверяется
  assert'ом.

  После этого через создание глобального объекта Locale::Registrar
  данные локали автоматически связываются с именем:

    Locale::Registrar("ru_RU", status_parts),

  и становятся доступны для использования:

   Locale locale("ru_RU");

  Использование
  -------------

    // Получить локаль
    Locale locale("ru_RU"); // Кидает Locale::UnknownLocale если локаль
                            // с таким именем не найдена

    // Получить и использовать данные по статусной части
    const StatusPart* info = locale.FindStatus("пр-т");
    assert(info->GetFull() == "проспект");
    assert(info->GetAbbrev() == "пр-т.");


StreetMangler::Name
===================

  Хранит название улицы, разбитое на части и готовое к преобразованиям.

  В конструктор передаётся строка с названием и ссылка на локаль.

  Единственный метод - Join() принимает ряд флагов, позволяющих
  преобразовать имя в различными способами:

    STATUS_TO_LEFT      - перенести статусную часть влево
    STATUS_TO_RIGHT     - перенести статусную часть вправо
    (в отсутствие этих флагов статусная часть не меняет положения)

    EXPAND_STATUS       - заменить статусную часть полным написанием
                          из локали
    SHRINK_STATUS       - заменить статусную часть сокращённым
                          написанием из локали
    CANONICALIZE_STATUS - заменить статусную часть каноническим
                          написанием из локали
    (в отсутствие этих флагов статусная часть не меняет написания)

    REMOVE_ALL_STATUSES  - удалить все части, похожие на статусные
    NORMALIZE_WHITESPACE - заменить все последовательности пробельных
                           символов (' ', '\t') единичными пробелами,
                           убрать пробелы в начале и конце строки
    NORMALIZE_PUNCT      - удалить запятую в случае типа "Ленина,
                           улица". Этот флаг автоматически
                           подразумевается при STATUS_TO_LEFT,
                           STATUS_TO_RIGHT, REMOVE_ALL_STATUSES
    ADD_PUNCT            - добавить запятую когда статусная часть
                           переосится направо (т.е. "улица Ленина" ->
                           "Ленина, улица")

  Использование
  -------------

    // Нужна локаль
    Locale locale("ru_RU");

    Name name("улица Ленина", locale);

    // Получить имя в неизменённом виде
    assert(name.Join()) == "улица Ленина");

    // Сократить статус
    assert(name.Join(Name::SHRINK_STATUS)) == "ул. Ленина");

    // Перенести статус вправо
    assert(name.Join(Name::STATUS_TO_RIGHT)) == "Ленина улица");


StreetMangler::Database
=======================

  База данных правильных названий улиц. Загружается из файла
  и предоставляет методы для сопоставления названий:

  CheckExactMatch    - проверка на точное соответствие
  CheckCanonicalForm - проверка неточного написания, учитывающая
                       перестановку слов, регистр, пробелы и
                       сокращения статусных частей
  CheckSpelling      - проверка неточного написания с учётом
                       орфографических ошибок (пока не реализовано)
  CheckStrippedStatus - проверка на название с отсутствующей статусной
                        частью

  Все функции возвращают число соответствий, а все кроме первой
  также наполняют вектор предположительных правильных написаний.
  В случае CheckCanonicalForm и CheckSpelling оный может использоваться,
  например, для формирования списка замен.

  Для удобства, все функции работают как с обычными строками, так
  и со StreetMangler::Name. Использование второй формы может быть
  эффективнее при последовательных вызовах, поскольку не нужно будет
  многократно конструировать Name.

  Использование
  -------------

    // Нужна локаль
    Locale locale("ru_RU");

    Database database(locale);

    // Можно загружать несколько баз
    database.Load("data/ru.txt");

    // Можно добавлять названия вручную
    database.Add("улица Ленина");

    int res = database.CheckExactMatch("улица Ленина");
    assert(res == 1); // Правильное написание

    std::vector<std::string> suggestions;
    int res = database.CheckCanonicalForm("Ленина ул.");
    assert(res == 1); // Найдена одна замена
    assert(suggestions[0] == "улица Ленина");