Marshalls
Base64 для байтов, текста UTF-8 и бинарного Variant: три разных контракта.
RawToBase64/Base64ToRaw преобразуют байты; Utf8ToBase64/Base64ToUtf8 — текст через UTF-8; VariantToBase64/Base64ToVariant используют бинарный формат Variant внутри Base64. Эти пары нельзя произвольно смешивать: обычный UTF-8 текст в Base64 не становится сериализованным Variant. Base64 не шифрует и не сжимает данные. Сервис общий; Singleton не освобождайте вручную.
Base64ToUtf8 читает декодированные байты как строку до NUL: например QQBC даёт A вместо трёх байтов A, 0, B. Для точных байтов используйте Base64ToRaw; в C# при необходимости Encoding.UTF8.GetString полученного byte[]. Нативные строки движка не поддерживают встроенный NUL; не рассчитывайте на его сохранение через Utf8ToBase64.
Объекты при fullObjects=false сериализуются как идентификаторы, а не независимые копии; результат может быть EncodedObjectAsId. Это не переносимая ссылка на объект другого процесса. fullObjects/allowObjects включают другой режим с восстановлением нативных объектов: для внешних данных оставляйте отключёнными. Не сериализуется произвольный CLR-граф объектов.
31 Windows headless-проверка общего набора покрыла Base64 и контейнеры; для Marshalls проверены байты, Unicode, Int64, nil, векторы/Color, вложенные контейнеры и object-ID режим. Ошибочный ввод, восстановление полных объектов и перенос формата между версиями/сборками не приняты. Nil при декодировании бывает и корректным значением, и fallback при диагностике: проверяйте ожидаемый тип/схему.
Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.
Свойства1
SingletonСвойство
public static MarshallsInstance Singleton { get; }Заимствованный общий сервис движка для статических методов Marshalls. Не вызывайте Free/Dispose у экземпляра; для обычного использования достаточно статических вызовов.
Методы7
Base64ToRawbyte[]
public static byte[] Base64ToRaw(string base64Str);Декодирует Base64 в новый byte[], сохраняя нулевые и произвольные байты. Не интерпретирует данные как текст или Variant. Пустой ввод даёт пустой массив; ошибка тоже может дать пустой fallback с диагностикой.
| Имя | Тип | По умолчанию |
|---|---|---|
base64Str | string | — |
base64StrКорректная Base64-строка соответствующей пары методов; не произвольный текст, путь или JSON.
byte[]Новый byte[]; пустой для пустого ввода либо диагностируемой ошибки.
Base64ToUtf8string
public static string Base64ToUtf8(string base64Str);Декодирует Base64 и создаёт строку UTF-8 до первого нулевого байта. Это не точное восстановление произвольного byte[]. Для сохранения NUL используйте Base64ToRaw и явное C#-декодирование. Некорректный UTF-8/неверный Base64 не принят этим обзором.
| Имя | Тип | По умолчанию |
|---|---|---|
base64Str | string | — |
base64StrКорректная Base64-строка соответствующей пары методов; не произвольный текст, путь или JSON.
stringСтрока соответствующего преобразования; пустой fallback ошибки может совпадать с допустимым пустым значением.
Base64ToVariantVariant
public static Variant Base64ToVariant(string base64Str, bool allowObjects = false);Декодирует данные, созданные VariantToBase64, в Variant. allowObjects=false не разрешает восстановление полных объектов; ID-обёртки всё же возможны. Возвращённый Variant освобождайте после использования. Nil не является однозначным признаком ошибки: он бывает корректным значением.
| Имя | Тип | По умолчанию |
|---|---|---|
base64Str | string | — |
allowObjects | bool | false |
base64StrКорректная Base64-строка соответствующей пары методов; не произвольный текст, путь или JSON.
allowObjectsОставляйте false для внешних данных; true разрешает нативное восстановление полных объектов. Режим не проверялся этим запуском.
VariantПринадлежащий вызывающему Variant; nil допустим и не различает ошибку сам по себе.
RawToBase642 перегрузки
public static string RawToBase64(byte[] array);Кодирует байты стандартным Base64 без преобразования UTF-8. Массив и ReadOnlySpan дают одинаковый результат. Для пустого массива обработайте пустой результат явно до вызова: текущая обёртка диагностирует пустую закодированную строку.
| Имя | Тип | По умолчанию |
|---|---|---|
array | byte[] | — |
arrayНепустые байты для точного Base64-кодирования. Нулевой байт внутри массива сохраняется; пустой случай обработайте отдельно.
stringСтрока соответствующего преобразования; пустой fallback ошибки может совпадать с допустимым пустым значением.
public static string RawToBase64(ReadOnlySpan<byte> array);Кодирует байты стандартным Base64 без преобразования UTF-8. Массив и ReadOnlySpan дают одинаковый результат. Для пустого массива обработайте пустой результат явно до вызова: текущая обёртка диагностирует пустую закодированную строку.
| Имя | Тип | По умолчанию |
|---|---|---|
array | ReadOnlySpan<byte> | — |
arrayНепустые байты для точного Base64-кодирования. Нулевой байт внутри массива сохраняется; пустой случай обработайте отдельно.
stringСтрока соответствующего преобразования; пустой fallback ошибки может совпадать с допустимым пустым значением.
Utf8ToBase64string
public static string Utf8ToBase64(string utf8Str);Кодирует поддерживаемую строку движка в UTF-8 и затем Base64. Пустая строка даёт пустую без ошибки. Нативные строки не поддерживают встроенный NUL; для таких данных сначала используйте C# Encoding.UTF8.GetBytes и RawToBase64.
| Имя | Тип | По умолчанию |
|---|---|---|
utf8Str | string | — |
utf8StrПоддерживаемая строка без встроенного NUL. Пустая строка допустима. Для произвольных UTF-8-байтов используйте RawToBase64.
stringСтрока соответствующего преобразования; пустой fallback ошибки может совпадать с допустимым пустым значением.
VariantToBase64string
public static string VariantToBase64(Variant variant, bool fullObjects = false);Сначала сериализует Variant бинарным кодеком движка, затем Base64. fullObjects=false по умолчанию хранит объекты как ID, не клоны. Формат не JSON, не произвольная .NET-сериализация и не обещание межверсионной совместимости. Ошибка даёт пустую строку с диагностикой.
| Имя | Тип | По умолчанию |
|---|---|---|
variant | Variant | — |
fullObjects | bool | false |
variantЗначение Variant, не произвольный CLR-объект. Массивы/словари используйте из Reckfell.Collections; учитывайте режим сериализации объектов.
fullObjectsfalse сохраняет объектные ID; true разрешает полную сериализацию нативных объектов. Это не эквивалент обычного JSON и не гарантия переноса объектов между процессами.
stringСтрока соответствующего преобразования; пустой fallback ошибки может совпадать с допустимым пустым значением.