/*
 * 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.
 */
package org.apache.commons.lang3.builder;

import org.apache.commons.lang3.ObjectUtils;
import org.apache.commons.lang3.Validate;

Assists in implementing Object.toString() methods.
This class enables a good and consistent toString() to be built for any
class or object. This class aims to simplify the process by:

 
allowing field names
 
handling all types consistently
 
handling nulls consistently
 
outputting arrays and multi-dimensional arrays
 
enabling the detail level to be controlled for Objects and Collections
 
handling class hierarchies

To use this class write code as follows:
public class Person {
  String name;
  int age;
  boolean smoker;
  ...
  public String toString() {
    return new ToStringBuilder(this).
      append("name", name).
      append("age", age).
      append("smoker", smoker).
      toString();
  }
}

This will produce a toString of the format:
Person@7f54[name=Stephen,age=29,smoker=false]
To add the superclass toString, use appendSuper. To append the toString from an object that is delegated to (or any other object), use appendToString.
Alternatively, there is a method that uses reflection to determine
the fields to test. Because these fields are usually private, the method,
reflectionToString, uses AccessibleObject.setAccessible to
change the visibility of the fields. This will fail under a security manager,
unless the appropriate permissions are set up correctly. It is also
slower than testing explicitly.
A typical invocation for this method would look like:
public String toString() {
  return ToStringBuilder.reflectionToString(this);
}

You can also use the builder to debug 3rd party objects:
System.out.println("An object: " + ToStringBuilder.reflectionToString(anObject));

The exact format of the toString is determined by the ToStringStyle passed into the constructor.
Since:
1.0/**
 * <p>Assists in implementing {@link Object#toString()} methods.</p>
 *
 * <p>This class enables a good and consistent <code>toString()</code> to be built for any
 * class or object. This class aims to simplify the process by:</p>
 * <ul>
 *  <li>allowing field names</li>
 *  <li>handling all types consistently</li>
 *  <li>handling nulls consistently</li>
 *  <li>outputting arrays and multi-dimensional arrays</li>
 *  <li>enabling the detail level to be controlled for Objects and Collections</li>
 *  <li>handling class hierarchies</li>
 * </ul>
 *
 * <p>To use this class write code as follows:</p>
 *
 * <pre>
 * public class Person {
 *   String name;
 *   int age;
 *   boolean smoker;
 *
 *   ...
 *
 *   public String toString() {
 *     return new ToStringBuilder(this).
 *       append("name", name).
 *       append("age", age).
 *       append("smoker", smoker).
 *       toString();
 *   }
 * }
 * </pre>
 *
 * <p>This will produce a toString of the format:
 * <code>Person@7f54[name=Stephen,age=29,smoker=false]</code></p>
 *
 * <p>To add the superclass <code>toString</code>, use {@link #appendSuper}.
 * To append the <code>toString</code> from an object that is delegated
 * to (or any other object), use {@link #appendToString}.</p>
 *
 * <p>Alternatively, there is a method that uses reflection to determine
 * the fields to test. Because these fields are usually private, the method,
 * <code>reflectionToString</code>, uses <code>AccessibleObject.setAccessible</code> to
 * change the visibility of the fields. This will fail under a security manager,
 * unless the appropriate permissions are set up correctly. It is also
 * slower than testing explicitly.</p>
 *
 * <p>A typical invocation for this method would look like:</p>
 *
 * <pre>
 * public String toString() {
 *   return ToStringBuilder.reflectionToString(this);
 * }
 * </pre>
 *
 * <p>You can also use the builder to debug 3rd party objects:</p>
 *
 * <pre>
 * System.out.println("An object: " + ToStringBuilder.reflectionToString(anObject));
 * </pre>
 *
 * <p>The exact format of the <code>toString</code> is determined by
 * the {@link ToStringStyle} passed into the constructor.</p>
 *
 * @since 1.0
 */
public class ToStringBuilder implements Builder<String> {

    
The default style of output to use, not null.
/**
     * The default style of output to use, not null.
     */
    private static volatile ToStringStyle defaultStyle = ToStringStyle.DEFAULT_STYLE;

