// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.core.util;

import java.sql.*;
import java.util.*;

import org.litesoft.charstreams.*;
import org.litesoft.core.simpletypes.nonpublic.*;
import org.litesoft.core.simpletypes.temporal.*;
import org.litesoft.core.simpletypes.temporal.nonpublic.*;
import org.litesoft.core.typeutils.*;

public class UtilsCommon extends EqualSupport
{
    public static final String MUST_BE_POSITIVE = " must be positive";
    public static final String CANNOT_BE_NEGATIVE = " cannot be negative";
    public static final String NOT_ALLOWED_TO_BE_NULL = ": Not allowed to be null";

    protected UtilsCommon()
    {
    }

    public static <T extends Enum<T>> T enumFromString( Class<T> pClass, String pEnumAsString )
    {
        if ( pClass != null )
        {
            if ( null != (pEnumAsString = Strings.noEmpty( pEnumAsString )) )
            {
                try
                {
                    return Enum.valueOf( pClass, pEnumAsString );
                }
                catch ( IllegalArgumentException ex )
                {
                    // Bad String
                }
            }
        }
        return null;
    }

    /**
     * Calculate the new "AccumulatedBitFlags" by Overriding the appropriate bit flags in
     * pPreviousAccumulatedBitFlags (based on the bits in pValidBitsOfNewBitFlags) from the pNewBitFlags.
     *
     * @param pPreviousAccumulatedBitFlags Bit Flags to be selectively overriden.
     * @param pValidBitsOfNewBitFlags      The '1' bits will indicate which bids to override.
     * @param pNewBitFlags                 The source of the override Bit Flags.
     *
     * @return The new "AccumulatedBitFlags".
     */
    public static int mutateAccumulatedBitFlags( int pPreviousAccumulatedBitFlags, int pValidBitsOfNewBitFlags, int pNewBitFlags )
    {
        return (pPreviousAccumulatedBitFlags & (~pValidBitsOfNewBitFlags)) //
               | (pValidBitsOfNewBitFlags & pNewBitFlags);
    }

    public static String cvtTextForDisplay( String pText )
    {
        if ( pText == null )
        {
            return "[null]";
        }
        int length = pText.length();
        StringBuilder sb = new StringBuilder( length );
        for ( int i = 0; i < length; i++ )
        {
            char c = pText.charAt( i );
            switch ( c )
            {
                case '[':
                case ']':
                case '\\':
                case '"':
                    sb.append( '\\' );
                    sb.append( c );
                    break;
                case '\n':
                    sb.append( "\\n" );
                    break;
                case '\r':
                    sb.append( "\\r" );
                    break;
                case '\t':
                    sb.append( "\\t" );
                    break;
                case '\f':
                    sb.append( "\\f" );
                    break;
                default:
                    if ( (' ' <= c) && (c < 127) )
                    {
                        sb.append( c );
                        break;
                    }
                    sb.append( '[' );
                    sb.append( Characters.cvtCharForDisplay( c ) );
                    sb.append( ']' );
                    break;
            }
        }
        return sb.toString();
    }

    public static Object[] convert( int pEntries, Enumeration<Object> pEnumeration )
    {
        Object[] them = new Object[pEntries];
        for ( int i = 0; (i < pEntries) && pEnumeration.hasMoreElements(); i++ )
        {
            them[i] = pEnumeration.nextElement();
        }
        return them;
    }

    public static boolean isEmptyString( Object pObject )
    {
        return pObject == null || ((pObject instanceof String) && Strings.isBlank( (String) pObject ));
    }

    public static boolean areBothEmptyStrings( Object pThis, Object pThat )
    {
        return isEmptyString( pThis ) && isEmptyString( pThat );
    }

    public static boolean areBothBooleanNotTrue( Object pThis, Object pThat )
    {
        return Booleans.isBooleanNotTrue( pThis ) && Booleans.isBooleanNotTrue( pThat );
    }

    public static boolean isNullEquivalent( Object pObject )
    {
        return isEmptyString( pObject ) || Booleans.isBooleanNotTrue( pObject );
    }

    public static boolean areBothNullEquivalent( Object pThis, Object pThat )
    {
        return isNullEquivalent( pThis ) && isNullEquivalent( pThat );
    }

