loci.common.DataTools Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ome-common Show documentation
Contains common I/O, date parsing, and XML processing classes.
The newest version!
/*
 * #%L
 * Common package for I/O and related utilities
 * %%
 * Copyright (C) 2005 - 2016 Open Microscopy Environment:
 *   - Board of Regents of the University of Wisconsin-Madison
 *   - Glencoe Software, Inc.
 *   - University of Dundee
 * %%
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 * #L%
 */

package loci.common;

import java.io.File;
import java.io.IOException;
import java.text.DecimalFormatSymbols;
import java.text.NumberFormat;
import java.text.DecimalFormat;
import java.text.ParseException;
import java.util.Locale;

import org.slf4j.LoggerFactory;
import org.slf4j.Logger;

/**
 * A utility class with convenience methods for
 * reading, writing and decoding words.
 *
 * @author Curtis Rueden ctrueden at wisc.edu
 * @author Chris Allan callan at blackcat.ca
 * @author Melissa Linkert melissa at glencoesoftware.com
 */
public final class DataTools {

  // -- Constants --

  // -- Static fields --
  private static final Logger LOGGER = LoggerFactory.getLogger(DataTools.class);

  private static final ThreadLocal nf =
      new ThreadLocal() {
        @Override protected NumberFormat initialValue() {
            return DecimalFormat.getInstance(Locale.ENGLISH);
        }
    };
  // -- Constructor --

  private DataTools() { }

  /**
   * Reads the contents of the given file into a string.
   *
   * @param id name of the file to read
   *           this can be any name supported by Location,
   *           not necessarily a file on disk
   * @return the complete contents of the specified file
   * @throws IOException if the file cannot be read or is larger than 2GB
   * @see Location#getMappedId(String)
   */
  public static String readFile(String id) throws IOException {
    RandomAccessInputStream in = new RandomAccessInputStream(id);
    long idLen = in.length();
    if (idLen > Integer.MAX_VALUE) {
      throw new IOException("File too large");
    }
    int len = (int) idLen;
    byte[] b = new byte[len];
    in.readFully(b);
    in.close();
    String data = new String(b, Constants.ENCODING);
    b = null;
    return data;
  }

  // -- Word decoding - bytes to primitive types --

  /**
   * Translates up to the first len bytes of a byte array beyond the given
   * offset to a short. If there are fewer than len bytes available,
   * the MSBs are all assumed to be zero (regardless of endianness).
   *
   * @param bytes array of bytes to use for translation
   * @param off offset to the first byte in the array
   * @param len number of bytes to use
   * @param little true if the bytes are provided in little-endian order
   * @return the short value that results from concatenating the specified bytes
   */
  public static short bytesToShort(byte[] bytes, int off, int len,
    boolean little)
  {
    if (bytes.length - off < len) len = bytes.length - off;
    short total = 0;
    for (int i=0, ndx=off; i2 * b.length representing the
   *         hexadecimal digits of each byte in b concatenated
   */
  public static String bytesToHex(byte[] b) {
    StringBuffer sb = new StringBuffer();
    for (int i=0; i2 * values.length
   */
  public static byte[] shortsToBytes(short[] values, boolean little) {
    byte[] v = new byte[values.length * 2];
    for (int i=0; i4 * values.length
   */
  public static byte[] intsToBytes(int[] values, boolean little) {
    byte[] v = new byte[values.length * 4];
    for (int i=0; i4 * values.length
   */
  public static byte[] floatsToBytes(float[] values, boolean little) {
    byte[] v = new byte[values.length * 4];
    for (int i=0; i8 * values.length
   */
  public static byte[] longsToBytes(long[] values, boolean little) {
    byte[] v = new byte[values.length * 8];
    for (int i=0; i8 * values.length
   */
  public static byte[] doublesToBytes(double[] values, boolean little) {
    byte[] v = new byte[values.length * 8];
    for (int i=0; i Integer.MAX_VALUE) {
        throw new IllegalArgumentException("Array size too large: " +
          sizeAsProduct(sizes));
      }
    }
    // NB: The downcast to int is safe here, due to the checks above.
    return (int) total;
  }

  /**
   * Checks that the product of the given sizes does not exceed the 64-bit
   * integer limit (i.e., {@link Long#MAX_VALUE}).
   * 
   * @param sizes list of sizes from which to compute the product
   * @return the product of the given sizes
   * @throws IllegalArgumentException if the total size exceeds 8EiB, which is
   *           the maximum size of a long in Java; or if any size argument is
   *           zero or negative
   */
  public static long safeMultiply64(long... sizes)
    throws IllegalArgumentException
  {
    if (sizes.length == 0) return 0;
    long total = 1;
    for (long size : sizes) {
      if (size < 1) {
        throw new IllegalArgumentException("Invalid array size: " +
          sizeAsProduct(sizes));
      }
      if (willOverflow(total, size)) {
        throw new IllegalArgumentException("Array size too large: " +
          sizeAsProduct(sizes));
      }
      total *= size;
    }
    return total;
  }

  /**
   * Returns true if the given value is contained in the given array.
   *
   * @param array an array of ints to search
   * @param value the int for which to search
   * @return true if array contains at least one occurence of
   *         value
   * @see #indexOf(int[], int)
   */
  public static boolean containsValue(int[] array, int value) {
    return indexOf(array, value) != -1;
  }

  /**
   * Returns the index of the first occurrence of the given value in the given
   * array. If the value is not in the array, returns -1.
   *
   * @param array an array of ints to search
   * @param value the int for which to search
   * @return the index of the first occurence of value in
   *         array, or -1 if value is not found
   */
  public static int indexOf(int[] array, int value) {
    for (int i=0; ivalue in
   *         array, or -1 if value is not found
   */
  public static int indexOf(Object[] array, Object value) {
    for (int i=0; i