Marshalls
Base64 for bytes, UTF-8 text and binary Variant: three distinct contracts.
RawToBase64/Base64ToRaw transform bytes; Utf8ToBase64/Base64ToUtf8 transform text through UTF-8; VariantToBase64/Base64ToVariant use binary Variant data inside Base64. Do not mix these contracts arbitrarily: Base64-encoded plain UTF-8 is not a serialized Variant. Base64 neither encrypts nor compresses data. The service is shared; do not manually dispose Singleton.
Base64ToUtf8 reads decoded bytes as a NUL-terminated string: QQBC gives A rather than the three bytes A, 0, B. Use Base64ToRaw for exact bytes and Encoding.UTF8.GetString on the byte[] when needed in C#. Native engine strings do not support embedded NUL; do not expect Utf8ToBase64 to retain it.
With fullObjects=false, objects serialize as identifiers rather than independent copies and can decode to EncodedObjectAsId. This is not a portable reference into another process. fullObjects/allowObjects enable a different mode that reconstructs native objects; keep them disabled for external data. Arbitrary CLR object graphs are not serialized.
The combined suite ran 31 Windows headless checks for Base64 and containers. Marshalls coverage included bytes, Unicode, Int64, nil, vectors/Color, nested containers and object-ID mode. Malformed input, full-object reconstruction and format portability across versions/builds remain unaccepted. Decoded nil can be a valid value or a diagnosed-failure fallback; validate the expected type/schema.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Properties1
SingletonProperty
public static MarshallsInstance Singleton { get; }Borrowed shared engine service behind static Marshalls methods. Do not Free/Dispose the instance; static calls are sufficient for ordinary use.
Methods7
Base64ToRawbyte[]
public static byte[] Base64ToRaw(string base64Str);Decodes Base64 into a new byte[] retaining zero and arbitrary byte values. Interprets neither text nor Variant data. Empty input yields an empty array; failure can also return an empty fallback with a diagnostic.
| Name | Type | Default |
|---|---|---|
base64Str | string | — |
base64StrValid Base64 text for the corresponding method pair, not arbitrary text, a path or JSON.
byte[]New byte[]; empty for empty input or a diagnosed failure.
Base64ToUtf8string
public static string Base64ToUtf8(string base64Str);Decodes Base64 and creates UTF-8 text up to the first zero byte. Not lossless recovery of an arbitrary byte[]. Use Base64ToRaw plus explicit C# decoding to retain NUL. Malformed UTF-8/Base64 were not accepted by this review.
| Name | Type | Default |
|---|---|---|
base64Str | string | — |
base64StrValid Base64 text for the corresponding method pair, not arbitrary text, a path or JSON.
stringText from the corresponding transform; an empty failure fallback can overlap a valid empty value.
Base64ToVariantVariant
public static Variant Base64ToVariant(string base64Str, bool allowObjects = false);Decodes VariantToBase64 data into a Variant. allowObjects=false disallows full-object reconstruction but object-ID wrappers remain possible. Dispose the returned Variant after use. Nil is not an unambiguous failure indicator because it is also a valid value.
| Name | Type | Default |
|---|---|---|
base64Str | string | — |
allowObjects | bool | false |
base64StrValid Base64 text for the corresponding method pair, not arbitrary text, a path or JSON.
allowObjectsKeep false for external data; true permits full native-object reconstruction. That mode was not exercised in this run.
VariantCaller-owned Variant; nil is valid and does not identify failure by itself.
RawToBase642 overloads
public static string RawToBase64(byte[] array);Encodes bytes as standard Base64 without UTF-8 conversion. Array and ReadOnlySpan produce the same result. Handle empty input explicitly before calling: the current wrapper diagnoses an empty encoded result.
| Name | Type | Default |
|---|---|---|
array | byte[] | — |
arrayNonempty bytes for exact Base64 encoding. Embedded zero bytes are retained; handle empty input separately.
stringText from the corresponding transform; an empty failure fallback can overlap a valid empty value.
public static string RawToBase64(ReadOnlySpan<byte> array);Encodes bytes as standard Base64 without UTF-8 conversion. Array and ReadOnlySpan produce the same result. Handle empty input explicitly before calling: the current wrapper diagnoses an empty encoded result.
| Name | Type | Default |
|---|---|---|
array | ReadOnlySpan<byte> | — |
arrayNonempty bytes for exact Base64 encoding. Embedded zero bytes are retained; handle empty input separately.
stringText from the corresponding transform; an empty failure fallback can overlap a valid empty value.
Utf8ToBase64string
public static string Utf8ToBase64(string utf8Str);Encodes a supported engine string as UTF-8 then Base64. Empty text returns empty without error. Native strings do not support embedded NUL; for such data use C# Encoding.UTF8.GetBytes and RawToBase64 first.
| Name | Type | Default |
|---|---|---|
utf8Str | string | — |
utf8StrSupported text without embedded NUL. Empty text is allowed. Use RawToBase64 for arbitrary UTF-8 bytes.
stringText from the corresponding transform; an empty failure fallback can overlap a valid empty value.
VariantToBase64string
public static string VariantToBase64(Variant variant, bool fullObjects = false);Serializes Variant with the engine binary codec then Base64. Default fullObjects=false stores objects as IDs rather than clones. Neither JSON, arbitrary .NET serialization nor a cross-version compatibility promise. Failure returns empty text with a diagnostic.
| Name | Type | Default |
|---|---|---|
variant | Variant | — |
fullObjects | bool | false |
variantVariant value rather than an arbitrary CLR object. Use Reckfell.Collections arrays/dictionaries and account for object-serialization mode.
fullObjectsfalse stores object IDs; true permits full native-object serialization. Neither ordinary JSON nor a guarantee of transferring objects across processes.
stringText from the corresponding transform; an empty failure fallback can overlap a valid empty value.