    public static boolean areEqual( Object pThis, Object pThat )
    {
        if ( Objects.areNonArraysEqual( pThis, pThat ) )
        {
            return true;
        }
        // Both CAN'T be null
        if ( (pThis instanceof Object[]) && (pThat instanceof Object[]) )
        {
            return Objects.areArraysEqual( (Object[]) pThis, (Object[]) pThat );
        }
        return (pThis instanceof int[]) && (pThat instanceof int[]) && Integers.areArraysEqual( (int[]) pThis, (int[]) pThat );
    }

    public static String deNullToString( Object value, Object defaultValue )
    {
        return Strings.deNull( noEmptyToString( value ), noEmptyToString( defaultValue ) );
    }

    public static String noEmptyToString( Object value )
    {
        return Strings.noEmpty( Strings.nullOKtoString( value ) );
    }

    public static String trimToLength( String pSource, int pMaxAcceptableLength )
            throws IllegalArgumentException
    {
        pMaxAcceptableLength = assertNotNegative( "MaxAcceptableLength", pMaxAcceptableLength );
        return ((pSource = Strings.deNull( pSource )).length() <= pMaxAcceptableLength) ? pSource : pSource.substring( 0, pMaxAcceptableLength );
    }

    public static String trimToLength( String pSource, int pMaxAcceptableLength, String pTrimmedSuffix )
            throws IllegalArgumentException
    {
        pMaxAcceptableLength = assertNotNegative( "MaxAcceptableLength", pMaxAcceptableLength );
        if ( (pSource = Strings.deNull( pSource )).length() <= pMaxAcceptableLength )
        {
            return pSource;
        }
        int zSuffixLength = (pTrimmedSuffix = Strings.deNull( pTrimmedSuffix )).length();
        if ( zSuffixLength == 0 )
        {
            return pSource.substring( 0, pMaxAcceptableLength );
        }
        if ( pMaxAcceptableLength < zSuffixLength )
        {
            pTrimmedSuffix = pTrimmedSuffix.substring( 0, zSuffixLength = pMaxAcceptableLength );
        }
        pMaxAcceptableLength -= zSuffixLength;
        return pSource.substring( 0, pMaxAcceptableLength ) + pTrimmedSuffix;
    }

    public static String combineAsLines( String... pStrings )
    {
        StringBuilder sb = new StringBuilder();
        if ( pStrings != null )
        {
            for ( String s : pStrings )
            {
                sb.append( s );
                sb.append( '\n' );
            }
        }
        return sb.toString();
    }

    public static String[] splitLines( String pString )
    {
        pString = Strings.normalizeNewLines( pString );

        return Strings.parseChar( pString, '\n' );
    }

    public static String combine( String pSeparator, Object... pObjects )
    {
        if ( Objects.isNullOrEmpty( pObjects ) )
        {
            return null;
        }
        StringBuilder sb = new StringBuilder();

        sb.append( pObjects[0] );

        for ( int i = 1; i < pObjects.length; i++ )
        {
            sb.append( pSeparator );
            sb.append( pObjects[i] );
        }
        return sb.toString();
    }

    public static String combine( char pSeparator, String... pStrings )
    {
        if ( Objects.isNullOrEmpty( pStrings ) )
        {
            return null;
        }
        StringBuilder sb = new StringBuilder();

        sb.append( pStrings[0] );

        for ( int i = 1; i < pStrings.length; i++ )
        {
            sb.append( pSeparator );
            sb.append( pStrings[i] );
        }
        return sb.toString();
    }

    public static void assertAll7BitAsciiAlpha( String pObjectName, String pToBeAssert )
            throws IllegalArgumentException
    {
        Objects.assertNotNull( pObjectName, pToBeAssert );
        for ( int i = 0; i < pToBeAssert.length(); i++ )
        {
            char c = pToBeAssert.charAt( i );
            if ( !(Characters.is7BitAsciiAlpha( c )) )
            {
                throw new IllegalArgumentException( pObjectName + ": '" + c + "' Not a 7 Bit Ascii Alpha at: " + i );
            }
        }
    }

    public static void assertNotEqual( String pObjectName, long pNotExpected, long pActual )
            throws IllegalArgumentException
    {
        if ( pNotExpected == pActual )
        {
            throw new IllegalArgumentException( pObjectName + ": '" + pNotExpected + "' Not allowed" );
        }
    }

    public static void assertTrue( String pValueDescription, boolean pActual )
            throws IllegalArgumentException
    {
        if ( !pActual )
        {
            throw new IllegalArgumentException( pValueDescription + ": Expected to be true" );
        }
    }

