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 */
017package org.apache.commons.io;
018
019import java.io.IOException;
020import java.io.OutputStream;
021import java.nio.charset.Charset;
022
023/**
024 * Dumps data in hexadecimal format.
025 * <p>
026 * Provides a single function to take an array of bytes and display it
027 * in hexadecimal form.
028 * <p>
029 * Origin of code: POI.
030 *
031 */
032public class HexDump {
033
034    /**
035     * Instances should NOT be constructed in standard programming.
036     */
037    public HexDump() {
038        super();
039    }
040
041    /**
042     * Dump an array of bytes to an OutputStream. The output is formatted
043     * for human inspection, with a hexadecimal offset followed by the
044     * hexadecimal values of the next 16 bytes of data and the printable ASCII
045     * characters (if any) that those bytes represent printed per each line
046     * of output.
047     * <p>
048     * The offset argument specifies the start offset of the data array
049     * within a larger entity like a file or an incoming stream. For example,
050     * if the data array contains the third kibibyte of a file, then the
051     * offset argument should be set to 2048. The offset value printed
052     * at the beginning of each line indicates where in that larger entity
053     * the first byte on that line is located.
054     * <p>
055     * All bytes between the given index (inclusive) and the end of the
056     * data array are dumped.
057     *
058     * @param data  the byte array to be dumped
059     * @param offset  offset of the byte array within a larger entity
060     * @param stream  the OutputStream to which the data is to be
061     *               written
062     * @param index initial index into the byte array
063     *
064     * @throws IOException is thrown if anything goes wrong writing
065     *         the data to stream
066     * @throws ArrayIndexOutOfBoundsException if the index is
067     *         outside the data array's bounds
068     * @throws IllegalArgumentException if the output stream is null
069     */
070
071    public static void dump(final byte[] data, final long offset,
072                            final OutputStream stream, final int index)
073            throws IOException, ArrayIndexOutOfBoundsException,
074            IllegalArgumentException {
075
076        if (index < 0 || index >= data.length) {
077            throw new ArrayIndexOutOfBoundsException(
078                    "illegal index: " + index + " into array of length "
079                    + data.length);
080        }
081        if (stream == null) {
082            throw new IllegalArgumentException("cannot write to nullstream");
083        }
084        long display_offset = offset + index;
085        final StringBuilder buffer = new StringBuilder(74);
086
087        for (int j = index; j < data.length; j += 16) {
088            int chars_read = data.length - j;
089
090            if (chars_read > 16) {
091                chars_read = 16;
092            }
093            dump(buffer, display_offset).append(' ');
094            for (int k = 0; k < 16; k++) {
095                if (k < chars_read) {
096                    dump(buffer, data[k + j]);
097                } else {
098                    buffer.append("  ");
099                }
100                buffer.append(' ');
101            }
102            for (int k = 0; k < chars_read; k++) {
103                if (data[k + j] >= ' ' && data[k + j] < 127) {
104                    buffer.append((char) data[k + j]);
105                } else {
106                    buffer.append('.');
107                }
108            }
109            buffer.append(EOL);
110            // make explicit the dependency on the default encoding
111            stream.write(buffer.toString().getBytes(Charset.defaultCharset()));
112            stream.flush();
113            buffer.setLength(0);
114            display_offset += chars_read;
115        }
116    }
117
118    /**
119     * The line-separator (initializes to "line.separator" system property.
120     */
121    public static final String EOL =
122            System.getProperty("line.separator");
123    private static final char[] _hexcodes =
124            {
125                '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
126                'A', 'B', 'C', 'D', 'E', 'F'
127            };
128    private static final int[] _shifts =
129            {
130                28, 24, 20, 16, 12, 8, 4, 0
131            };
132
133    /**
134     * Dump a long value into a StringBuilder.
135     *
136     * @param _lbuffer the StringBuilder to dump the value in
137     * @param value  the long value to be dumped
138     * @return StringBuilder containing the dumped value.
139     */
140    private static StringBuilder dump(final StringBuilder _lbuffer, final long value) {
141        for (int j = 0; j < 8; j++) {
142            _lbuffer
143                    .append(_hexcodes[(int) (value >> _shifts[j]) & 15]);
144        }
145        return _lbuffer;
146    }
147
148    /**
149     * Dump a byte value into a StringBuilder.
150     *
151     * @param _cbuffer the StringBuilder to dump the value in
152     * @param value  the byte value to be dumped
153     * @return StringBuilder containing the dumped value.
154     */
155    private static StringBuilder dump(final StringBuilder _cbuffer, final byte value) {
156        for (int j = 0; j < 2; j++) {
157            _cbuffer.append(_hexcodes[value >> _shifts[j + 6] & 15]);
158        }
159        return _cbuffer;
160    }
161
162}