    //----------------------------------------------------------------------------

    
Gets the default ToStringStyle to use.
This method gets a singleton default value, typically for the whole JVM.
Changing this default should generally only be done during application startup.
It is recommended to pass a ToStringStyle to the constructor instead
of using this global default.
This method can be used from multiple threads.
Internally, a volatile variable is used to provide the guarantee that the latest value set using setDefaultStyle is the value returned. It is strongly recommended that the default style is only changed during application startup.
One reason for changing the default could be to have a verbose style during
development and a compact style in production.
Returns:
the default ToStringStyle, never null/**
     * <p>Gets the default <code>ToStringStyle</code> to use.</p>
     *
     * <p>This method gets a singleton default value, typically for the whole JVM.
     * Changing this default should generally only be done during application startup.
     * It is recommended to pass a <code>ToStringStyle</code> to the constructor instead
     * of using this global default.</p>
     *
     * <p>This method can be used from multiple threads.
     * Internally, a <code>volatile</code> variable is used to provide the guarantee
     * that the latest value set using {@link #setDefaultStyle} is the value returned.
     * It is strongly recommended that the default style is only changed during application startup.</p>
     *
     * <p>One reason for changing the default could be to have a verbose style during
     * development and a compact style in production.</p>
     *
     * @return the default <code>ToStringStyle</code>, never null
     */
    public static ToStringStyle getDefaultStyle() {
        return defaultStyle;
    }

    
Sets the default ToStringStyle to use.
This method sets a singleton default value, typically for the whole JVM.
Changing this default should generally only be done during application startup.
It is recommended to pass a ToStringStyle to the constructor instead
of changing this global default.
This method is not intended for use from multiple threads.
Internally, a volatile variable is used to provide the guarantee that the latest value set is the value returned from getDefaultStyle.
Params:
style –  the default ToStringStyle
Throws:
IllegalArgumentException – if the style is null/**
     * <p>Sets the default <code>ToStringStyle</code> to use.</p>
     *
     * <p>This method sets a singleton default value, typically for the whole JVM.
     * Changing this default should generally only be done during application startup.
     * It is recommended to pass a <code>ToStringStyle</code> to the constructor instead
     * of changing this global default.</p>
     *
     * <p>This method is not intended for use from multiple threads.
     * Internally, a <code>volatile</code> variable is used to provide the guarantee
     * that the latest value set is the value returned from {@link #getDefaultStyle}.</p>
     *
     * @param style  the default <code>ToStringStyle</code>
     * @throws IllegalArgumentException if the style is <code>null</code>
     */
    public static void setDefaultStyle(final ToStringStyle style) {
        Validate.isTrue(style != null, "The style must not be null");
        defaultStyle = style;
    }

    //----------------------------------------------------------------------------
    
Uses ReflectionToStringBuilder to generate a
toString for the specified object.
Params:
object –  the Object to be output
See Also:
ReflectionToStringBuilder.toString(Object)
Returns:
the String result/**
     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
     * <code>toString</code> for the specified object.</p>
     *
     * @param object  the Object to be output
     * @return the String result
     * @see ReflectionToStringBuilder#toString(Object)
     */
    public static String reflectionToString(final Object object) {
        return ReflectionToStringBuilder.toString(object);
    }

    
Uses ReflectionToStringBuilder to generate a
toString for the specified object.
Params:
object –  the Object to be output
style –  the style of the toString to create, may be null
See Also:
ReflectionToStringBuilder.toString(Object, ToStringStyle)
Returns:
the String result/**
     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
     * <code>toString</code> for the specified object.</p>
     *
     * @param object  the Object to be output
     * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
     * @return the String result
     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle)
     */
    public static String reflectionToString(final Object object, final ToStringStyle style) {
        return ReflectionToStringBuilder.toString(object, style);
    }

    
Uses ReflectionToStringBuilder to generate a
toString for the specified object.
Params:
object –  the Object to be output
style –  the style of the toString to create, may be null
outputTransients –  whether to include transient fields
See Also:
ReflectionToStringBuilder.toString(Object, ToStringStyle, boolean)
Returns:
the String result/**
     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
     * <code>toString</code> for the specified object.</p>
     *
     * @param object  the Object to be output
     * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
     * @param outputTransients  whether to include transient fields
     * @return the String result
     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean)
     */
    public static String reflectionToString(final Object object, final ToStringStyle style, final boolean outputTransients) {
        return ReflectionToStringBuilder.toString(object, style, outputTransients, false, null);
    }

    
Uses ReflectionToStringBuilder to generate a
toString for the specified object.
Params:
object –  the Object to be output
style –  the style of the toString to create, may be null
outputTransients –  whether to include transient fields
reflectUpToClass –  the superclass to reflect up to (inclusive), may be null
Type parameters:
<T> – the type of the object
See Also:
ReflectionToStringBuilder.toString(Object, ToStringStyle, boolean, boolean, Class<? super Object>)
Returns:
the String result
Since:
2.0/**
     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
     * <code>toString</code> for the specified object.</p>
     *
     * @param <T> the type of the object
     * @param object  the Object to be output
     * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
     * @param outputTransients  whether to include transient fields
     * @param reflectUpToClass  the superclass to reflect up to (inclusive), may be <code>null</code>
     * @return the String result
     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean,boolean,Class)
     * @since 2.0
     */
    public static <T> String reflectionToString(
        final T object,
        final ToStringStyle style,
        final boolean outputTransients,
        final Class<? super T> reflectUpToClass) {
        return ReflectionToStringBuilder.toString(object, style, outputTransients, false, reflectUpToClass);
    }

