Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.codec.binary;
019
020import org.apache.commons.codec.BinaryDecoder;
021import org.apache.commons.codec.BinaryEncoder;
022import org.apache.commons.codec.DecoderException;
023import org.apache.commons.codec.EncoderException;
024
025/**
026 * Converts between byte arrays and strings of "0"s and "1"s.
027 *
028 * <p>This class is immutable and thread-safe.</p>
029 *
030 * TODO: may want to add more bit vector functions like and/or/xor/nand
031 * TODO: also might be good to generate boolean[] from byte[] et cetera.
032 *
033 * @since 1.3
034 */
035public class BinaryCodec implements BinaryDecoder, BinaryEncoder {
036    /*
037     * tried to avoid using ArrayUtils to minimize dependencies while using these empty arrays - dep is just not worth
038     * it.
039     */
040    /** Empty char array. */
041    private static final char[] EMPTY_CHAR_ARRAY = {};
042
043    /** Empty byte array. */
044    private static final byte[] EMPTY_BYTE_ARRAY = {};
045
046    /** Mask for bit 0 of a byte. */
047    private static final int BIT_0 = 1;
048
049    /** Mask for bit 1 of a byte. */
050    private static final int BIT_1 = 0x02;
051
052    /** Mask for bit 2 of a byte. */
053    private static final int BIT_2 = 0x04;
054
055    /** Mask for bit 3 of a byte. */
056    private static final int BIT_3 = 0x08;
057
058    /** Mask for bit 4 of a byte. */
059    private static final int BIT_4 = 0x10;
060
061    /** Mask for bit 5 of a byte. */
062    private static final int BIT_5 = 0x20;
063
064    /** Mask for bit 6 of a byte. */
065    private static final int BIT_6 = 0x40;
066
067    /** Mask for bit 7 of a byte. */
068    private static final int BIT_7 = 0x80;
069
070    private static final int[] BITS = {BIT_0, BIT_1, BIT_2, BIT_3, BIT_4, BIT_5, BIT_6, BIT_7};
071
072    /**
073     * Decodes a byte array where each byte represents an ASCII '0' or '1'.
074     *
075     * @param ascii
076     *                  each byte represents an ASCII '0' or '1'
077     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
078     */
079    public static byte[] fromAscii(final byte[] ascii) {
080        if (isEmpty(ascii)) {
081            return EMPTY_BYTE_ARRAY;
082        }
083        final int asciiLength = ascii.length;
084        // get length/8 times bytes with 3 bit shifts to the right of the length
085        final byte[] raw = new byte[asciiLength >> 3];
086        /*
087         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
088         * loop.
089         */
090        for (int ii = 0, jj = asciiLength - 1; ii < raw.length; ii++, jj -= 8) {
091            for (int bits = 0; bits < BITS.length; ++bits) {
092                if (ascii[jj - bits] == '1') {
093                    raw[ii] |= BITS[bits];
094                }
095            }
096        }
097        return raw;
098    }
099
100    /**
101     * Decodes a char array where each char represents an ASCII '0' or '1'.
102     *
103     * @param ascii
104     *                  each char represents an ASCII '0' or '1'
105     * @return the raw encoded binary where each bit corresponds to a char in the char array argument
106     */
107    public static byte[] fromAscii(final char[] ascii) {
108        if (ascii == null || ascii.length == 0) {
109            return EMPTY_BYTE_ARRAY;
110        }
111        final int asciiLength = ascii.length;
112        // get length/8 times bytes with 3 bit shifts to the right of the length
113        final byte[] raw = new byte[asciiLength >> 3];
114        /*
115         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
116         * loop.
117         */
118        for (int ii = 0, jj = asciiLength - 1; ii < raw.length; ii++, jj -= 8) {
119            for (int bits = 0; bits < BITS.length; ++bits) {
120                if (ascii[jj - bits] == '1') {
121                    raw[ii] |= BITS[bits];
122                }
123            }
124        }
125        return raw;
126    }
127
128    /**
129     * Returns {@code true} if the given array is {@code null} or empty (size 0.)
130     *
131     * @param array
132     *            the source array
133     * @return {@code true} if the given array is {@code null} or empty (size 0.)
134     */
135    static boolean isEmpty(final byte[] array) {
136        return array == null || array.length == 0;
137    }
138
139    /**
140     * Converts an array of raw binary data into an array of ASCII 0 and 1 character bytes - each byte is a truncated
141     * char.
142     *
143     * @param raw
144     *                  the raw binary data to convert
145     * @return an array of 0 and 1 character bytes for each bit of the argument
146     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
147     */
148    public static byte[] toAsciiBytes(final byte[] raw) {
149        if (isEmpty(raw)) {
150            return EMPTY_BYTE_ARRAY;
151        }
152        final int rawLength = raw.length;
153        // get 8 times the bytes with 3 bit shifts to the left of the length
154        final byte[] l_ascii = new byte[rawLength << 3];
155        /*
156         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
157         * loop.
158         */
159        for (int ii = 0, jj = l_ascii.length - 1; ii < rawLength; ii++, jj -= 8) {
160            for (int bits = 0; bits < BITS.length; ++bits) {
161                if ((raw[ii] & BITS[bits]) == 0) {
162                    l_ascii[jj - bits] = '0';
163                } else {
164                    l_ascii[jj - bits] = '1';
165                }
166            }
167        }
168        return l_ascii;
169    }
170
171    /**
172     * Converts an array of raw binary data into an array of ASCII 0 and 1 characters.
173     *
174     * @param raw
175     *                  the raw binary data to convert
176     * @return an array of 0 and 1 characters for each bit of the argument
177     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
178     */
179    public static char[] toAsciiChars(final byte[] raw) {
180        if (isEmpty(raw)) {
181            return EMPTY_CHAR_ARRAY;
182        }
183        final int rawLength = raw.length;
184        // get 8 times the bytes with 3 bit shifts to the left of the length
185        final char[] l_ascii = new char[rawLength << 3];
186        /*
187         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
188         * loop.
189         */
190        for (int ii = 0, jj = l_ascii.length - 1; ii < rawLength; ii++, jj -= 8) {
191            for (int bits = 0; bits < BITS.length; ++bits) {
192                if ((raw[ii] & BITS[bits]) == 0) {
193                    l_ascii[jj - bits] = '0';
194                } else {
195                    l_ascii[jj - bits] = '1';
196                }
197            }
198        }
199        return l_ascii;
200    }
201
202    /**
203     * Converts an array of raw binary data into a String of ASCII 0 and 1 characters.
204     *
205     * @param raw
206     *                  the raw binary data to convert
207     * @return a String of 0 and 1 characters representing the binary data
208     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
209     */
210    public static String toAsciiString(final byte[] raw) {
211        return new String(toAsciiChars(raw));
212    }
213
214    /**
215     * Constructs a new instance.
216     */
217    public BinaryCodec() {
218        // empty
219    }
220
221    /**
222     * Decodes a byte array where each byte represents an ASCII '0' or '1'.
223     *
224     * @param ascii
225     *                  each byte represents an ASCII '0' or '1'
226     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
227     * @see org.apache.commons.codec.Decoder#decode(Object)
228     */
229    @Override
230    public byte[] decode(final byte[] ascii) {
231        return fromAscii(ascii);
232    }
233
234    /**
235     * Decodes a byte array where each byte represents an ASCII '0' or '1'.
236     *
237     * @param ascii
238     *                  each byte represents an ASCII '0' or '1'
239     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
240     * @throws DecoderException
241     *                  if argument is not a byte[], char[] or String
242     * @see org.apache.commons.codec.Decoder#decode(Object)
243     */
244    @Override
245    public Object decode(final Object ascii) throws DecoderException {
246        if (ascii == null) {
247            return EMPTY_BYTE_ARRAY;
248        }
249        if (ascii instanceof byte[]) {
250            return fromAscii((byte[]) ascii);
251        }
252        if (ascii instanceof char[]) {
253            return fromAscii((char[]) ascii);
254        }
255        if (ascii instanceof String) {
256            return fromAscii(((String) ascii).toCharArray());
257        }
258        throw new DecoderException("argument not a byte array");
259    }
260
261    /**
262     * Converts an array of raw binary data into an array of ASCII 0 and 1 characters.
263     *
264     * @param raw
265     *                  the raw binary data to convert
266     * @return 0 and 1 ASCII character bytes one for each bit of the argument
267     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
268     */
269    @Override
270    public byte[] encode(final byte[] raw) {
271        return toAsciiBytes(raw);
272    }
273
274    /**
275     * Converts an array of raw binary data into an array of ASCII 0 and 1 chars.
276     *
277     * @param raw
278     *                  the raw binary data to convert
279     * @return 0 and 1 ASCII character chars one for each bit of the argument
280     * @throws EncoderException
281     *                  if the argument is not a byte[]
282     * @see org.apache.commons.codec.Encoder#encode(Object)
283     */
284    @Override
285    public Object encode(final Object raw) throws EncoderException {
286        if (!(raw instanceof byte[])) {
287            throw new EncoderException("argument not a byte array");
288        }
289        return toAsciiChars((byte[]) raw);
290    }
291
292    /**
293     * Decodes a String where each char of the String represents an ASCII '0' or '1'.
294     *
295     * @param ascii
296     *                  String of '0' and '1' characters
297     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
298     * @see org.apache.commons.codec.Decoder#decode(Object)
299     */
300    public byte[] toByteArray(final String ascii) {
301        if (ascii == null) {
302            return EMPTY_BYTE_ARRAY;
303        }
304        return fromAscii(ascii.toCharArray());
305    }
306}