    public static void assertNotEmptyIfNotNull( String pParamName, String pToBeAsserted )
            throws IllegalArgumentException
    {
        if ( (pToBeAsserted != null) && (pToBeAsserted.length() == 0) )
        {
            throw new IllegalArgumentException( pParamName + ": Not allowed to be empty ('')" );
        }
    }

    public static void assertNotNullNotEmptyNoSpaces( String pErrorMessage, String pStringToAssert )
            throws IllegalArgumentException
    {
        if ( Strings.isNullOrEmptyOrSpaces( pStringToAssert ) )
        {
            Strings.errorNullOrEmptyOrSpace( pErrorMessage, "String" );
        }
    }

    public static String assertNotNullNotEmpty( String pErrorMessage, String pStringToAssert )
            throws IllegalArgumentException
    {
        String rv = Strings.noEmpty( pStringToAssert );
        if ( rv == null )
        {
            Strings.errorNullOrEmpty( pErrorMessage, "String" );
        }
        return rv;
    }

    public static String assertNoLeadingOrTrailingWhiteSpace( String pErrorMessage, String pStringToAssert )
            throws IllegalArgumentException
    {
        if ( pStringToAssert != null )
        {
            String rv = pStringToAssert.trim();
            if ( pStringToAssert.length() != rv.length() )
            {
                Strings.error( "String", pErrorMessage, "No Leading or trailing whitespace allowed" );
            }
        }
        return pStringToAssert;
    }

    public static String[] assertNotNullNotEmptyAndNoNullsOrEmptiesAndTrim( String pErrorMessage, String[] pStringArrayToAssert )
            throws IllegalArgumentException
    {
        assertNotNullNotEmpty( pErrorMessage, pStringArrayToAssert );
        return assertNoNullsOrEmptiesAndTrim( pErrorMessage, pStringArrayToAssert );
    }

    public static void assertNotNullNotEmpty( String pErrorMessage, String[] pStringArrayToAssert )
            throws IllegalArgumentException
    {
        if ( Objects.isNullOrEmpty( pStringArrayToAssert ) )
        {
            Strings.errorNullOrEmpty( pErrorMessage, "String[]" );
        }
    }

    public static String[] assertNoNullsOrEmptiesAndTrim( String pErrorMessage, String[] pStringArrayToAssert )
            throws IllegalArgumentException
    {
        String[] rv = new String[pStringArrayToAssert.length];
        for ( int i = 0; i < pStringArrayToAssert.length; i++ )
        {
            String s = Strings.noEmpty( pStringArrayToAssert[i] );
            if ( s == null )
            {
                Strings.errorNullOrEmpty( pErrorMessage + "[" + i + "]", "String[]" );
            }
            rv[i] = s;
        }
        return rv;
    }

    /**
     * Assert that "value" is not null or when converted to a String is not
     * empty and then return resulting "value" trimmed.
     *
     * @param what  "field" was the problem on
     * @param value to check
     *
     * @return value converted to a String minus any leading and trailing spaces
     */
    public static String assertNoEmptyToString( String what, Object value )
    {
        String strValue = noEmptyToString( value );
        if ( strValue == null )
        {
            Strings.errorNullOrEmpty( what, String.valueOf( Objects.justClassNameOf( value ) ) );
        }
        return strValue;
    }

    /**
     * Assert that "value" is not null or empty (if it is a String) and return
     * "value" trimmed (if it is a String).
     *
     * @param what  "field" was the problem on
     * @param value to check
     *
     * @return value minus any leading and trailing spaces
     */
    public static <T> T assertNotNullOrEmpty( String what, T value )
    {
        if ( value == null )
        {
            Strings.errorNullOrEmpty( what, String.valueOf( Objects.justClassNameOf( value ) ) );
        }
        if ( value instanceof String )
        {
            value = cast( assertNotNullNotEmpty( what, value.toString() ) );
        }
        return value;
    }

    public static Long assertNotNegative( String pName, Long pValue )
            throws IllegalArgumentException
    {
        if ( pValue != null )
        {
            assertNotNegative( pName, pValue.longValue() );
        }
        return pValue;
    }

    public static long assertNotNegative( String pName, long pValue )
            throws IllegalArgumentException
    {
        if ( pValue < 0 )
        {
            throw new IllegalArgumentException( pName + CANNOT_BE_NEGATIVE );
        }
        return pValue;
    }