    //----------------------------------------------------------------------------

    
Current toString buffer, not null.
/**
     * Current toString buffer, not null.
     */
    private final StringBuffer buffer;
    
The object being output, may be null.
/**
     * The object being output, may be null.
     */
    private final Object object;
    
The style of output to use, not null.
/**
     * The style of output to use, not null.
     */
    private final ToStringStyle style;

    
Constructs a builder for the specified object using the default output style.
This default style is obtained from getDefaultStyle().
Params:
object –  the Object to build a toString for, not recommended to be null/**
     * <p>Constructs a builder for the specified object using the default output style.</p>
     *
     * <p>This default style is obtained from {@link #getDefaultStyle()}.</p>
     *
     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
     */
    public ToStringBuilder(final Object object) {
        this(object, null, null);
    }

    
Constructs a builder for the specified object using the defined output style.
If the style is null, the default style is used.
Params:
object –  the Object to build a toString for, not recommended to be null
style –  the style of the toString to create, null uses the default style/**
     * <p>Constructs a builder for the specified object using the defined output style.</p>
     *
     * <p>If the style is <code>null</code>, the default style is used.</p>
     *
     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
     * @param style  the style of the <code>toString</code> to create, null uses the default style
     */
    public ToStringBuilder(final Object object, final ToStringStyle style) {
        this(object, style, null);
    }

    
Constructs a builder for the specified object.
If the style is null, the default style is used.
If the buffer is null, a new one is created.
Params:
object –  the Object to build a toString for, not recommended to be null
style –  the style of the toString to create, null uses the default style
buffer –  the StringBuffer to populate, may be null/**
     * <p>Constructs a builder for the specified object.</p>
     *
     * <p>If the style is <code>null</code>, the default style is used.</p>
     *
     * <p>If the buffer is <code>null</code>, a new one is created.</p>
     *
     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
     * @param style  the style of the <code>toString</code> to create, null uses the default style
     * @param buffer  the <code>StringBuffer</code> to populate, may be null
     */
    public ToStringBuilder(final Object object, ToStringStyle style, StringBuffer buffer) {
        if (style == null) {
            style = getDefaultStyle();
        }
        if (buffer == null) {
            buffer = new StringBuffer(512);
        }
        this.buffer = buffer;
        this.style = style;
        this.object = object;

        style.appendStart(buffer, object);
    }

