org.cpsolver.ifs.util

## Class ToolBox

- java.lang.Object
- - org.cpsolver.ifs.util.ToolBox

-     public class ToolBox
      extends Object

  Several auxiliary static methods.
  Version:
    IFS 1.3 (Iterative Forward Search)
    Copyright (C) 2006 - 2014 Tomáš Müller
    muller@unitime.org
    http://muller.unitime.org
    This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
    This library 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 Lesser General Public License for more details.
    You should have received a copy of the GNU Lesser General Public License along with this library; if not see http://www.gnu.org/licenses/.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ToolBox()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static long` | `binomial(int N, int K)` Compute number of K-tuples of N elements
    `static String` | `col2string(Collection<?> col, int tab)` Multiline representation of a collection
    `static void` | `configureLogging()` Configurates log4j loging
    `static String` | `configureLogging(String logDir, Properties properties)` Configure log4j logging
    `static String` | `configureLogging(String logDir, Properties properties, boolean timeInFileName)` Configure log4j logging
    `static String` | `configureLogging(String logDir, Properties properties, boolean timeInFileName, boolean includeSystemOuts)` Configure log4j logging
    `static <K,V> String` | `dict2string(Map<K,V> dict, int tab)` Multiline representation of a dictionary
    `static boolean` | `equals(Object o1, Object o2)`
    `static Random` | `getRandom()` Gets random number generator
    `static long` | `getSeed()` Gets current seed
    `static <E> List<E>` | `intersect(Collection<E> source1, Collection<E> source2)` Returns intersection of two collections
    `static DataProperties` | `loadProperties(File propertyFile)` Loads data properties.
    `static <E> void` | `merge(List<E> target, Collection<E> source)` Merge source with target
    `static <E> List<E>` | `permutation(List<E> items, int m, long id)` Generate given permutation
    `static <E> Enumeration<Collection<E>>` | `permutations(List<E> items, int m)` Generate a list of all permutations of size m of the given list
    `static double` | `random()` Generates random double number
    `static <E> E` | `random(Collection<E> set)` Returns random element from the given set of elements
    `static int` | `random(int limit)` Returns random number (int) from the set 0 .. limit - 1
    `static double` | `rms(int n, double x, double x2)` Root mean square
    `static <E> Set<E>` | `sample(List<E> items, int m)` Create random sample (m-tuple) of given list of elements
    `static <E> Enumeration<Collection<E>>` | `sample(List<E> items, int m, int count)` Generate a list of samples of the given list
    `static <E> Enumeration<Collection<E>>` | `sample(List<E> preferred, List<E> additional, int m, int count)` Generate a list of random samples combined of the given two lists
    `static void` | `setSeed(long seed)` Sets seeds for `getRandom()` and `random()` methods.
    `static <E> Collection<E>` | `subSet(Collection<E> set, double part)` Returns a randomly generated subset of the given set
    `static <E> Collection<E>` | `subSet(Collection<E> set, double part, int minSize)` Returns a randomly generated subset of the given set
    `static <E> List<E>` | `toList(E... obj)` Convert array of elements into a list
    `static String` | `trim(String s, int length)` Trim a string to have given length

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ToolBox

          public ToolBox()

  - ### Method Detail

    - #### random

          public static int random(int limit)

      Returns random number (int) from the set 0 .. limit - 1
      Parameters:
        `limit` - a limit
      Returns:
        a random number between 0 and limit - 1

    - #### random

          public static <E> E random(Collection<E> set)

      Returns random element from the given set of elements
      Type Parameters:
        `E` - some type
      Parameters:
        `set` - collection of objects
      Returns:
        randomly selected object

    - #### subSet

          public static <E> Collection<E> subSet(Collection<E> set,
                                                 double part)

      Returns a randomly generated subset of the given set
      Type Parameters:
        `E` - some type
      Parameters:
        `set` - set
        `part` - probability of selection of an element into the resultant subset
      Returns:
        randomly selected subset

    - #### subSet

          public static <E> Collection<E> subSet(Collection<E> set,
                                                 double part,
                                                 int minSize)

      Returns a randomly generated subset of the given set
      Type Parameters:
        `E` - some type
      Parameters:
        `set` - set
        `part` - probability of selection of an element into the resultant subset
        `minSize` - minimal size of the returned subset
      Returns:
        randomly selected subset

    - #### trim

          public static String trim(String s,
                                    int length)

      Trim a string to have given length
      Parameters:
        `s` - a string to trim
        `length` - a length to trim to
      Returns:
        trimmed and padded string of the given length

    - #### col2string

          public static String col2string(Collection<?> col,
                                          int tab)

      Multiline representation of a collection
      Parameters:
        `col` - a collection
        `tab` - tab size
      Returns:
        string representation

    - #### dict2string

          public static <K,V> String dict2string(Map<K,V> dict,
                                                 int tab)

      Multiline representation of a dictionary
      Type Parameters:
        `K` - a key class
        `V` - a value class
      Parameters:
        `dict` - a map
        `tab` - tab size
      Returns:
        string representation

    - #### rms

          public static double rms(int n,
                                   double x,
                                   double x2)

      Root mean square
      Parameters:
        `n` - number of tests
        `x` - total value of all tests
        `x2` - total value^2 of all tests
      Returns:
        root mean square

    - #### merge

          public static <E> void merge(List<E> target,
                                       Collection<E> source)

      Merge source with target
      Type Parameters:
        `E` - some object
      Parameters:
        `target` - target list
        `source` - source list

    - #### intersect

          public static <E> List<E> intersect(Collection<E> source1,
                                              Collection<E> source2)

      Returns intersection of two collections
      Type Parameters:
        `E` - some object
      Parameters:
        `source1` - first collection
        `source2` - second collection
      Returns:
        intersection

    - #### setSeed

          public static void setSeed(long seed)

      Sets seeds for `getRandom()` and `random()` methods.
      Parameters:
        `seed` - random seed

    - #### getSeed

          public static long getSeed()

      Gets current seed
      Returns:
        random seed

    - #### getRandom

          public static Random getRandom()

      Gets random number generator
      Returns:
        random number generator

    - #### random

          public static double random()

      Generates random double number
      Returns:
        random number

    - #### configureLogging

          public static void configureLogging()

      Configurates log4j loging

    - #### configureLogging

          public static String configureLogging(String logDir,
                                                Properties properties)

      Configure log4j logging
      Parameters:
        `logDir` - output folder
        `properties` - some other log4j properties
      Returns:
        name of the log file

    - #### configureLogging

          public static String configureLogging(String logDir,
                                                Properties properties,
                                                boolean timeInFileName)

      Configure log4j logging
      Parameters:
        `logDir` - output folder
        `properties` - some other log4j properties
        `timeInFileName` - if true log file is named debug_yyyy-MM-dd_(HH.mm.ss).log, it is named debug.log otherwise
      Returns:
        name of the log file

    - #### configureLogging

          public static String configureLogging(String logDir,
                                                Properties properties,
                                                boolean timeInFileName,
                                                boolean includeSystemOuts)

      Configure log4j logging
      Parameters:
        `logDir` - output folder
        `properties` - some other log4j properties
        `timeInFileName` - if true log file is named debug_yyyy-MM-dd_(HH.mm.ss).log, it is named debug.log otherwise
        `includeSystemOuts` - include system out and error in the log
      Returns:
        name of the log file

    - #### loadProperties

          public static DataProperties loadProperties(File propertyFile)

      Loads data properties. If there is INCLUDE property available, it is interpreted as semi-colon separated list of porperty files which should be also loaded (works recursively).
      Parameters:
        `propertyFile` - a file to read
      Returns:
        solver configuration

    - #### equals

          public static boolean equals(Object o1,
                                       Object o2)

    - #### toList

          public static <E> List<E> toList(E... obj)

      Convert array of elements into a list
      Parameters:
        `obj` - array of elements
      Returns:
        list of elements

    - #### binomial

          public static long binomial(int N,
                                      int K)

      Compute number of K-tuples of N elements
      Parameters:
        `N` - number of elements (e.g., number of room locations in a domain)
        `K` - size of a tuple (e.g., number of rooms a class needs)
      Returns:
        number of different K-tupples of N elements

    - #### sample

          public static <E> Set<E> sample(List<E> items,
                                          int m)

      Create random sample (m-tuple) of given list of elements
      Parameters:
        `items` - list of elements
        `m` - size of a tuple
      Returns:
        random subset of the list of size m

    - #### permutation

          public static <E> List<E> permutation(List<E> items,
                                                int m,
                                                long id)

      Generate given permutation
      Parameters:
        `items` - list of elements
        `m` - size of a tuple (permutation)
        `id` - position of the permutation in the list of all permutations of m-tuples of the given list of elements
      Returns:
        given subset of the list of size m

    - #### sample

          public static <E> Enumeration<Collection<E>> sample(List<E> items,
                                                              int m,
                                                              int count)

      Generate a list of samples of the given list
      Parameters:
        `items` - list of elements
        `m` - size of a sample
        `count` - number of samples
      Returns:
        list of samples (m-tuples) of the given items

    - #### permutations

          public static <E> Enumeration<Collection<E>> permutations(List<E> items,
                                                                    int m)

      Generate a list of all permutations of size m of the given list
      Parameters:
        `items` - list of elements
        `m` - size of a permutation
      Returns:
        list of all permutations (m-tuples) of the given items

    - #### sample

          public static <E> Enumeration<Collection<E>> sample(List<E> preferred,
                                                              List<E> additional,
                                                              int m,
                                                              int count)

      Generate a list of random samples combined of the given two lists
      Parameters:
        `preferred` - list of preferred elements
        `additional` - list of additional elements
        `m` - size of a sample
        `count` - number of samples
      Returns:
        list of samples of size m, preferring as many elements of the preferred list as possible