    public static Integer assertNotNegative( String pName, Integer pValue )
            throws IllegalArgumentException
    {
        if ( pValue != null )
        {
            assertNotNegative( pName, pValue.intValue() );
        }
        return pValue;
    }

    public static int assertNotNegative( String pName, int pValue )
            throws IllegalArgumentException
    {
        if ( pValue < 0 )
        {
            throw new IllegalArgumentException( pName + CANNOT_BE_NEGATIVE );
        }
        return pValue;
    }

    public static int assertPositive( String pName, int pValue )
            throws IllegalArgumentException
    {
        if ( pValue <= 0 )
        {
            throw new IllegalArgumentException( pName + MUST_BE_POSITIVE );
        }
        return pValue;
    }

    public static String displayFormatFlag( boolean pFlag, String pTrueString )
    {
        return pFlag ? pTrueString : "";
    }

    public static boolean endsWithPathSep( String pPath )
    {
        return (pPath != null) && Characters.isPathSep( pPath.charAt( pPath.length() - 1 ) );
    }

    public static int lastPathSepAt( String pPath )
    {
        if ( pPath != null )
        {
            for ( int at = pPath.length(); --at >= 0; )
            {
                if ( Characters.isPathSep( pPath.charAt( at ) ) )
                {
                    return at;
                }
            }
        }
        return -1;
    }

    public static String forwardSlashPath( String pPath )
    {
        return pPath.replace( '\\', '/' );
    }

    public static String multiLineHelper( String pLine, String pAppend )
    {
        return Strings.isNullOrEmpty( pLine ) ? "" : (pLine + pAppend);
    }

    // Groups

    // Object Group:

    public static String padIt( int pMinDesiredLength, Object pIt )
    {
        return Strings.padIt( pMinDesiredLength, "" + pIt );
    }

    public static String iTpad( Object pIt, int pMinDesiredLength )
    {
        return Strings.iTpad( "" + pIt, pMinDesiredLength );
    }

    public static boolean isAnyTrue( Boolean... pToSearch )
    {
        if ( pToSearch != null )
        {
            for ( Boolean zBoolean : pToSearch )
            {
                if ( Boolean.TRUE.equals( zBoolean ) )
                {
                    return true;
                }
            }
        }
        return false;
    }

    public static boolean isOneOf( String pToFind, String[] pToSearch )
    {
        return isObjectOneOf( pToFind, pToSearch );
    }

    public static boolean isOneOf( Object pToFind, Object[] pToSearch )
    {
        return isObjectOneOf( pToFind, pToSearch );
    }

    private static boolean isObjectOneOf( Object pToFind, Object[] pToSearch )
    {
        if ( pToSearch != null )
        {
            for ( int i = pToSearch.length; --i >= 0; )
            {
                if ( areEqual( pToFind, pToSearch[i] ) )
                {
                    return true;
                }
            }
        }
        return false;
    }

    public static String toStringNullToEmpty( Object pObject )
    {
        if ( pObject != null )
        {
            String rv = pObject.toString();
            if ( rv != null )
            {
                return rv;
            }
        }
        return "";
    }

    public static String toStringOrNull( Object pObject )
    {
        return Strings.noEmpty( (pObject != null) ? pObject.toString() : null );
    }

    public static String toString( Object pObject )
    {
        if ( pObject != null )
        {
            String rv = pObject.toString();
            if ( rv != null )
            {
                return rv;
            }
        }
        return null;
    }

    public static String optionsToString( Object[] pObjects )
    {
        if ( pObjects == null )
        {
            return "No Options Available";
        }
        StringBuilder sb = new StringBuilder( "Valid Options are" );
        String prefix = ": ";
        //noinspection ForLoopReplaceableByForEach
        for ( int i = 0; i < pObjects.length; i++ )
        {
            sb.append( prefix ).append( pObjects[i] );
            prefix = ", ";
        }
        return sb.toString();
    }

    public static String toString( Object[] pObjects )
    {
        if ( pObjects == null )
        {
            return "null";
        }
        return new StringBuilder().append( '<' ).append( pObjects.length ).append( ':' ).append( toString( pObjects, "," ) ).append( '>' ).toString();
    }

    public static String toString( Object[] pObjects, String separator )
    {
        if ( pObjects == null )
        {
            return "null";
        }
        StringBuilder sb = new StringBuilder();
        if ( pObjects.length > 0 )
        {
            sb.append( pObjects[0] );
            //noinspection ForLoopReplaceableByForEach
            for ( int i = 1; i < pObjects.length; i++ )
            {
                sb.append( separator ).append( pObjects[i] );
            }
        }
        return sb.toString();
    }

