itextpdf-master/itext/src/main/java/com/itextpdf/text/Utilities.java
/*
 *
 * This file is part of the iText (R) project.
    Copyright (c) 1998-2022 iText Group NV
 * Authors: Bruno Lowagie, Paulo Soares, et al.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License version 3
 * as published by the Free Software Foundation with the addition of the
 * following permission added to Section 15 as permitted in Section 7(a):
 * FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
 * ITEXT GROUP. ITEXT GROUP DISCLAIMS THE WARRANTY OF NON INFRINGEMENT
 * OF THIRD PARTY RIGHTS
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Affero General Public License for more details.
 * You should have received a copy of the GNU Affero General Public License
 * along with this program; if not, see http://www.gnu.org/licenses or write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA, 02110-1301 USA, or download the license from the following URL:
 * http://itextpdf.com/terms-of-use/
 *
 * The interactive user interfaces in modified source and object code versions
 * of this program must display Appropriate Legal Notices, as required under
 * Section 5 of the GNU Affero General Public License.
 *
 * In accordance with Section 7(b) of the GNU Affero General Public License,
 * a covered work must retain the producer line in every PDF that is created
 * or manipulated using iText.
 *
 * You can be released from the requirements of the license by purchasing
 * a commercial license. Buying such a license is mandatory as soon as you
 * develop commercial activities involving the iText software without
 * disclosing the source code of your own applications.
 * These activities include: offering paid services to customers as an ASP,
 * serving PDFs on the fly in a web application, shipping iText with a closed
 * source product.
 *
 * For more information, please contact iText Software Corp. at this
 * address: sales@itextpdf.com
 */
package com.itextpdf.text;

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Collections;
import java.util.Hashtable;
import java.util.Properties;
import java.util.Set;

import com.itextpdf.text.pdf.ByteBuffer;
import com.itextpdf.text.pdf.PRTokeniser;
import com.itextpdf.text.pdf.PdfEncodings;

/**
 * A collection of convenience methods that were present in many different iText
 * classes.
 */

public class Utilities {

	/**
	 * Gets the keys of a Hashtable.
	 * Marked as deprecated, not used anywhere anymore.
	 * @param <K> type for the key
	 * @param <V> type for the value
	 * @param table
	 *            a Hashtable
	 * @return the keyset of a Hashtable (or an empty set if table is null)
	 */
	@Deprecated
	public static <K, V>  Set<K> getKeySet(final Hashtable<K, V> table) {
		return table == null ? Collections.<K>emptySet() : table.keySet();
	}

	/**
	 * Utility method to extend an array.
	 *
	 * @param original
	 *            the original array or <CODE>null</CODE>
	 * @param item
	 *            the item to be added to the array
	 * @return a new array with the item appended
	 */
	public static Object[][] addToArray(Object original[][], final Object item[]) {
		if (original == null) {
			original = new Object[1][];
			original[0] = item;
			return original;
		} else {
			Object original2[][] = new Object[original.length + 1][];
			System.arraycopy(original, 0, original2, 0, original.length);
			original2[original.length] = item;
			return original2;
		}
	}

	/**
	 * Checks for a true/false value of a key in a Properties object.
	 * @param attributes
	 * @param key
	 * @return a true/false value of a key in a Properties object
	 */
	public static boolean checkTrueOrFalse(final Properties attributes, final String key) {
		return "true".equalsIgnoreCase(attributes.getProperty(key));
	}

	/**
	 * Unescapes an URL. All the "%xx" are replaced by the 'xx' hex char value.
	 * @param src the url to unescape
	 * @return the unescaped value
	 */
	public static String unEscapeURL(final String src) {
	    StringBuffer bf = new StringBuffer();
	    char[] s = src.toCharArray();
	    for (int k = 0; k < s.length; ++k) {
	        char c = s[k];
	        if (c == '%') {
	            if (k + 2 >= s.length) {
	                bf.append(c);
	                continue;
	            }
	            int a0 = PRTokeniser.getHex(s[k + 1]);
	            int a1 = PRTokeniser.getHex(s[k + 2]);
	            if (a0 < 0 || a1 < 0) {
	                bf.append(c);
	                continue;
	            }
	            bf.append((char)(a0 * 16 + a1));
	            k += 2;
	        }
	        else
	            bf.append(c);
	    }
	    return bf.toString();
	}

