|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System.Diagnostics;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using static System.Buffers.Text.Base64Helper;
namespace System.Buffers.Text
{
/// <summary>
/// Convert between binary data and UTF-8 encoded text that is represented in base 64.
/// </summary>
public static partial class Base64
{
/// <summary>
/// Returns the length (in bytes) of the result if you were to encode binary data within a byte span of size <paramref name="bytesLength"/>.
/// </summary>
/// <param name="bytesLength">The number of bytes to encode.</param>
/// <returns>The number of bytes that encoding will produce.</returns>
/// <exception cref="ArgumentOutOfRangeException">
/// <paramref name="bytesLength"/> is less than 0 or greater than 1610612733.
/// </exception>
/// <remarks>
/// This method is equivalent to <see cref="GetMaxEncodedToUtf8Length(int)"/>. The encoded length for base64 is exactly calculated, not an upper bound.
/// </remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static int GetEncodedLength(int bytesLength)
{
ArgumentOutOfRangeException.ThrowIfGreaterThan<uint>((uint)bytesLength, MaximumEncodeLength);
return ((bytesLength + 2) / 3) * 4;
}
/// <summary>
/// Returns the maximum length (in bytes) of the result if you were to encode binary data within a byte span of size "length".
/// </summary>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when the specified <paramref name="length"/> is less than 0 or larger than 1610612733 (since encode inflates the data by 4/3).
/// </exception>
/// <remarks>
/// This method is equivalent to <see cref="GetEncodedLength(int)"/>. The encoded length for base64 is exactly calculated, not an upper bound.
/// </remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static int GetMaxEncodedToUtf8Length(int length) => GetEncodedLength(length);
/// <summary>
/// Encode the span of binary data into UTF-8 encoded text represented as base64.
/// </summary>
/// <param name="bytes">The input span which contains binary data that needs to be encoded.</param>
/// <param name="utf8">The output span which contains the result of the operation, i.e. the UTF-8 encoded text in base64.</param>
/// <param name="bytesConsumed">The number of input bytes consumed during the operation. This can be used to slice the input for subsequent calls, if necessary.</param>
/// <param name="bytesWritten">The number of bytes written into the output span. This can be used to slice the output for subsequent calls, if necessary.</param>
/// <param name="isFinalBlock"><see langword="true"/> (default) when the input span contains the entire data to encode.
/// Set to <see langword="true"/> when the source buffer contains the entirety of the data to encode.
/// Set to <see langword="false"/> if this method is being called in a loop and if more input data may follow.
/// At the end of the loop, call this (potentially with an empty source buffer) passing <see langword="true"/>.</param>
/// <returns>It returns the <see cref="OperationStatus"/> enum values:
/// - Done - on successful processing of the entire input span
/// - DestinationTooSmall - if there is not enough space in the output span to fit the encoded input
/// - NeedMoreData - only if <paramref name="isFinalBlock"/> is <see langword="false"/>, otherwise the output is padded if the input is not a multiple of 3
/// It does not return InvalidData since that is not possible for base64 encoding.
/// </returns>
public static OperationStatus EncodeToUtf8(ReadOnlySpan<byte> bytes, Span<byte> utf8, out int bytesConsumed, out int bytesWritten, bool isFinalBlock = true) =>
EncodeTo(default(Base64EncoderByte), bytes, utf8, out bytesConsumed, out bytesWritten, isFinalBlock);
/// <summary>
/// Encodes the span of binary data into UTF-8 encoded text represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <param name="destination">The output span which contains the result of the operation, i.e. the UTF-8 encoded text in Base64.</param>
/// <returns>The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary.</returns>
/// <exception cref="ArgumentException">The buffer in <paramref name="destination"/> is too small to hold the encoded output.</exception>
public static int EncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination)
{
OperationStatus status = EncodeToUtf8(source, destination, out _, out int bytesWritten);
if (status == OperationStatus.Done)
{
return bytesWritten;
}
Debug.Assert(status == OperationStatus.DestinationTooSmall);
throw new ArgumentException(SR.Argument_DestinationTooShort, nameof(destination));
}
/// <summary>
/// Encodes the span of binary data into UTF-8 encoded text represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <returns>The output byte array which contains the result of the operation, i.e. the UTF-8 encoded text in Base64.</returns>
public static byte[] EncodeToUtf8(ReadOnlySpan<byte> source)
{
byte[] destination = new byte[GetEncodedLength(source.Length)];
EncodeToUtf8(source, destination, out _, out int bytesWritten);
Debug.Assert(destination.Length == bytesWritten);
return destination;
}
/// <summary>
/// Encodes the span of binary data into UTF-8 encoded text represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <param name="destination">The output span which contains the result of the operation, i.e. the UTF-8 encoded text in Base64.</param>
/// <param name="bytesWritten">When this method returns, contains the number of bytes written into the output span. This can be used to slice the output for subsequent calls, if necessary. This parameter is treated as uninitialized.</param>
/// <returns><see langword="true"/> if bytes encoded successfully, otherwise <see langword="false"/>.</returns>
public static bool TryEncodeToUtf8(ReadOnlySpan<byte> source, Span<byte> destination, out int bytesWritten)
{
OperationStatus status = EncodeToUtf8(source, destination, out _, out bytesWritten);
return status == OperationStatus.Done;
}
/// <summary>
/// Encode the span of binary data (in-place) into UTF-8 encoded text represented as base 64.
/// The encoded text output is larger than the binary data contained in the input (the operation inflates the data).
/// </summary>
/// <param name="buffer">The input span which contains binary data that needs to be encoded.
/// It needs to be large enough to fit the result of the operation.</param>
/// <param name="dataLength">The amount of binary data contained within the buffer that needs to be encoded
/// (and needs to be smaller than the buffer length).</param>
/// <param name="bytesWritten">The number of bytes written into the buffer.</param>
/// <returns>It returns the OperationStatus enum values:
/// - Done - on successful processing of the entire buffer
/// - DestinationTooSmall - if there is not enough space in the buffer beyond dataLength to fit the result of encoding the input
/// It does not return NeedMoreData since this method tramples the data in the buffer and hence can only be called once with all the data in the buffer.
/// It does not return InvalidData since that is not possible for base 64 encoding.
/// </returns>
public static OperationStatus EncodeToUtf8InPlace(Span<byte> buffer, int dataLength, out int bytesWritten) =>
Base64Helper.EncodeToUtf8InPlace(default(Base64EncoderByte), buffer, dataLength, out bytesWritten);
/// <summary>
/// Encodes the span of binary data (in-place) into UTF-8 encoded text represented as base 64.
/// The encoded text output is larger than the binary data contained in the input (the operation inflates the data).
/// </summary>
/// <param name="buffer">The input span which contains binary data that needs to be encoded.
/// It needs to be large enough to fit the result of the operation.</param>
/// <param name="dataLength">The amount of binary data contained within the buffer that needs to be encoded
/// (and needs to be smaller than the buffer length).</param>
/// <param name="bytesWritten">When this method returns, contains the number of bytes written into the buffer. This parameter is treated as uninitialized.</param>
/// <returns><see langword="true"/> if bytes encoded successfully, otherwise <see langword="false"/>.</returns>
public static bool TryEncodeToUtf8InPlace(Span<byte> buffer, int dataLength, out int bytesWritten)
{
OperationStatus status = EncodeToUtf8InPlace(buffer, dataLength, out bytesWritten);
return status == OperationStatus.Done;
}
/// <summary>
/// Encodes the span of binary data into unicode ASCII chars represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <param name="destination">The output span which contains the result of the operation, i.e. the ASCII chars in Base64.</param>
/// <param name="bytesConsumed">When this method returns, contains the number of input bytes consumed during the operation. This can be used to slice the input for subsequent calls, if necessary. This parameter is treated as uninitialized.</param>
/// <param name="charsWritten">When this method returns, contains the number of chars written into the output span. This can be used to slice the output for subsequent calls, if necessary. This parameter is treated as uninitialized.</param>
/// <param name="isFinalBlock"><see langword="true"/> when the input span contains the entirety of data to encode; <see langword="false"/> when more data may follow,
/// such as when calling in a loop, subsequent calls with <see langword="false"/> should end with <see langword="true"/> call. The default is <see langword="true" />.</param>
/// <returns>One of the enumeration values that indicates the success or failure of the operation.</returns>
public static OperationStatus EncodeToChars(ReadOnlySpan<byte> source, Span<char> destination,
out int bytesConsumed, out int charsWritten, bool isFinalBlock = true) =>
EncodeTo(default(Base64EncoderChar), source, MemoryMarshal.Cast<char, ushort>(destination), out bytesConsumed, out charsWritten, isFinalBlock);
/// <summary>
/// Encodes the span of binary data into unicode ASCII chars represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <param name="destination">The output span which contains the result of the operation, i.e. the ASCII chars in Base64.</param>
/// <returns>The number of chars written into the destination span. This can be used to slice the output for subsequent calls, if necessary.</returns>
/// <exception cref="ArgumentException">The buffer in <paramref name="destination"/> is too small to hold the encoded output.</exception>
public static int EncodeToChars(ReadOnlySpan<byte> source, Span<char> destination)
{
OperationStatus status = EncodeToChars(source, destination, out _, out int charsWritten);
if (status == OperationStatus.Done)
{
return charsWritten;
}
Debug.Assert(status == OperationStatus.DestinationTooSmall);
throw new ArgumentException(SR.Argument_DestinationTooShort, nameof(destination));
}
/// <summary>
/// Encodes the span of binary data into unicode ASCII chars represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <returns>A char array which contains the result of the operation, i.e. the ASCII chars in Base64.</returns>
public static char[] EncodeToChars(ReadOnlySpan<byte> source)
{
char[] destination = new char[GetEncodedLength(source.Length)];
EncodeToChars(source, destination, out _, out int charsWritten);
Debug.Assert(destination.Length == charsWritten);
return destination;
}
/// <summary>
/// Encodes the span of binary data into unicode string represented as Base64 ASCII chars.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <returns>A string which contains the result of the operation, i.e. the ASCII string in Base64.</returns>
public static string EncodeToString(ReadOnlySpan<byte> source) =>
string.Create(GetEncodedLength(source.Length), source, static (buffer, source) =>
{
EncodeToChars(source, buffer, out _, out int charsWritten);
Debug.Assert(buffer.Length == charsWritten, $"The source length: {source.Length}, chars written: {charsWritten}");
});
/// <summary>
/// Encodes the span of binary data into unicode ASCII chars represented as Base64.
/// </summary>
/// <param name="source">The input span which contains binary data that needs to be encoded.</param>
/// <param name="destination">The output span which contains the result of the operation, i.e. the ASCII chars in Base64.</param>
/// <param name="charsWritten">When this method returns, contains the number of chars written into the output span. This can be used to slice the output for subsequent calls, if necessary. This parameter is treated as uninitialized.</param>
/// <returns><see langword="true"/> if chars encoded successfully, otherwise <see langword="false"/>.</returns>
public static bool TryEncodeToChars(ReadOnlySpan<byte> source, Span<char> destination, out int charsWritten)
{
OperationStatus status = EncodeToChars(source, destination, out _, out charsWritten);
return status == OperationStatus.Done;
}
}
}
|