Просмотр кода страницы Работа с ФИО

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

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

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

==Выходные параметры==
*<code>FullName</code> - выводит полный вариант в формате "Фамилия Имя Отчество";
*<code>NameInit</code> - выводит фамилию и инициалы в формате "Фамилия И.О.";
*<code>InitName</code> - выводит инициалы и фамилию в формате "И.О. Фамилия".

==Входные параметры==
Все 3 функции имеют общие входные параметры:
*<code>surname</code> - фамилия,
*<code>name</code> - имя, 
*<code>patronymic</code> - отчество.

==Алгоритм==

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

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

<syntaxhighlight lang="C#">
// 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])]
</syntaxhighlight>

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

<syntaxhighlight lang="C#">

// 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"))
);
</syntaxhighlight>

==Подключение==
==Код класса==

<syntaxhighlight lang="C#">
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;
    }
}
</syntaxhighlight>