    public static Map<String, String> createHashMap( String... pKeyValuePairs )
            throws IllegalArgumentException
    {
        return populate( new HashMap<String, String>(), pKeyValuePairs );
    }

    public static Map<String, String> populate( Map<String, String> pToPopulate, String... pNameValuePairs )
            throws IllegalArgumentException
    {
        if ( pNameValuePairs != null )
        {
            if ( (pNameValuePairs.length & 1) == 1 )
            {
                throw new IllegalArgumentException( "NameValuePairs not paired" );
            }
            for ( int i = 0; i < pNameValuePairs.length; )
            {
                String name = pNameValuePairs[i++];
                String value = pNameValuePairs[i++];
                // noinspection unchecked
                pToPopulate.put( name, value );
            }
        }
        return pToPopulate;
    }

    public static void populate( Map pToPopulate, Map pNewContents )
    {
        if ( pNewContents != null )
        {
            //noinspection unchecked
            pToPopulate.putAll( pNewContents );
        }
    }

    public static String[] getSortedKeysAsStrings( Map pMap )
    {
        String[] names = toStringArray( pMap.keySet().toArray() );
        Arrays.sort( names );
        return names;
    }

    public static String[] arrayOfOne( String pString )
    {
        return new String[]{pString};
    }

    public static String[] toStringArray( Collection pCollection )
    {
        return (pCollection == null) ? null : toStringArray( pCollection.toArray() );
    }

    public static String[] toStringArray( Object[] pObjects )
    {
        if ( pObjects == null )
        {
            return null;
        }
        String[] zStrings = new String[pObjects.length];
        for ( int i = 0; i < pObjects.length; i++ )
        {
            Object o = pObjects[i];
            zStrings[i] = (o == null) ? null : o.toString();
        }
        return zStrings;
    }

    public static List<String> toStringList( Collection pCollection )
    {
        return (pCollection == null) ? null : toStringList( pCollection.toArray() );
    }

    public static List<String> toStringList( Object[] pObjects )
    {
        if ( pObjects == null )
        {
            return null;
        }
        List<String> strings = new ArrayList<String>( pObjects.length );
        for ( Object o : pObjects )
        {
            strings.add( (o == null) ? null : o.toString() );
        }
        return strings;
    }

    public static Map<String, String> addPropertiesTo( Map<String, String> pMap, String... pProperty_NameValues )
            throws IllegalArgumentException
    {
        if ( Objects.isNotNullOrEmpty( pProperty_NameValues ) )
        {
            if ( (pProperty_NameValues.length & 1) != 0 )
            {
                throw new IllegalArgumentException( "Attempt to add Properties that were NOT Name/Value pairs" );
            }
            for ( int i = 0; i < pProperty_NameValues.length; i += 2 )
            {
                pMap.put( pProperty_NameValues[i], pProperty_NameValues[i + 1] );
            }
        }
        return pMap;
    }

    public static boolean isAll7BitAsciiAlpha( String pString, int pMinLength )
    {
        if ( (pString == null) || (pString.length() < pMinLength) )
        {
            return false;
        }
        for ( int i = 0; i < pString.length(); i++ )
        {
            if ( !Characters.is7BitAsciiAlpha( pString.charAt( i ) ) )
            {
                return false;
            }
        }
        return true;
    }

    public static boolean isAlphaNumeric( String pString, int pMinLength )
    {
        if ( (pString == null) || (pString.length() < pMinLength) )
        {
            return false;
        }
        for ( int i = 0; i < pString.length(); i++ )
        {
            if ( !Characters.isAlphaNumeric( pString.charAt( i ) ) )
            {
                return false;
            }
        }
        return true;
    }

    public static boolean isNumeric( String pString, int pMinLength )
    {
        if ( (pString == null) || (pString.length() < pMinLength) )
        {
            return false;
        }
        for ( int i = 0; i < pString.length(); i++ )
        {
            if ( !Characters.isNumeric( pString.charAt( i ) ) )
            {
                return false;
            }
        }
        return true;
    }

    public static boolean isValidAttributeIdentifier( String pIdentifier )
    {
        return isValidAttributeIdentifier( pIdentifier, 2 );
    }

