This documentation is archived and is not being maintained.

Convert.ToBase64CharArray Method (Byte[], Int32, Int32, Char[], Int32, Base64FormattingOptions)

Converts a subset of an 8-bit unsigned integer array to an equivalent subset of a Unicode character array encoded with base 64 digits. Parameters specify the subsets as offsets in the input and output arrays, the number of elements in the input array to convert, and whether line breaks are inserted in the output array.

Namespace: System
Assembly: mscorlib (in mscorlib.dll)

[ComVisibleAttribute(false)] 
public static int ToBase64CharArray (
	byte[] inArray,
	int offsetIn,
	int length,
	char[] outArray,
	int offsetOut,
	Base64FormattingOptions options
)
/** @attribute ComVisibleAttribute(false) */ 
public static int ToBase64CharArray (
	byte[] inArray, 
	int offsetIn, 
	int length, 
	char[] outArray, 
	int offsetOut, 
	Base64FormattingOptions options
)
ComVisibleAttribute(false) 
public static function ToBase64CharArray (
	inArray : byte[], 
	offsetIn : int, 
	length : int, 
	outArray : char[], 
	offsetOut : int, 
	options : Base64FormattingOptions
) : int
Not applicable.

Parameters

inArray

An input array of 8-bit unsigned integers.

offsetIn

A position within inArray.

length

The number of elements of inArray to convert.

outArray

An output array of Unicode characters.

offsetOut

A position within outArray.

options

InsertLineBreaks to insert a line break every 76 characters, or None to not insert line breaks.

Return Value

A 32-bit signed integer containing the number of bytes in outArray.

Exception typeCondition

ArgumentNullException

inArray or outArray is a null reference (Nothing in Visual Basic).

ArgumentOutOfRangeException

offsetIn, offsetOut, or length is negative.

-or-

offsetIn plus length is greater than the length of inArray.

-or-

offsetOut plus the number of elements to return is greater than the length of outArray.

ArgumentException

options is not a valid Base64FormattingOptions value.

The subset of length elements of the inArray parameter starting at position offsetIn, are taken as a numeric value and converted to a subset of elements in the outArray parameter starting at position offsetOut. The return value indicates the number of converted elements in outArray. The subset of outArray consists of base 64 digits.

The base 64 digits in ascending order from zero are the uppercase characters 'A' to 'Z', the lowercase characters 'a' to 'z', the numerals '0' to '9', and the symbols '+' and '/'. The valueless character '=' is used for trailing padding.

The offset and length parameters are 32-bit signed numbers. The offsetIn and offsetOut parameters are zero-based array positions.

If the options parameter is set to InsertLineBreaks and the output of the conversion is longer than 76 characters, a line break is inserted every 76 characters. A line break is defined as a carriage return character (U+000D) followed by a line feed character (U+000A). For more information, see RFC 2045, "Multipurpose Internet Mail Extensions", at http://www.rfc-editor.org/.

The following code example demonstrates the ToBase64CharArray method. The input is divided into groups of three bytes (24 bits) each. Consequently, each group consists of four 6-bit numbers where each number ranges from decimal 0 to 63. In this example, there are 85 3-byte groups with one byte remaining. The first group consists of the hexadecimal values 00, 01, and 02, which yield four 6-bit values equal to decimal 0, 0, 4, and 2. Those four values correspond to the base 64 digits 'A', 'A', 'E', and 'C' at the beginning of the output.

If there is not an integral number of 3-byte groups, the remaining bytes are effectively padded with zeroes to form a complete group. In this example, the value of the last byte is hexadecimal FF. The first 6 bits are equal to decimal 63, which corresponds to the base 64 digit '/' at the end of the output, and the next 2 bits are padded with zeroes to yield decimal 48, which corresponds to the base 64 digit 'w'. The last two 6-bit values are padding and correspond to the valueless padding character, '='.

// This example demonstrates the Convert.ToBase64CharArray() and
//                               Convert.FromBase64CharArray methods

using System;

class Sample 
{
    public static void Main() 
    {
    byte[] byteArray1 = new byte[256];
    byte[] byteArray2 = new byte[256];
    char[] charArray  = new char[352];
    int charArrayLength;
    string nl = Environment.NewLine;

    string ruler1a = "         1         2         3         4";
    string ruler2a = "1234567890123456789012345678901234567890";
    string ruler3a = "----+----+----+----+----+----+----+----+";
    string ruler1b = "         5         6         7      ";
    string ruler2b = "123456789012345678901234567890123456";
    string ruler3b = "----+----+----+----+----+----+----+-";
    string ruler   = String.Concat(ruler1a, ruler1b, nl, 
                                   ruler2a, ruler2b, nl,
                                   ruler3a, ruler3b);

// 1) Initialize and display a Byte array of arbitrary data.
    Console.WriteLine("1) Input: A Byte array of arbitrary data.{0}", nl);
    for (int x = 0; x < byteArray1.Length; x++)
    {
    byteArray1[x] = (byte)x;
    Console.Write("{0:X2} ", byteArray1[x]);
    if (((x+1)%20) == 0) Console.WriteLine();
    }
    Console.Write("{0}{0}", nl);

// 2) Convert the input Byte array to a Char array, with newlines inserted.
    charArrayLength = 
        Convert.ToBase64CharArray(byteArray1, 0, byteArray1.Length, 
                                   charArray, 0, Base64FormattingOptions.InsertLineBreaks);
    Console.WriteLine("2) Convert the input Byte array to a Char array with newlines.");
    Console.Write("   Output: A Char array (length = {0}). ", charArrayLength);
    Console.WriteLine("The elements of the array are:{0}", nl);
    Console.WriteLine(ruler);
    Console.WriteLine(new String(charArray));
    Console.WriteLine();

// 3) Convert the Char array back to a Byte array.
    Console.WriteLine("3) Convert the Char array to an output Byte array.");
    byteArray2 = Convert.FromBase64CharArray(charArray, 0, charArrayLength);

// 4) Are the input and output Byte arrays equivalent?
    Console.WriteLine("4) The output Byte array is equal to the input Byte array?: {0}", 
                      ArraysAreEqual(byteArray1, byteArray2));
    }