    //----------------------------------------------------------------------------

    
Append to the toString a boolean
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>boolean</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final boolean value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a boolean
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>boolean</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final boolean[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a byte
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>byte</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final byte value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a byte
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>byte</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final byte[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a char
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>char</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final char value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a char
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>char</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final char[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a double
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>double</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final double value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a double
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>double</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final double[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a float
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>float</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final float value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a float
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>float</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final float[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString an int
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>int</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final int value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString an int
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>int</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final int[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a long
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>long</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final long value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a long
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>long</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final long[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString an Object
value.
Params:
obj –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>Object</code>
     * value.</p>
     *
     * @param obj  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final Object obj) {
        style.append(buffer, null, obj, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString an Object
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>Object</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final Object[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a short
value.
Params:
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>short</code>
     * value.</p>
     *
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final short value) {
        style.append(buffer, null, value);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append to the toString a short
array.
Params:
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>short</code>
     * array.</p>
     *
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final short[] array) {
        style.append(buffer, null, array, null);
        return this;
    }

    
Append to the toString a boolean
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>boolean</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final boolean value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a boolean
array.
Params:
fieldName –  the field name
array –  the array to add to the hashCode
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>boolean</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>hashCode</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final boolean[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a boolean
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>boolean</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final boolean[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString an byte
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>byte</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final byte value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a byte array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>byte</code> array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final byte[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a byte
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>byte</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final byte[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString a char
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>char</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final char value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a char
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>char</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final char[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a char
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>char</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final char[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString a double
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>double</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final double value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a double
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>double</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final double[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a double
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>double</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final double[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString an float
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>float</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final float value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a float
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>float</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final float[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a float
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>float</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final float[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString an int
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>int</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final int value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString an int
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>int</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final int[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString an int
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>int</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final int[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString a long
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>long</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final long value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a long
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>long</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final long[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a long
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>long</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final long[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString an Object
value.
Params:
fieldName –  the field name
obj –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>Object</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param obj  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final Object obj) {
        style.append(buffer, fieldName, obj, null);
        return this;
    }

    
Append to the toString an Object
value.
Params:
fieldName –  the field name
obj –  the value to add to the toString
fullDetail –  true for detail,
 false for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>Object</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param obj  the value to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail,
     *  <code>false</code> for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final Object obj, final boolean fullDetail) {
        style.append(buffer, fieldName, obj, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString an Object
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>Object</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final Object[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString an Object
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>Object</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final Object[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Append to the toString an short
value.
Params:
fieldName –  the field name
value –  the value to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> an <code>short</code>
     * value.</p>
     *
     * @param fieldName  the field name
     * @param value  the value to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final short value) {
        style.append(buffer, fieldName, value);
        return this;
    }

    
Append to the toString a short
array.
Params:
fieldName –  the field name
array –  the array to add to the toString
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>short</code>
     * array.</p>
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final short[] array) {
        style.append(buffer, fieldName, array, null);
        return this;
    }

    
Append to the toString a short
array.
A boolean parameter controls the level of detail to show.
Setting true will output the array in full. Setting
false will output a summary, typically the size of
the array.
Params:
fieldName –  the field name
array –  the array to add to the toString
fullDetail –  true for detail, false
 for summary info
Returns:
this/**
     * <p>Append to the <code>toString</code> a <code>short</code>
     * array.</p>
     *
     * <p>A boolean parameter controls the level of detail to show.
     * Setting <code>true</code> will output the array in full. Setting
     * <code>false</code> will output a summary, typically the size of
     * the array.
     *
     * @param fieldName  the field name
     * @param array  the array to add to the <code>toString</code>
     * @param fullDetail  <code>true</code> for detail, <code>false</code>
     *  for summary info
     * @return this
     */
    public ToStringBuilder append(final String fieldName, final short[] array, final boolean fullDetail) {
        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
        return this;
    }

    
Appends with the same format as the default Object toString()
 method. Appends the class name followed by System.identityHashCode(Object).
Params:
srcObject –  the Object whose class name and id to output
Returns:
this
Since:
2.0/**
     * <p>Appends with the same format as the default <code>Object toString()
     * </code> method. Appends the class name followed by
     * {@link System#identityHashCode(java.lang.Object)}.</p>
     *
     * @param srcObject  the <code>Object</code> whose class name and id to output
     * @return this
     * @since 2.0
     */
    public ToStringBuilder appendAsObjectToString(final Object srcObject) {
        ObjectUtils.identityToString(this.getStringBuffer(), srcObject);
        return this;
    }

    //----------------------------------------------------------------------------

    
Append the toString from the superclass.
This method assumes that the superclass uses the same ToStringStyle
as this one.
If superToString is null, no change is made.
Params:
superToString –  the result of super.toString()
Returns:
this
Since:
2.0/**
     * <p>Append the <code>toString</code> from the superclass.</p>
     *
     * <p>This method assumes that the superclass uses the same <code>ToStringStyle</code>
     * as this one.</p>
     *
     * <p>If <code>superToString</code> is <code>null</code>, no change is made.</p>
     *
     * @param superToString  the result of <code>super.toString()</code>
     * @return this
     * @since 2.0
     */
    public ToStringBuilder appendSuper(final String superToString) {
        if (superToString != null) {
            style.appendSuper(buffer, superToString);
        }
        return this;
    }

    
Append the toString from another object.
This method is useful where a class delegates most of the implementation of
its properties to another class. You can then call toString() on
the other class and pass the result into this method.
  private AnotherObject delegate;
  private String fieldInThisClass;
  public String toString() {
    return new ToStringBuilder(this).
      appendToString(delegate.toString()).
      append(fieldInThisClass).
      toString();
  }
This method assumes that the other object uses the same ToStringStyle
as this one.
If the toString is null, no change is made.
Params:
toString –  the result of toString() on another object
Returns:
this
Since:
2.0/**
     * <p>Append the <code>toString</code> from another object.</p>
     *
     * <p>This method is useful where a class delegates most of the implementation of
     * its properties to another class. You can then call <code>toString()</code> on
     * the other class and pass the result into this method.</p>
     *
     * <pre>
     *   private AnotherObject delegate;
     *   private String fieldInThisClass;
     *
     *   public String toString() {
     *     return new ToStringBuilder(this).
     *       appendToString(delegate.toString()).
     *       append(fieldInThisClass).
     *       toString();
     *   }</pre>
     *
     * <p>This method assumes that the other object uses the same <code>ToStringStyle</code>
     * as this one.</p>
     *
     * <p>If the <code>toString</code> is <code>null</code>, no change is made.</p>
     *
     * @param toString  the result of <code>toString()</code> on another object
     * @return this
     * @since 2.0
     */
    public ToStringBuilder appendToString(final String toString) {
        if (toString != null) {
            style.appendToString(buffer, toString);
        }
        return this;
    }

    
Returns the Object being output.
Returns:
The object being output.
Since:
2.0/**
     * <p>Returns the <code>Object</code> being output.</p>
     *
     * @return The object being output.
     * @since 2.0
     */
    public Object getObject() {
        return object;
    }

    
Gets the StringBuffer being populated.
Returns:
the StringBuffer being populated/**
     * <p>Gets the <code>StringBuffer</code> being populated.</p>
     *
     * @return the <code>StringBuffer</code> being populated
     */
    public StringBuffer getStringBuffer() {
        return buffer;
    }

    //----------------------------------------------------------------------------

    
Gets the ToStringStyle being used.
Returns:
the ToStringStyle being used
Since:
2.0/**
     * <p>Gets the <code>ToStringStyle</code> being used.</p>
     *
     * @return the <code>ToStringStyle</code> being used
     * @since 2.0
     */
    public ToStringStyle getStyle() {
        return style;
    }

    
Returns the built toString.
This method appends the end of data indicator, and can only be called once. Use getStringBuffer to get the current string state.
If the object is null, return the style's nullText
Returns:
the String toString/**
     * <p>Returns the built <code>toString</code>.</p>
     *
     * <p>This method appends the end of data indicator, and can only be called once.
     * Use {@link #getStringBuffer} to get the current string state.</p>
     *
     * <p>If the object is <code>null</code>, return the style's <code>nullText</code></p>
     *
     * @return the String <code>toString</code>
     */
    @Override
    public String toString() {
        if (this.getObject() == null) {
            this.getStringBuffer().append(this.getStyle().getNullText());
        } else {
            style.appendEnd(this.getStringBuffer(), this.getObject());
        }
        return this.getStringBuffer().toString();
    }

    
Returns the String that was build as an object representation. The default implementation utilizes the toString() implementation. 
See Also:
toString()
Returns:
the String toString
Since:
3.0/**
     * Returns the String that was build as an object representation. The
     * default implementation utilizes the {@link #toString()} implementation.
     *
     * @return the String <code>toString</code>
     *
     * @see #toString()
     *
     * @since 3.0
     */
    @Override
    public String build() {
        return toString();
    }
}