    public static boolean isValidAttributeIdentifier( String pIdentifier, int pMinLength )
    {
        if ( (pIdentifier == null) || (pIdentifier.length() < pMinLength) )
        {
            return false;
        }

        if ( !Characters.isValidAttributeIdentifierStartCharacter( pIdentifier.charAt( 0 ) ) )
        {
            return false;
        }
        for ( int i = 1; i < pIdentifier.length(); i++ )
        {
            if ( !Characters.isValidAttributeIdentifierRestCharacter( pIdentifier.charAt( i ) ) )
            {
                return false;
            }
        }
        return true;
    }

    @SuppressWarnings({"unchecked", "ManualArrayToCollectionCopy", "MismatchedQueryAndUpdateOfCollection"})
    public static <T> Collection<T> convert( Collection<T> pCollectionToFill, Object[] pObjects )
    {
        Collection<Object> toFill = (Collection<Object>) pCollectionToFill;
        for ( Object object : pObjects )
        {
            toFill.add( object );
        }
        return pCollectionToFill;
    }

    public static void appendClassName( StringBuilder pBuffer, int pTabLevel, String pLabel, Object pValue )
    {
        append( pBuffer, pTabLevel, pLabel, (pValue == null) ? null : pValue.getClass().getName() );
    }

    public static void append( StringBuilder pBuffer, int pTabLevel, String pLabel, Object pValue )
    {
        append( pBuffer, pTabLevel, pLabel );
        pBuffer.append( ':' );
        pBuffer.append( (pValue == null) ? "null" : pValue.toString() );
    }

    public static void append( StringBuilder pBuffer, int pTabLevel, String pValue )
    {
        pBuffer.append( '\n' );
        while ( pTabLevel-- >= 1 )
        {
            pBuffer.append( '\t' );
        }
        pBuffer.append( (pValue == null) ? "null" : pValue );
    }

    public static <T> List<T> convert( Enumeration<T> pEnumeration )
    {
        ArrayList<T> rv = new ArrayList<T>();
        while ( pEnumeration.hasMoreElements() )
        {
            rv.add( pEnumeration.nextElement() );
        }
        return rv;
    }

    public static String[] parseOptions( String pOptionsAsString )
            throws IllegalArgumentException
    {
        if ( null == (pOptionsAsString = Strings.noEmpty( pOptionsAsString )) )
        {
            return null;
        }
        char sep = pOptionsAsString.charAt( 0 );
        return Character.isLetterOrDigit( sep ) ? //
               parseOptions( pOptionsAsString, ',' ) : //
               parseOptions( pOptionsAsString.substring( 1 ).trim(), sep );
    }

    private static String[] parseOptions( String pStringToParse, char pSeparator )
            throws IllegalArgumentException
    {
        List<String> zParts = new ArrayList<String>();
        int from = 0;
        for ( int at; -1 != (at = pStringToParse.indexOf( pSeparator, from )); from = at + 1 )
        {
            addNotEmpty( zParts, pStringToParse.substring( from, at ) );
        }
        addNotEmpty( zParts, pStringToParse.substring( from ) );
        if ( zParts.size() < 2 )
        {
            throw new IllegalArgumentException( "Not TWO options, given: " + pStringToParse );
        }
        return toStringArray( zParts );
    }

    private static void addNotEmpty( List<String> pParts, String pPart )
    {
        if ( (pPart = pPart.trim()).length() != 0 )
        {
            pParts.add( pPart );
        }
    }

    public static String printStackTraceToString( Throwable pThrowable )
    {
        ExceptionStackTracePrintStream ps = new ExceptionStackTracePrintStream();
        pThrowable.printStackTrace( ps );
        return ps.toString();
    }

    public static String normalizeCtrlChars( String pText )
    {
        if ( pText != null )
        {
            for ( int i = pText.length(); i-- > 0; )
            {
                if ( pText.charAt( i ) < ' ' )
                {
                    StringBuilder sb = new StringBuilder( pText );
                    for (; i >= 0; i-- )
                    {
                        char c = sb.charAt( i );
                        if ( c < ' ' )
                        {
                            switch ( c )
                            {
                                case '\n':
                                case '\r':
                                case '\f':
                                    break;
                                case '\t':
                                    sb.setCharAt( i, ' ' );
                                    break;
                                default:
                                    sb.setCharAt( i, '.' );
                                    break;
                            }
                        }
                        pText = sb.toString();
                    }
                    break;
                }
            }
        }
        return pText;
    }

