/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * <p>
 * Provides highly reusable static utility methods, chiefly concerned with
 * adding value to the {@link java.lang} classes. Most of these classes are
 * immutable and thus thread-safe. However
 * {@link org.apache.commons.lang3.CharSet} is not currently guaranteed
 * thread-safe under all circumstances.
 * </p>
 *
 * <p>
 * The top level package contains various Utils classes, whilst there are
 * various subpackages including {@link org.apache.commons.lang3.math},
 * {@link org.apache.commons.lang3.concurrent} and
 * {@link org.apache.commons.lang3.builder}. Using the Utils classes is
 * generally simplicity itself. They are the equivalent of global functions in
 * another language, a collection of stand-alone, thread-safe, static methods.
 * In contrast, subpackages may contain interfaces which may have to be
 * implemented or classes which may need to be extended to get the full
 * functionality from the code. They may, however, contain more global-like
 * functions.
 * </p>
 *
 * <p>
 * Lang 3.0 requires JDK 1.5+, since Lang 3.2 it requires JDK 6+; The legacy
 * release 2.6 requires JDK 1.2+. In both cases you can find features of later
 * JDKs being maintained by us and likely to be removed or modified in favour of
 * the JDK in the next major version. Note that Lang 3.0 uses a different
 * package than its predecessors, allowing it to be used at the same time as an
 * earlier version.
 * </p>
 *
 * <p>
 * You will find deprecated methods as you stroll through the Lang
 * documentation. These are removed in the next major version.
 * </p>
 *
 * <p>
 * All util classes contain empty public constructors with warnings not to use.
 * This may seem an odd thing to do, but it allows tools like Velocity to access
 * the class as if it were a bean. In other words, yes we know about private
 * constructors and have chosen not to use them.
 * </p>
 *
 * <h2>String manipulation - StringUtils, StringEscapeUtils,
 * RandomStringUtils</h2>
 *
 * <p>
 * Lang has a series of String utilities. The first is
 * {@link org.apache.commons.lang3.StringUtils}, oodles and oodles of functions
 * which tweak, transform, squeeze and cuddle {@link java.lang.String
 * java.lang.Strings}. In addition to StringUtils, there are a series of other
 * String manipulating classes;
 * {@link org.apache.commons.lang3.RandomStringUtils} and
 * {@link org.apache.commons.lang3.StringEscapeUtils StringEscapeUtils}.
 * RandomStringUtils speaks for itself. It's provides ways in which to generate
 * pieces of text, such as might be used for default passwords.
 * StringEscapeUtils contains methods to escape and unescape Java, JavaScript,
 * JSON, HTML and XML.
 * </p>
 *
 * <p>
 * These are ideal classes to start using if you're looking to get into Lang.
 * StringUtils' {@link org.apache.commons.lang3.StringUtils#capitalize(String)},
 * {@link org.apache.commons.lang3.StringUtils#substringBetween(String, String)}/{@link org.apache.commons.lang3.StringUtils#substringBefore(String, String)
 * Before}/{@link org.apache.commons.lang3.StringUtils#substringAfter(String, String)
 * After}, {@link org.apache.commons.lang3.StringUtils#split(String)} and
 * {@link org.apache.commons.lang3.StringUtils#join(Object[])} are good methods
 * to begin with.
 * </p>
 *
 * <h2>Character handling - CharSetUtils, CharSet, CharRange, CharUtils</h2>
 *
 * <p>
 * In addition to dealing with Strings, it's also important to deal with chars
 * and Characters. {@link org.apache.commons.lang3.CharUtils} exists for this
 * purpose, while {@link org.apache.commons.lang3.CharSetUtils} exists for
 * set-manipulation of Strings. Be careful, although CharSetUtils takes an
 * argument of type String, it is only as a set of characters. For example,
 * {@code CharSetUtils.delete("testtest", "tr")} will remove all t's and all r's
 * from the String, not just the String "tr".
 * </p>
 *
 * <p>
 * {@link org.apache.commons.lang3.CharRange} and
 * {@link org.apache.commons.lang3.CharSet} are both used internally by
 * CharSetUtils, and will probably rarely be used.
 * </p>
 *
 * <h2>JVM interaction - SystemUtils, CharEncoding</h2>
 *
 * <p>
 * SystemUtils is a simple little class which makes it easy to find out
 * information about which platform you are on. For some, this is a necessary
 * evil. It was never something I expected to use myself until I was trying to
 * ensure that Commons Lang itself compiled under JDK 1.2. Having pushed out a
 * few JDK 1.3 bits that had slipped in ({@code Collections.EMPTY_MAP} is a
 * classic offender), I then found that one of the Unit Tests was dying
 * mysteriously under JDK 1.2, but ran fine under JDK 1.3. There was no obvious
 * solution and I needed to move onwards, so the simple solution was to wrap
 * that particular test in a
 * <code>if (SystemUtils.isJavaVersionAtLeast(1.3f)) {</code>, make a note and
 * move on.
 * </p>
 *
 * <p>
 * The {@link org.apache.commons.lang3.CharEncoding} class is also used to
 * interact with the Java environment and may be used to see which character
 * encodings are supported in a particular environment.
 * </p>
 *
 * <h2>Serialization - SerializationUtils, SerializationException</h2>
 *
 * <p>
 * Serialization doesn't have to be that hard! A simple util class can take away
 * the pain, plus it provides a method to clone an object by unserializing and
 * reserializing, an old Java trick.
 * </p>
 *
 * <h3>Assorted functions - ObjectUtils, ClassUtils, ArrayUtils,
 * BooleanUtils</h3>
 *
 * <p>
 * Would you believe it, {@link org.apache.commons.lang3.ObjectUtils} contains
 * handy functions for Objects, mainly null-safe implementations of the methods
 * on {@link java.lang.Object}.
 * </p>
 *
 * <p>
 * {@link org.apache.commons.lang3.ClassUtils} is largely a set of helper
 * methods for reflection. Of special note are the comparators hidden away in
 * ClassUtils, useful for sorting Class and Package objects by name; however
 * they merely sort alphabetically and don't understand the common habit of
 * sorting {@code java} and {@code javax} first.
 * </p>
 *
 * <p>
 * Next up, {@link org.apache.commons.lang3.ArrayUtils}. This is a big one with
 * many methods and many overloads of these methods so it is probably worth an
 * in depth look here. Before we begin, assume that every method mentioned is
 * overloaded for all the primitives and for Object. Also, the short-hand 'xxx'
 * implies a generic primitive type, but usually also includes Object.
 * </p>
 *
 * <ul>
 * <li>ArrayUtils provides singleton empty arrays for all the basic types. These
 * will largely be of use in the Collections API with its toArray methods, but
 * also will be of use with methods which want to return an empty array on
 * error.</li>
 * <li>{@code add(xxx[], xxx)} will add a primitive type to an array, resizing
 * the array as you'd expect. Object is also supported.</li>
 * <li>{@code clone(xxx[])} clones a primitive or Object array.</li>
 * <li>{@code contains(xxx[], xxx)} searches for a primitive or Object in a
 * primitive or Object array.</li>
 * <li>{@code getLength(Object)} returns the length of any array or an
 * IllegalArgumentException if the parameter is not an array.
 * {@code hashCode(Object)}, {@code equals(Object, Object)},
 * {@code toString(Object)}</li>
 * <li>{@code indexOf(xxx[], xxx)} and {@code indexOf(xxx[], xxx, int)} are
 * copies of the classic String methods, but this time for primitive/Object
 * arrays. In addition, a lastIndexOf set of methods exists.</li>
 * <li>{@code isEmpty(xxx[])} lets you know if an array is zero-sized or null.
 * </li>
 * <li>{@code isSameLength(xxx[], xxx[])} returns true if the arrays are the
 * same length.</li>
 * <li>Along side the add methods, there are also remove methods of two types.
 * The first type remove the value at an index, {@code remove(xxx[], int)},
 * while the second type remove the first value from the array,
 * {@code remove(xxx[], xxx)}.</li>
 * <li>Nearing the end now. The {@code reverse(xxx[])} method turns an array
 * around.</li>
 * <li>The {@code subarray(xxx[], int, int)} method splices an array out of a
 * larger array.</li>
 * <li>Primitive to primitive wrapper conversion is handled by the
 * {@code toObject(xxx[])} and {@code toPrimitive(Xxx[])} methods.</li>
 * </ul>
 *
 * <p>
 * Lastly, {@link org.apache.commons.lang3.ArrayUtils#toMap(Object[])} is worthy
 * of special note. It is not a heavily overloaded method for working with
 * arrays, but a simple way to create Maps from literals.
 * </p>
 *
 * <h4>Using toMap</h4>
 * 
 * <pre>
 * <code>
 * Map colorMap = ArrayUtils.toMap(new String[][] {{
 *   {"RED", "#FF0000"},
 *   {"GREEN", "#00FF00"},
 *   {"BLUE", "#0000FF"}
 * });
 * </code>
 * </pre>
 *
 * <p>
 * Our final util class is {@link org.apache.commons.lang3.BooleanUtils}. It
 * contains various Boolean acting methods, probably of most interest is the
 * {@link org.apache.commons.lang3.BooleanUtils#toBoolean(String)} method which
 * turns various positive/negative Strings into a Boolean object, and not just
 * true/false as with Boolean.valueOf.
 * </p>
 *
 * <h2>Flotsam - BitField, Validate</h2>
 * <p>
 * On reaching the end of our package, we are left with a couple of classes that
 * haven't fit any of the topics so far.
 * </p>
 * <p>
 * The {@link org.apache.commons.lang3.BitField} class provides a wrapper class
 * around the classic bitmask integer, whilst the
 * {@link org.apache.commons.lang3.Validate} class may be used for assertions
 * (remember, we support Java 1.2).
 * </p>
 *
 * @since 1.0
 */
package org.apache.commons.lang3;