    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 *      http://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 = new char[0];
    042
    043    /** Empty byte array. */
    044    private static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
    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     * Converts an array of raw binary data into an array of ASCII 0 and 1 characters.
    074     *
    075     * @param raw
    076     *                  the raw binary data to convert
    077     * @return 0 and 1 ASCII character bytes one for each bit of the argument
    078     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
    079     */
    080    @Override
    081    public byte[] encode(final byte[] raw) {
    082        return toAsciiBytes(raw);
    083    }
    084
    085    /**
    086     * Converts an array of raw binary data into an array of ASCII 0 and 1 chars.
    087     *
    088     * @param raw
    089     *                  the raw binary data to convert
    090     * @return 0 and 1 ASCII character chars one for each bit of the argument
    091     * @throws EncoderException
    092     *                  if the argument is not a byte[]
    093     * @see org.apache.commons.codec.Encoder#encode(Object)
    094     */
    095    @Override
    096    public Object encode(final Object raw) throws EncoderException {
    097        if (!(raw instanceof byte[])) {
    098            throw new EncoderException("argument not a byte array");
    099        }
    100        return toAsciiChars((byte[]) raw);
    101    }
    102
    103    /**
    104     * Decodes a byte array where each byte represents an ASCII '0' or '1'.
    105     *
    106     * @param ascii
    107     *                  each byte represents an ASCII '0' or '1'
    108     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
    109     * @throws DecoderException
    110     *                  if argument is not a byte[], char[] or String
    111     * @see org.apache.commons.codec.Decoder#decode(Object)
    112     */
    113    @Override
    114    public Object decode(final Object ascii) throws DecoderException {
    115        if (ascii == null) {
    116            return EMPTY_BYTE_ARRAY;
    117        }
    118        if (ascii instanceof byte[]) {
    119            return fromAscii((byte[]) ascii);
    120        }
    121        if (ascii instanceof char[]) {
    122            return fromAscii((char[]) ascii);
    123        }
    124        if (ascii instanceof String) {
    125            return fromAscii(((String) ascii).toCharArray());
    126        }
    127        throw new DecoderException("argument not a byte array");
    128    }
    129
    130    /**
    131     * Decodes a byte array where each byte represents an ASCII '0' or '1'.
    132     *
    133     * @param ascii
    134     *                  each byte represents an ASCII '0' or '1'
    135     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
    136     * @see org.apache.commons.codec.Decoder#decode(Object)
    137     */
    138    @Override
    139    public byte[] decode(final byte[] ascii) {
    140        return fromAscii(ascii);
    141    }
    142
    143    /**
    144     * Decodes a String where each char of the String represents an ASCII '0' or '1'.
    145     *
    146     * @param ascii
    147     *                  String of '0' and '1' characters
    148     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
    149     * @see org.apache.commons.codec.Decoder#decode(Object)
    150     */
    151    public byte[] toByteArray(final String ascii) {
    152        if (ascii == null) {
    153            return EMPTY_BYTE_ARRAY;
    154        }
    155        return fromAscii(ascii.toCharArray());
    156    }
    157
    158    // ------------------------------------------------------------------------
    159    //
    160    // static codec operations
    161    //
    162    // ------------------------------------------------------------------------
    163    /**
    164     * Decodes a char array where each char represents an ASCII '0' or '1'.
    165     *
    166     * @param ascii
    167     *                  each char represents an ASCII '0' or '1'
    168     * @return the raw encoded binary where each bit corresponds to a char in the char array argument
    169     */
    170    public static byte[] fromAscii(final char[] ascii) {
    171        if (ascii == null || ascii.length == 0) {
    172            return EMPTY_BYTE_ARRAY;
    173        }
    174        // get length/8 times bytes with 3 bit shifts to the right of the length
    175        final byte[] l_raw = new byte[ascii.length >> 3];
    176        /*
    177         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
    178         * loop.
    179         */
    180        for (int ii = 0, jj = ascii.length - 1; ii < l_raw.length; ii++, jj -= 8) {
    181            for (int bits = 0; bits < BITS.length; ++bits) {
    182                if (ascii[jj - bits] == '1') {
    183                    l_raw[ii] |= BITS[bits];
    184                }
    185            }
    186        }
    187        return l_raw;
    188    }
    189
    190    /**
    191     * Decodes a byte array where each byte represents an ASCII '0' or '1'.
    192     *
    193     * @param ascii
    194     *                  each byte represents an ASCII '0' or '1'
    195     * @return the raw encoded binary where each bit corresponds to a byte in the byte array argument
    196     */
    197    public static byte[] fromAscii(final byte[] ascii) {
    198        if (isEmpty(ascii)) {
    199            return EMPTY_BYTE_ARRAY;
    200        }
    201        // get length/8 times bytes with 3 bit shifts to the right of the length
    202        final byte[] l_raw = new byte[ascii.length >> 3];
    203        /*
    204         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
    205         * loop.
    206         */
    207        for (int ii = 0, jj = ascii.length - 1; ii < l_raw.length; ii++, jj -= 8) {
    208            for (int bits = 0; bits < BITS.length; ++bits) {
    209                if (ascii[jj - bits] == '1') {
    210                    l_raw[ii] |= BITS[bits];
    211                }
    212            }
    213        }
    214        return l_raw;
    215    }
    216
    217    /**
    218     * Returns {@code true} if the given array is {@code null} or empty (size 0.)
    219     *
    220     * @param array
    221     *            the source array
    222     * @return {@code true} if the given array is {@code null} or empty (size 0.)
    223     */
    224    private static boolean isEmpty(final byte[] array) {
    225        return array == null || array.length == 0;
    226    }
    227
    228    /**
    229     * Converts an array of raw binary data into an array of ASCII 0 and 1 character bytes - each byte is a truncated
    230     * char.
    231     *
    232     * @param raw
    233     *                  the raw binary data to convert
    234     * @return an array of 0 and 1 character bytes for each bit of the argument
    235     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
    236     */
    237    public static byte[] toAsciiBytes(final byte[] raw) {
    238        if (isEmpty(raw)) {
    239            return EMPTY_BYTE_ARRAY;
    240        }
    241        // get 8 times the bytes with 3 bit shifts to the left of the length
    242        final byte[] l_ascii = new byte[raw.length << 3];
    243        /*
    244         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
    245         * loop.
    246         */
    247        for (int ii = 0, jj = l_ascii.length - 1; ii < raw.length; ii++, jj -= 8) {
    248            for (int bits = 0; bits < BITS.length; ++bits) {
    249                if ((raw[ii] & BITS[bits]) == 0) {
    250                    l_ascii[jj - bits] = '0';
    251                } else {
    252                    l_ascii[jj - bits] = '1';
    253                }
    254            }
    255        }
    256        return l_ascii;
    257    }
    258
    259    /**
    260     * Converts an array of raw binary data into an array of ASCII 0 and 1 characters.
    261     *
    262     * @param raw
    263     *                  the raw binary data to convert
    264     * @return an array of 0 and 1 characters for each bit of the argument
    265     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
    266     */
    267    public static char[] toAsciiChars(final byte[] raw) {
    268        if (isEmpty(raw)) {
    269            return EMPTY_CHAR_ARRAY;
    270        }
    271        // get 8 times the bytes with 3 bit shifts to the left of the length
    272        final char[] l_ascii = new char[raw.length << 3];
    273        /*
    274         * We decr index jj by 8 as we go along to not recompute indices using multiplication every time inside the
    275         * loop.
    276         */
    277        for (int ii = 0, jj = l_ascii.length - 1; ii < raw.length; ii++, jj -= 8) {
    278            for (int bits = 0; bits < BITS.length; ++bits) {
    279                if ((raw[ii] & BITS[bits]) == 0) {
    280                    l_ascii[jj - bits] = '0';
    281                } else {
    282                    l_ascii[jj - bits] = '1';
    283                }
    284            }
    285        }
    286        return l_ascii;
    287    }
    288
    289    /**
    290     * Converts an array of raw binary data into a String of ASCII 0 and 1 characters.
    291     *
    292     * @param raw
    293     *                  the raw binary data to convert
    294     * @return a String of 0 and 1 characters representing the binary data
    295     * @see org.apache.commons.codec.BinaryEncoder#encode(byte[])
    296     */
    297    public static String toAsciiString(final byte[] raw) {
    298        return new String(toAsciiChars(raw));
    299    }
    300}