    /**
     * Given path(s) that may be system dependent, create a path
     * that is converted to a system independent form (forward Slashes).
     * Note: Ignore null entries (null, or all nulls returns null).
     */
    public static String forwardSlashPath( String... pPaths )
    {
        StringBuilder sb = null;
        if ( pPaths != null )
        {
            for ( String path : pPaths )
            {
                if ( path != null )
                {
                    if ( sb == null )
                    {
                        sb = new StringBuilder();
                    }
                    if ( path.length() != 0 )
                    {
                        String fsp = forwardSlashPath( path );
                        if ( sb.length() == 0 )
                        {
                            sb.append( fsp );
                        }
                        else
                        {
                            boolean pStartsWithSlash = (fsp.charAt( 0 ) == '/');
                            if ( sb.charAt( sb.length() - 1 ) == '/' )
                            {
                                sb.append( pStartsWithSlash ? fsp.substring( 1 ) : fsp );
                            }
                            else
                            {
                                if ( !pStartsWithSlash )
                                {
                                    sb.append( '/' );
                                }
                                sb.append( fsp );
                            }
                        }
                    }
                }
            }
        }
        return (sb == null) ? null : sb.toString();
    }

    /**
     * @param pText !null
     */
    public static void formatToJavaSourceString( StringBuilder pSB, String pText )
    {
        LowLevelEncode( pSB, new CharSourceFromSequence( pText ), true );
    }

    public static String encodeToConstrainedASCII( String pText )
    {
        if ( Strings.isNullOrEmpty( pText ) )
        {
            return pText;
        }
        return LowLevelEncode( new StringBuilder(), new CharSourceFromSequence( pText, 0 ), true ).toString();
    }

    public static String decodeFromConstrainedASCII( String pText )
    {
        if ( Strings.isNullOrEmpty( pText ) )
        {
            return pText;
        }
        return LowLevelDecode( new StringBuilder(), new CharSourceFromSequence( pText, 0 ), false ).toString();
    }

    private static StringBuilder LowLevelEncode( StringBuilder pSB, CharSource pSource, boolean pDoubleQuoteSpecial )
    {
        for ( int c; -1 != (c = pSource.get()); )
        {
            if ( pDoubleQuoteSpecial && (c == '"') )
            {
                pSB.append( '\\' );
                pSB.append( (char) c );
            }
            else
            {
                switch ( c )
                {
                    case '\\':
                        pSB.append( '\\' );
                        pSB.append( '\\' );
                        break;
                    case '\n':
                        pSB.append( '\\' );
                        pSB.append( 'n' );
                        break;
                    case '\r':
                        pSB.append( '\\' );
                        pSB.append( 'r' );
                        break;
                    case '\t':
                        pSB.append( '\\' );
                        pSB.append( 't' );
                        break;
                    default:
                        if ( (' ' <= c) && (c < 127) )
                        {
                            pSB.append( (char) c );
                            break;
                        }
                        pSB.append( '\\' );
                        pSB.append( 'x' );
                        pSB.append( Hex.toChar( c >> 24 ) );
                        pSB.append( Hex.toChar( c >> 16 ) );
                        pSB.append( Hex.toChar( c >> 8 ) );
                        pSB.append( Hex.toChar( c ) );
                        break;
                }
            }
        }
        return pSB;
    }

    private static StringBuilder LowLevelDecode( StringBuilder pSB, CharSource pSource, boolean pDoubleQuoteSpecial )
    {
        for ( int c; -1 != (c = pSource.get()); )
        {
            if ( (c < ' ') || (127 <= c) )
            {
                throw new IllegalArgumentException( "Decoding Error: Char[" + pSource.getLastOffset() + "] Not between ' ' & Ascii 126 (inclusive)" );
            }
            if ( c != '\\' )
            {
                pSB.append( (char) c );
                continue;
            }
            if ( -1 == (c = pSource.get()) )
            {
                throw new IllegalArgumentException( "Decoding Error: No Char after escape \\" );
            }
            if ( pDoubleQuoteSpecial && (c == '"') )
            {
                pSB.append( (char) c );
            }
            else
            {
                switch ( c )
                {
                    case '\\':
                        pSB.append( (char) c );
                        break;
                    case 'n':
                        pSB.append( '\n' );
                        break;
                    case 'r':
                        pSB.append( '\r' );
                        break;
                    case 't':
                        pSB.append( '\t' );
                        break;
                    case 'x':
                        int c1 = pSource.get();
                        int c2 = pSource.get();
                        int c3 = pSource.get();
                        int c4 = pSource.get();
                        if ( c4 == -1 )
                        {
                            throw new IllegalArgumentException( "Decoding Error: Not enough Chars after \\x" );
                        }
                        try
                        {
                            int zChar = (Hex.fromCharChecked( (char) c1 ) << 24) + //
                                        (Hex.fromCharChecked( (char) c2 ) << 16) + //
                                        (Hex.fromCharChecked( (char) c3 ) << 8) + //
                                        Hex.fromCharChecked( (char) c4 );
                            pSB.append( (char) zChar );
                        }
                        catch ( IllegalArgumentException e )
                        {
                            throw new IllegalArgumentException( "Decoding Error: After \\x expected 4 hex digits: " + e.getMessage() );
                        }
                        break;
                    default:
                        throw new IllegalArgumentException( "Decoding Error: Invalid Char '" + c + "' after escape \\" );
                }
            }
        }
        return pSB;
    }