	/**
	 * This method makes a valid URL from a given filename.
	 * <P>
	 * This method makes the conversion of this library from the JAVA 2 platform
	 * to a JDK1.1.x-version easier.
	 *
	 * @param filename
	 *            a given filename
	 * @return a valid URL
	 * @throws MalformedURLException
	 */
	public static URL toURL(final String filename) throws MalformedURLException {
        try {
            return new URL(filename);
        }
        catch (Exception e) {
            return new File(filename).toURI().toURL();
        }
	}

	/**
	 * This method is an alternative for the <CODE>InputStream.skip()</CODE>
	 * -method that doesn't seem to work properly for big values of <CODE>size
	 * </CODE>.
	 *
	 * @param is
	 *            the <CODE>InputStream</CODE>
	 * @param size
	 *            the number of bytes to skip
	 * @throws IOException
	 */
	static public void skip(final InputStream is, int size) throws IOException {
	    long n;
		while (size > 0) {
	        n = is.skip(size);
	        if (n <= 0)
	            break;
			size -= n;
		}
	}

	/**
	 * Measurement conversion from millimeters to points.
	 * @param	value	a value in millimeters
	 * @return	a value in points
	 * @since	2.1.2
	 */
	public static final float millimetersToPoints(final float value) {
	    return inchesToPoints(millimetersToInches(value));
	}

	/**
	 * Measurement conversion from millimeters to inches.
	 * @param	value	a value in millimeters
	 * @return	a value in inches
	 * @since	2.1.2
	 */
	public static final float millimetersToInches(final float value) {
	    return value / 25.4f;
	}

	/**
	 * Measurement conversion from points to millimeters.
	 * @param	value	a value in points
	 * @return	a value in millimeters
	 * @since	2.1.2
	 */
	public static final float pointsToMillimeters(final float value) {
	    return inchesToMillimeters(pointsToInches(value));
	}

	/**
	 * Measurement conversion from points to inches.
	 * @param	value	a value in points
	 * @return	a value in inches
	 * @since	2.1.2
	 */
	public static final float pointsToInches(final float value) {
	    return value / 72f;
	}

	/**
	 * Measurement conversion from inches to millimeters.
	 * @param	value	a value in inches
	 * @return	a value in millimeters
	 * @since	2.1.2
	 */
	public static final float inchesToMillimeters(final float value) {
	    return value * 25.4f;
	}

	/**
	 * Measurement conversion from inches to points.
	 * @param	value	a value in inches
	 * @return	a value in points
	 * @since	2.1.2
	 */
	public static final float inchesToPoints(final float value) {
	    return value * 72f;
	}

    /**
     * Check if the value of a character belongs to a certain interval
     * that indicates it's the higher part of a surrogate pair.
     * @param c	the character
     * @return	true if the character belongs to the interval
     * @since	2.1.2
     */
    public static boolean isSurrogateHigh(final char c) {
        return c >= '\ud800' && c <= '\udbff';
    }

    /**
     * Check if the value of a character belongs to a certain interval
     * that indicates it's the lower part of a surrogate pair.
     * @param c	the character
     * @return	true if the character belongs to the interval
     * @since	2.1.2
     */
    public static boolean isSurrogateLow(final char c) {
        return c >= '\udc00' && c <= '\udfff';
    }

    /**
     * Checks if two subsequent characters in a String are
     * are the higher and the lower character in a surrogate
     * pair (and therefore eligible for conversion to a UTF 32 character).
     * @param text	the String with the high and low surrogate characters
     * @param idx	the index of the 'high' character in the pair
     * @return	true if the characters are surrogate pairs
     * @since	2.1.2
     */
    public static boolean isSurrogatePair(final String text, final int idx) {
        if (idx < 0 || idx > text.length() - 2)
            return false;
        return isSurrogateHigh(text.charAt(idx)) && isSurrogateLow(text.charAt(idx + 1));
    }

    /**
     * Checks if two subsequent characters in a character array are
     * are the higher and the lower character in a surrogate
     * pair (and therefore eligible for conversion to a UTF 32 character).
     * @param text	the character array with the high and low surrogate characters
     * @param idx	the index of the 'high' character in the pair
     * @return	true if the characters are surrogate pairs
     * @since	2.1.2
     */
    public static boolean isSurrogatePair(final char[] text, final int idx) {
        if (idx < 0 || idx > text.length - 2)
            return false;
        return isSurrogateHigh(text[idx]) && isSurrogateLow(text[idx + 1]);
    }

