BinaryCodec


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  
17  package org.apache.commons.codec.binary;
18  
19  import org.apache.commons.codec.BinaryDecoder;
20  import org.apache.commons.codec.BinaryEncoder;
21  import org.apache.commons.codec.DecoderException;
22  import org.apache.commons.codec.EncoderException;
23  
24  /**
25   * Translates between byte arrays and strings of "0"s and "1"s.
26   * 
27   * @todo may want to add more bit vector functions like and/or/xor/nand 
28   * @todo 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   */
35  public 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags