Работа с ФИО

Класс PersonNameFormatter - содержит 3 функции для работы с ФИО: FullName, NameInit и InitName.

Большинство параметров сходны и описываются для всех функций совместно.

Функции принципиально отличаются друг от друга только выходными параметрами.

Выходные параметры

• FullName - выводит полный вариант в формате "Фамилия Имя Отчество";
• NameInit - выводит фамилию и инициалы в формате "Фамилия И.О.";
• InitName - выводит инициалы и фамилию в формате "И.О. Фамилия".

Входные параметры

Все 3 функции имеют общие входные параметры:

• surname - фамилия,
• name - имя,
• patronymic - отчество.

Алгоритм

1. Лишние пробелы в начале и конце полученных на входе строк удаляются.
2. Если какой-либо из параметров равен null или пустой строке, он игнорируется при сборке.
3. Выполняется сборка по правилам и в последовательности, ожидаемых в выходных параметрах функции.
4. Если все параметры пусты, возвращается значение по умолчанию -.

Использование в выражениях

// A_1
[FullName([Main.surname], [Main.name], [Main.patronimyc])]

// JL_2
[NameInit([Main.surname], [Main.name], [Main.patronymic])]

// M_1
[InitName([FioFilter.surname], [FioFilter.name], [FioFilter.patronymic])]

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

// NG_3
Cell103.Text = InitName(
    Convert.ToString(Report.GetColumnValue("FioFilter_1.surname_1")),
    Convert.ToString(Report.GetColumnValue("FioFilter_1.name_1")),
    Convert.ToString(Report.GetColumnValue("FioFilter_1.patronymic_1"))
);

Код класса

using System.Text;

namespace Chemsoft.Triteia.ReportFunctions.Signatures;
    
/// <summary>
///     Вспомогательный (утилитарный) класс для представления ФИО в разных форматах
/// </summary>
public static class PersonNameFormatter
{
    /// <summary>
    ///     Форматирует ФИО в вид: "Фамилия И.О."
    /// </summary>
    /// <param name="surname">Фамилия</param>
    /// <param name="name">Имя</param>
    /// <param name="patronymic">Отчество</param>
    /// <returns>Строка с фамилией и инициалами.</returns>
    /// <remarks>
    ///     1. Лишние пробелы в начале и конце строк удаляются.<br/>
    ///     2. Если какой-либо из параметров равен <see langword="null"/> или пустой строке, 
    ///     он игнорируется при сборке.<br/>
    ///     3. Если все параметры пусты, вернет значение по умолчанию для пустой строки методом <see cref="Output"/>.
    /// </remarks>
    public static string NameInit(string? surname, string? name, string? patronymic)
    {
        var cleanSurname = surname?.Trim();
        var cleanName = name?.Trim();
        var cleanPatronymic = patronymic?.Trim();
        
        var initials = GetInitials(cleanName, cleanPatronymic);

        return Output(string.Join(" ", cleanSurname, initials));
    }

    /// <summary>
    ///     Форматирует ФИО в вид: "И.О. Фамилия"
    /// </summary>
    /// <param name="surname">Фамилия</param>
    /// <param name="name">Имя</param>
    /// <param name="patronymic">Отчество</param>
    /// <returns>Строка с инициалами и фамилией.</returns>
    /// <remarks>
    ///     1. Лишние пробелы в начале и конце строк удаляются.<br/>
    ///     2. Если какой-либо из параметров равен <see langword="null"/> или пустой строке, 
    ///     он игнорируется при сборке.<br/>
    ///     3. Если все параметры пусты, вернет значение по умолчанию для пустой строки методом <see cref="Output"/>.
    /// </remarks>
    public static string InitName(string? surname, string? name, string? patronymic)
    {   
        var cleanSurname = surname?.Trim();
        var cleanName = name?.Trim();
        var cleanPatronymic = patronymic?.Trim();
        
        var initials = GetInitials(cleanName, cleanPatronymic);

        return Output(string.Join(" ", initials, cleanSurname));
    }

    /// <summary>
    ///     Форматирует ФИО в вид: "Фамилия Имя Отчество"
    /// </summary>
    /// <param name="surname">Фамилия</param>
    /// <param name="name">Имя</param>
    /// <param name="patronymic">Отчество</param>
    /// <returns>Полная строка ФИО, разделенная пробелами.</returns>
    /// <remarks>
    ///     1. Лишние пробелы в начале и конце строк удаляются.<br/>
    ///     2. Если какой-либо из параметров равен <see langword="null"/> или пустой строке, 
    ///     он игнорируется при сборке.<br/>
    ///     3. Если все параметры пусты, вернет значение по умолчанию для пустой строки методом <see cref="Output"/>.
    /// </remarks>
    public static string FullName(string? surname, string? name, string? patronymic)
    {
        var sb = new StringBuilder();
        
        var cleanSurname = surname?.Trim();
        var cleanName = name?.Trim();
        var cleanPatronymic = patronymic?.Trim();
        
        if (!string.IsNullOrEmpty(cleanSurname))
        {
            sb.Append(cleanSurname);
        }

        if (!string.IsNullOrEmpty(cleanName))
        {
            if (sb.Length > 0) sb.Append(" ");
            sb.Append(cleanName);
        }

        if (!string.IsNullOrEmpty(cleanPatronymic))
        {
            if (sb.Length > 0) sb.Append(" ");
            sb.Append(cleanPatronymic);
        }

        return Output(sb.ToString());
    }
    
    /// <summary>
    ///     Формирует строку инициалов в формате "И.О." на основе очищенных имени и отчества.
    /// </summary>
    /// <param name="cleanName">Нормализованное имя (не должно быть <see langword="null"/>).</param>
    /// <param name="cleanPatronymic">Нормализованное отчество (не должно быть <see langword="null"/>).</param>
    /// <returns>
    ///         - или два инициала,<br/>
    ///         - или один инициал (если один из параметров пустой),<br/>
    ///         - или значение null (если оба параметра пустые).
    /// </returns>
    /// <remarks>
    ///     Метод берет первый символ от каждой непустой строки.
    ///     Если одна из строк пустая, соответствующий инициал пропускается
    ///     без добавления лишних пробелов или разделителей.
    /// </remarks>
    private static string? GetInitials(string? cleanName, string? cleanPatronymic)
    {   
        if (string.IsNullOrEmpty(cleanName) && string.IsNullOrEmpty(cleanPatronymic))
        {
            return null;
        }
        
        var sb = new StringBuilder();
        
        if (!string.IsNullOrEmpty(cleanName))
        {
            sb.Append(cleanName.Substring(0, 1));
            sb.Append(".");
        }

        if (!string.IsNullOrEmpty(cleanPatronymic))
        {
            sb.Append(cleanPatronymic.Substring(0, 1));
            sb.Append(".");
        }

        return sb.ToString();
    }
    
    /// <summary>
    ///     Выполняет финальную проверку сформированного ФИО
    ///     и заменяет пустые или некорректные значения на значение по умолчанию (дефис).
    /// </summary>
    /// <param name="field">Результирующая строка ФИО после форматирования.</param>
    /// <returns>
    ///     - или исходную строку <paramref name="field"/>,<br/>
    ///     - или дефис <c>"-"</c> (если строка пуста или равна <c>"0"</c>).
    /// </returns>
    /// <remarks>
    ///     Метод гарантирует, что вызывающие методы не вернут пустую строку. 
    /// </remarks>
    private static string Output(string field)
    {
        const string defaultEmptyValue = "-";
        var trimmedField = field.Trim(); 
        
        return string.IsNullOrEmpty(trimmedField) ? defaultEmptyValue : trimmedField;
    }
}