    // Array / varArgs

    public static String combineAsLines( List<String> pStrings )
    {
        return combineAsLines( (pStrings == null) ? null : pStrings.toArray( new String[pStrings.size()] ) );
    }

    public static String combine( String pSeparator, List<String> pStrings )
    {
        //noinspection SuspiciousToArrayCall
        return combine( pSeparator, (Object[]) pStrings.toArray( new String[pStrings.size()] ) );
    }

    public static String combineObjects( String pSeparator, List<?> pObjects )
    {
        return combine( pSeparator, pObjects.toArray() );
    }

    // Objects:

    // Object Group:

    public static boolean areNotNull( Object... pToChecks )
    {
        if ( pToChecks == null )
        {
            return false;
        }
        for ( Object toCheck : pToChecks )
        {
            if ( toCheck == null )
            {
                return false;
            }
        }
        return true;
    }

    public static boolean isAsciiIdentifier( String pToTest )
    {
        if ( !Strings.isNullOrEmpty( pToTest ) )
        {
            if ( Characters.isFirstCharAsciiIdentifier( pToTest.charAt( 0 ) ) )
            {
                for ( int i = 1; i < pToTest.length(); i++ )
                {
                    if ( !Characters.isNonFirstCharAsciiIdentifier( pToTest.charAt( i ) ) )
                    {
                        return false;
                    }
                }
                return true;
            }
        }
        return false;
    }

    public static boolean isNoSpaceAscii( String pToTest )
    {
        if ( !Strings.isNullOrEmpty( pToTest ) )
        {
            for ( int i = 0; i < pToTest.length(); i++ )
            {
                if ( !Characters.isNoSpaceAscii( pToTest.charAt( i ) ) )
                {
                    return false;
                }
            }
            return true;
        }
        return false;
    }

    public static boolean isNoCtrlAscii( String pToTest )
    {
        if ( pToTest != null )
        {
            for ( int i = 0; i < pToTest.length(); i++ )
            {
                if ( !Characters.isNoCtrlAscii( pToTest.charAt( i ) ) )
                {
                    return false;
                }
            }
            return true;
        }
        return false;
    }

    public static boolean hasText( Object pValue )
    {
        return (pValue != null) && (pValue.toString().trim().length() != 0);
    }

    public static SimpleDate forceEndOfMonth( SimpleDate pSimpleDate )
    {
        if ( pSimpleDate != null )
        {
            int zDaysInMonth = CalendarSupport.daysInMonth( pSimpleDate.getYear(), pSimpleDate.getMonth() );
            if ( pSimpleDate.getDay() != zDaysInMonth )
            {
                pSimpleDate.setDay( zDaysInMonth );
            }
        }
        return pSimpleDate;
    }

    public static String singleQuoteToString( List<String> pStrings )
    {
        StringBuilder sb = new StringBuilder();
        if ( pStrings != null )
        {
            char prefix = '[';
            if ( pStrings.size() == 0 )
            {
                sb.append( prefix );
            }
            else
            {
                for ( String zString : pStrings )
                {
                    sb.append( prefix );
                    sb.append( '\'' );
                    sb.append( zString );
                    sb.append( '\'' );
                    prefix = ',';
                }
            }
            sb.append( ']' );
        }
        return sb.toString();
    }

    @SuppressWarnings({"unchecked"})
    public static <T> T cast( Object o )
    {
        return (T) o;
    }
}