    /**
     * Returns the code point of a UTF32 character corresponding with
     * a high and a low surrogate value.
     * @param highSurrogate	the high surrogate value
     * @param lowSurrogate	the low surrogate value
     * @return	a code point value
     * @since	2.1.2
     */
    public static int convertToUtf32(final char highSurrogate, final char lowSurrogate) {
         return (highSurrogate - 0xd800) * 0x400 + lowSurrogate - 0xdc00 + 0x10000;
    }

    /**
     * Converts a unicode character in a character array to a UTF 32 code point value.
     * @param text	a character array that has the unicode character(s)
     * @param idx	the index of the 'high' character
     * @return	the code point value
     * @since	2.1.2
     */
    public static int convertToUtf32(final char[] text, final int idx) {
         return (text[idx] - 0xd800) * 0x400 + text[idx + 1] - 0xdc00 + 0x10000;
    }

    /**
     * Converts a unicode character in a String to a UTF32 code point value
     * @param text	a String that has the unicode character(s)
     * @param idx	the index of the 'high' character
     * @return	the codepoint value
     * @since	2.1.2
     */
    public static int convertToUtf32(final String text, final int idx) {
         return (text.charAt(idx) - 0xd800) * 0x400 + text.charAt(idx + 1) - 0xdc00 + 0x10000;
    }

    /**
     * Converts a UTF32 code point value to a String with the corresponding character(s).
     * @param codePoint	a Unicode value
     * @return	the corresponding characters in a String
     * @since	2.1.2
     */
    public static String convertFromUtf32(int codePoint) {
        if (codePoint < 0x10000)
            return Character.toString((char)codePoint);
        codePoint -= 0x10000;
        return new String(new char[]{(char)(codePoint / 0x400 + 0xd800), (char)(codePoint % 0x400 + 0xdc00)});
    }

    /**
     * Reads the contents of a file to a String.
     * @param	path	the path to the file
     * @return	a String with the contents of the file
     * @throws IOException
     * @since	iText 5.0.0
     */
	public static String readFileToString(final String path) throws IOException {
		return readFileToString(new File(path));
	}

    /**
     * Reads the contents of a file to a String.
     * @param	file	a file
     * @return	a String with the contents of the file
     * @throws IOException if file was not found or could not be read.
     * @since	iText 5.0.0
     */
	public static String readFileToString(final File file) throws IOException {
		byte[] jsBytes = new byte[(int) file.length()];
	    FileInputStream f = new FileInputStream(file);
	    f.read(jsBytes);
	    return new String(jsBytes);
	}

	/**
	 * Converts an array of bytes to a String of hexadecimal values
	 * @param bytes	a byte array
	 * @return	the same bytes expressed as hexadecimal values
	 */
	public static String convertToHex(byte[] bytes) {
	    ByteBuffer buf = new ByteBuffer();
	    for (byte b : bytes) {
	        buf.appendHex(b);
	    }
	    return PdfEncodings.convertToString(buf.toByteArray(), null).toUpperCase();
	}

	/**
	 * Copies the specified range of the specified array into a new array.
	 * The initial index of the range (<tt>from</tt>) must lie between zero
	 * and <tt>original.length</tt>, inclusive.  The value at
	 * <tt>original[from]</tt> is placed into the initial element of the copy
	 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
	 * Values from subsequent elements in the original array are placed into
	 * subsequent elements in the copy.  The final index of the range
	 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
	 * may be greater than <tt>original.length</tt>, in which case
	 * <tt>'\\u000'</tt> is placed in all elements of the copy whose index is
	 * greater than or equal to <tt>original.length - from</tt>.  The length
	 * of the returned array will be <tt>to - from</tt>.
	 *
	 * @param original the array from which a range is to be copied
	 * @param from the initial index of the range to be copied, inclusive
	 * @param to the final index of the range to be copied, exclusive.
	 *     (This index may lie outside the array.)
	 * @return a new array containing the specified range from the original array,
	 *     truncated or padded with null characters to obtain the required length
	 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
	 *     or {@code from > original.length}
	 * @throws IllegalArgumentException if <tt>from &gt; to</tt>
	 * @throws NullPointerException if <tt>original</tt> is null
	 * @since 1.6
	 */
	public static char[] copyOfRange(char[] original, int from, int to) {
		int newLength = to - from;
		if (newLength < 0)
			throw new IllegalArgumentException(from + " > " + to);
		char[] copy = new char[newLength];
		System.arraycopy(original, from, copy, 0,
				Math.min(original.length - from, newLength));
		return copy;
	}

}
