    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}