1/*
2 * Copyright 2001-2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package org.apache.commons.codec.binary;
18
19import org.apache.commons.codec.BinaryDecoder;
20import org.apache.commons.codec.BinaryEncoder;
21import org.apache.commons.codec.DecoderException;
22import org.apache.commons.codec.EncoderException;
23
24/**
25 * Translates between byte arrays and strings of "0"s and "1"s.
26 *
27 * <b>TODO:</b> may want to add more bit vector functions like and/or/xor/nand.
28 * <B>TODO:</b> also might be good to generate boolean[]
29 * from byte[] et. cetera.
30 *
31 * @author Apache Software Foundation
32 * @since 1.3
33 * @version $Id $
34 */
35public class BinaryCodec implements BinaryDecoder, BinaryEncoder {
36    /*
37     * tried to avoid using ArrayUtils to minimize dependencies while using these empty arrays - dep is just not worth
38     * it.
39     */
40    /** Empty char array. */
41    private static final char[] EMPTY_CHAR_ARRAY = new char[0];
42
43    /** Empty byte array. */
44    private static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
45
46    /** Mask for bit 0 of a byte. */
47    private static final int BIT_0 = 1;
48
49    /** Mask for bit 1 of a byte. */
50    private static final int BIT_1 = 0x02;
51
52    /** Mask for bit 2 of a byte. */
53    private static final int BIT_2 = 0x04;
54
55    /** Mask for bit 3 of a byte. */
56    private static final int BIT_3 = 0x08;
57
58    /** Mask for bit 4 of a byte. */
59    private static final int BIT_4 = 0x10;
60
61    /** Mask for bit 5 of a byte. */
62    private static final int BIT_5 = 0x20;
63
64    /** Mask for bit 6 of a byte. */
65    private static final int BIT_6 = 0x40;
66
67    /** Mask for bit 7 of a byte. */
68    private static final int BIT_7 = 0x80;
69
70    private static final int[] BITS = {BIT_0, BIT_1, BIT_2, BIT_3, BIT_4, BIT_5, BIT_6, BIT_7};
71
72    /**
73     * Converts an array of raw binary data into an array of ascii 0 and 1 characters.
74     *
75     * @param raw
76     *                  the raw binary data to convert
77     * @return 0 and 1 ascii character bytes one for each bit of the argument
78     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
79     */
80    public byte[] encode(byte[] raw) {
81        return toAsciiBytes(raw);
82    }
83
84    /**
85     * Converts an array of raw binary data into an array of ascii 0 and 1 chars.
86     *
87     * @param raw
88     *                  the raw binary data to convert
89     * @return 0 and 1 ascii character chars one for each bit of the argument
90     * @throws EncoderException
91     *                  if the argument is not a byte[]
92     * @see org.apache.commons.codec.Encoder#encode(java.lang.Object)
93     */
94    public Object encode(Object raw) throws EncoderException {
95        if (!(raw instanceof byte[])) {
96            throw new EncoderException("argument not a byte array");
97        }
98        return toAsciiChars((byte[]) raw);
99    }
100
101    /**
102     * Decodes a byte array where each byte represents an ascii '0' or '1'.
103     *
104     * @param ascii
105     *                  each byte represents an ascii '0' or '1'
106     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
107     * @throws DecoderException
108     *                  if argument is not a byte[], char[] or String
109     * @see org.apache.commons.codec.Decoder#decode(java.lang.Object)
110     */
111    public Object decode(Object ascii) throws DecoderException {
112        if (ascii == null) {
113            return EMPTY_BYTE_ARRAY;
114        }
115        if (ascii instanceof byte[]) {
116            return fromAscii((byte[]) ascii);
117        }
118        if (ascii instanceof char[]) {
119            return fromAscii((char[]) ascii);
120        }
121        if (ascii instanceof String) {
122            return fromAscii(((String) ascii).toCharArray());
123        }
124        throw new DecoderException("argument not a byte array");
125    }
126
127    /**
128     * Decodes a byte array where each byte represents an ascii '0' or '1'.
129     *
130     * @param ascii
131     *                  each byte represents an ascii '0' or '1'
132     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
133     * @see org.apache.commons.codec.Decoder#decode(Object)
134     */
135    public byte[] decode(byte[] ascii) {
136        return fromAscii(ascii);
137    }
138
139    /**
140     * Decodes a String where each char of the String represents an ascii '0' or '1'.
141     *
142     * @param ascii
143     *                  String of '0' and '1' characters
144     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
145     * @see org.apache.commons.codec.Decoder#decode(Object)
146     */
147    public byte[] toByteArray(String ascii) {
148        if (ascii == null) {
149            return EMPTY_BYTE_ARRAY;
150        }
151        return fromAscii(ascii.toCharArray());
152    }
153
154    // ------------------------------------------------------------------------
155    //
156    // static codec operations
157    //
158    // ------------------------------------------------------------------------
159    /**
160     * Decodes a byte array where each char represents an ascii '0' or '1'.
161     *
162     * @param ascii
163     *                  each char represents an ascii '0' or '1'
164     * @return the raw encoded binary where each bit corresponds to a char in the char array argument
165     */
166    public static byte[] fromAscii(char[] ascii) {
167        if (ascii == null || ascii.length == 0) {
168            return EMPTY_BYTE_ARRAY;
169        }
170        // get length/8 times bytes with 3 bit shifts to the right of the length
171        byte[] l_raw = new byte[ascii.length >> 3];
172        /*
173         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
174         * loop.
175         */
176        for (int ii = 0, jj = ascii.length - 1; ii < l_raw.length; ii++, jj -= 8) {
177            for (int bits = 0; bits < BITS.length; ++bits) {
178                if (ascii[jj - bits] == '1') {
179                    l_raw[ii] |= BITS[bits];
180                }
181            }
182        }
183        return l_raw;
184    }
185
186    /**
187     * Decodes a byte array where each byte represents an ascii '0' or '1'.
188     *
189     * @param ascii
190     *                  each byte represents an ascii '0' or '1'
191     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
192     */
193    public static byte[] fromAscii(byte[] ascii) {
194        if (ascii == null || ascii.length == 0) {
195            return EMPTY_BYTE_ARRAY;
196        }
197        // get length/8 times bytes with 3 bit shifts to the right of the length
198        byte[] l_raw = new byte[ascii.length >> 3];
199        /*
200         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
201         * loop.
202         */
203        for (int ii = 0, jj = ascii.length - 1; ii < l_raw.length; ii++, jj -= 8) {
204            for (int bits = 0; bits < BITS.length; ++bits) {
205                if (ascii[jj - bits] == '1') {
206                    l_raw[ii] |= BITS[bits];
207                }
208            }
209        }
210        return l_raw;
211    }
212
213    /**
214     * Converts an array of raw binary data into an array of ascii 0 and 1 character bytes - each byte is a truncated
215     * char.
216     *
217     * @param raw
218     *                  the raw binary data to convert
219     * @return an array of 0 and 1 character bytes for each bit of the argument
220     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
221     */
222    public static byte[] toAsciiBytes(byte[] raw) {
223        if (raw == null || raw.length == 0) {
224            return EMPTY_BYTE_ARRAY;
225        }
226        // get 8 times the bytes with 3 bit shifts to the left of the length
227        byte[] l_ascii = new byte[raw.length << 3];
228        /*
229         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
230         * loop.
231         */
232        for (int ii = 0, jj = l_ascii.length - 1; ii < raw.length; ii++, jj -= 8) {
233            for (int bits = 0; bits < BITS.length; ++bits) {
234                if ((raw[ii] & BITS[bits]) == 0) {
235                    l_ascii[jj - bits] = '0';
236                } else {
237                    l_ascii[jj - bits] = '1';
238                }
239            }
240        }
241        return l_ascii;
242    }
243
244    /**
245     * Converts an array of raw binary data into an array of ascii 0 and 1 characters.
246     *
247     * @param raw
248     *                  the raw binary data to convert
249     * @return an array of 0 and 1 characters for each bit of the argument
250     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
251     */
252    public static char[] toAsciiChars(byte[] raw) {
253        if (raw == null || raw.length == 0) {
254            return EMPTY_CHAR_ARRAY;
255        }
256        // get 8 times the bytes with 3 bit shifts to the left of the length
257        char[] l_ascii = new char[raw.length << 3];
258        /*
259         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
260         * loop.
261         */
262        for (int ii = 0, jj = l_ascii.length - 1; ii < raw.length; ii++, jj -= 8) {
263            for (int bits = 0; bits < BITS.length; ++bits) {
264                if ((raw[ii] & BITS[bits]) == 0) {
265                    l_ascii[jj - bits] = '0';
266                } else {
267                    l_ascii[jj - bits] = '1';
268                }
269            }
270        }
271        return l_ascii;
272    }
273
274    /**
275     * Converts an array of raw binary data into a String of ascii 0 and 1 characters.
276     *
277     * @param raw
278     *                  the raw binary data to convert
279     * @return a String of 0 and 1 characters representing the binary data
280     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
281     */
282    public static String toAsciiString(byte[] raw) {
283        return new String(toAsciiChars(raw));
284    }
285}
286