    public static bool ArraysAreEqual(byte[] a1, byte[] a2)
    {
    if (a1.Length != a2.Length) return false;
    for (int i = 0; i < a1.Length; i++)
        if (a1[i] != a2[i]) return false;
    return true;
    }
}
/*
This example produces the following results:

1) Input: A Byte array of arbitrary data.

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13
14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B
3C 3D 3E 3F 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F 60 61 62 63
64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F 80 81 82 83 84 85 86 87 88 89 8A 8B
8C 8D 8E 8F 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF B0 B1 B2 B3
B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB
DC DD DE DF E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF

2) Convert the input Byte array to a Char array with newlines.
   Output: A Char array (length = 352). The elements of the array are:

         1         2         3         4         5         6         7
1234567890123456789012345678901234567890123456789012345678901234567890123456
----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+-
AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4
OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3Bx
cnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmq
q6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj
5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w==

3) Convert the Char array to an output Byte array.
4) The output Byte array is equal to the input Byte array?: True

*/

// This example demonstrates the Convert.ToBase64CharArray() and
//                               Convert.FromBase64CharArray methods
import System.*;

class Sample
{
    public static void main(String[] args)
    {
        ubyte byteArray1[] = new ubyte[256];
        ubyte byteArray2[] = new ubyte[256];
        char charArray[] = new char[352];
        int charArrayLength;
        String nl = Environment.get_NewLine();

        String ruler1a = "         1         2         3         4";
        String ruler2a = "1234567890123456789012345678901234567890";
        String ruler3a = "----+----+----+----+----+----+----+----+";
        String ruler1b = "         5         6         7      ";
        String ruler2b = "123456789012345678901234567890123456";
        String ruler3b = "----+----+----+----+----+----+----+-";
        String sTemp[] = {
            ruler1a, ruler1b, nl, ruler2a, ruler2b, nl, ruler3a, ruler3b
        };
        String ruler = String.Concat(sTemp);
        // 1) Initialize and display a Byte array of arbitrary data.
        Console.WriteLine("1) Input: A Byte array of arbitrary data.{0}", nl);
        for (int x = 0; x < byteArray1.get_Length(); x++) {
            byteArray1[x] = (ubyte)x;
            Console.Write("{0:X2} ", byteArray1.get_Item(x));
            if ((x + 1) % 20 == 0) {
                Console.WriteLine();
            }
        }
        Console.Write("{0}{0}", nl);
        // 2) Convert the input Byte array to a Char array,
        // with newlines inserted.
        charArrayLength = Convert.ToBase64CharArray(byteArray1, 0,
            byteArray1.get_Length(), charArray, 0, 
            Base64FormattingOptions.InsertLineBreaks);
        Console.WriteLine("2) Convert the input Byte array to a Char "
            + "array with newlines.");
        Console.Write("   Output: A Char array (length = {0}). ",
            System.Convert.ToString(charArrayLength));
        Console.WriteLine("The elements of the array are:{0}", nl);
        Console.WriteLine(ruler);
        Console.WriteLine(new String(charArray));
        Console.WriteLine();
        // 3) Convert the Char array back to a Byte array.
        Console.WriteLine("3) Convert the Char array to an output Byte array.");
        byteArray2 = Convert.FromBase64CharArray(charArray, 0, charArrayLength);
        // 4) Are the input and output Byte arrays equivalent?
        Console.WriteLine("4) The output Byte array is equal to the input Byte "
            + "array?: {0}",
            System.Convert.ToString(ArraysAreEqual(byteArray1, byteArray2)));
    } //main

    public static boolean ArraysAreEqual(ubyte a1[], ubyte a2[]) 
    {
        if (a1.get_Length() != a2.get_Length()) {
            return false;
        }
        for (int i = 0; i < a1.get_Length(); i++) {
            if (!a1.get_Item(i).Equals(a2.get_Item(i))) {
                return false;
            }
        }
        return true;
    } //ArraysAreEqual
} //Sample
/*
This example produces the following results:

1) Input: A Byte array of arbitrary data.

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13
14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B
3C 3D 3E 3F 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F 60 61 62 63
64 65 66 67 68 69 6A 6B 6C 6D 6E 6F 70 71 72 73 74 75 76 77
78 79 7A 7B 7C 7D 7E 7F 80 81 82 83 84 85 86 87 88 89 8A 8B
8C 8D 8E 8F 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF B0 B1 B2 B3
B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF C0 C1 C2 C3 C4 C5 C6 C7
C8 C9 CA CB CC CD CE CF D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB
DC DD DE DF E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF

2) Convert the input Byte array to a Char array with newlines.
   Output: A Char array (length = 352). The elements of the array are:

         1         2         3         4         5         6         7
1234567890123456789012345678901234567890123456789012345678901234567890123456
----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+-
AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4
OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3Bx
cnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmq
q6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj
5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w==

3) Convert the Char array to an output Byte array.
4) The output Byte array is equal to the input Byte array?: True

*/

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0
Show: