mutablestring.java

MG4J (Managing Gigabytes for Java) is a free full-text search engine for large document collections

    /** Returns a substring of this mutable string.
     *
     * @param start first character of the substring (inclusive).
     * @return a substring ranging from the given position to the end of this string.
     * @see #substring(int,int)
     */
    final public MutableString substring( final int start ) { return substring( start, length() ); }

    /** A class representing a subsequence.
     *
     * <P>Subsequences represented by this class share the backing array. Equality
     * is content-based; hash codes are identical to those of a mutable string with the same content.
     */
    private class SubSequence implements CharSequence {
		final int from, to;
		
		private SubSequence( final int from, final int to ) {
			this.from = from;
			this.to = to;
		}
	
		public char charAt( int index ) { return array[ from + index ]; }
		public int length() { return to - from; }
		public CharSequence subSequence( final int start, final int end ) { 
			if ( start < 0 ) throw new StringIndexOutOfBoundsException( start );
			if ( end < start || end > length() ) throw new StringIndexOutOfBoundsException( end );
			return new SubSequence( this.from + start, this.from + end ); 
		}

		/** For convenience, the hash code of a subsequence is equal
		 * to that of a <code>String</code> with the same content with the
		 * 31st bit set.
		 *
		 * @return the hash code.
		 */
		public int hashCode() {
			int h = 0;
			final char[] a = array;
			for ( int i = from; i < to; i++ ) h = 31 * h + a[ i ];
			return h | ( 1 << 31 );
		}
	
		public boolean equals( Object o ) {
			if ( o instanceof CharSequence ) {
				CharSequence s = (CharSequence)o;
				int n = length();
				if ( n == s.length() ) {
					while( n-- != 0 ) if ( charAt( n ) != s.charAt( n ) ) return false;
					return true;
				}
			}
			return false;
		}

		public String toString() { return new String( array, from, to - from ); }
    }

    
    /** Returns a subsequence of this mutable string.
     *
     * <P>Subsequences <em>share the backing array</em>. Thus, you should
     * <em>not</em> use a subsequence after changing the characters of this
     * mutable string between <code>start</code> and <code>end</code>.
     *
     * <P>Equality of <code>CharSequence</code>s returned by this method is defined by
     * content equality, and hash codes are identical to mutable strings with the same
     * content. Thus, you <em>can</em> mix mutable strings and <code>CharSequence</code>s
     * returned by this method in data structures, as the contracts of {@link java.lang.Object#equals(Object) equals()} and
     * {@link java.lang.Object#hashCode() hashCode()} are honoured.
     * 
     * @param start first character of the subsequence (inclusive).
     * @param end last character of the subsequence (exclusive).
     * @return a subsequence defined as above.
     * @see #substring(int,int)
     */
    final public CharSequence subSequence( final int start, final int end ) { 
		if ( start < 0 ) throw new StringIndexOutOfBoundsException();
		if ( start > end || end > length() ) throw new StringIndexOutOfBoundsException();
		return new SubSequence( start, end );
    }

    /** Appends the given mutable string to this mutable string.
     *
     * @param s the mutable string to append.
     * @return  this mutable string.
     */
    final public MutableString append( MutableString s ) {
    	if ( s == null ) s = NULL;
    	final int l = s.length();
		if ( l == 0 ) return this;

		final int newLength = length() + l;
		expand( newLength );
		System.arraycopy( s.array, 0, array, newLength - l, l ); 
		hashLength = hashLength < 0 ? -1 : newLength;
		return this;
    }

    /**
	 * Appends the given <code>String</code> to this mutable string.
	 * 
	 * @param s a <code>String</code> (<code>null</code> is not allowed).
	 * @return this mutable string.
	 * @throws NullPointerException if the argument is <code>null</code>
	 */
	final public MutableString append( final String s ) {
		if ( s == null ) return append( NULL );
		final int l = s.length();
		if ( l == 0 ) return this;

		final int newLength = length() + l;
		expand( newLength );
		s.getChars( 0, l, array, newLength - l );
		hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}

    /**
	 * Appends the given <code>CharSequence</code> to this mutable string.
	 * 
	 * @param s a <code>CharSequence</code> or <code>null</code>.
	 * @return this mutable string.
	 * 
	 * @see Appendable#append(java.lang.CharSequence)
	 */
	final public MutableString append( final CharSequence s ) {
		if ( s == null ) return append( NULL );
		final int l = s.length();
		if ( l == 0 ) return this;

		final int newLength = length() + l;
		expand( newLength );
		getChars( s, 0, l, array, newLength - l );
		hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}

    /**
	 * Appends a subsequence of the given <code>CharSequence</code> to this mutable string.
	 * 
	 * <strong>Warning</strong>: the semantics of this method of that of
	 * {@link #append(char[], int, int)} are different.
	 * 
	 * @param s a <code>CharSequence</code> or <code>null</code>.
	 * @param start the index of the first character of the subsequence to append.
	 * @param end the index of the character after the last character in the subsequence.
	 * @return this mutable string.
	 * 
	 * @see Appendable#append(java.lang.CharSequence, int, int)
	 */
	final public MutableString append( final CharSequence s, final int start, final int end ) {
		if ( s == null ) return append( NULL, start, end );
		final int len = end - start;
		if ( len < 0 || start < 0 || end > s.length() )
			throw new IndexOutOfBoundsException( "start: " + start + " end: " + end + " length():" + s.length() );
		final int newLength = length() + len;
		expand( newLength );

		try {
			getChars( s, start, end, array, newLength - len );
		}
		catch ( IndexOutOfBoundsException e ) {
			if ( hashLength < 0 ) setCapacity( newLength - len );
			else hashLength = newLength - len;
			throw e;
		}
		if ( len != 0 ) hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}

	/**
	 * Appends the given character sequences to this mutable string using the given separator.
	 * 
	 * @param a an array.
	 * @param offset the index of the first character sequence to append.
	 * @param length the number of character sequences to append.
	 * @param separator a separator that will be appended inbetween the character sequences.
	 * @return this mutable string.
	 */
    // TODO: this needs tests
	final public MutableString append( final CharSequence[] a, final int offset, final int length, final CharSequence separator ) {
    	ObjectArrays.ensureOffsetLength( a, offset, length );
    	if ( length == 0 ) return this;
    	
    	// Precompute the length of the resulting string
    	int m = 0;
    	for( int i = 0; i < length; i++ ) m += a[ offset + i ].length();
    	final int separatorLength = separator.length();
    	m += ( length - 1 ) * separatorLength;

    	final int l = length();
    	ensureCapacity( l + m );
    	m = 0;
    	for( int i = 0; i < length; i++ ) {
    		if ( i != 0 ) {
    			getChars( separator, 0, separatorLength, array, l + m );
    			m += separatorLength;
    		}
    		getChars( a[ i ], 0, a[ i + offset ].length(), array, l + m );
    		m += a[ i ].length();
    	}
    	if ( hashLength < 0 ) hashLength = -1;
    	else hashLength = l + m;
    	return this;
	}

	/** Appends the given character sequences to this mutable string using the given separator.
	 *
	 * @param a an array.
	 * @param separator a separator that will be appended inbetween the character sequences.
	 * @return this mutable string.
	 */
	final public MutableString append( final CharSequence[] a, final CharSequence separator ) {
		return append( a, 0, a.length, separator );
	}
   	

	/** Appends the string representations of the given objects to this mutable string using the given separator.
	 * 
	 * @param a an array of objects.
	 * @param offset the index of the first object to append.
	 * @param length the number of objects to append.
	 * @param separator a separator that will be appended inbetween the string representations of the given objects.
	 * @return this mutable string.
	 */
	final public MutableString append( final Object[] a, final int offset, final int length, final CharSequence separator ) {
		String s[] = new String[ a.length ];
		for( int i = 0; i < length; i++ ) s[ i ] = a[ offset + i ].toString();
		return append( s, offset, length, separator );
	}
	
	/** Appends the string representations of the given objects to this mutable string using the given separator.
	 *
	 * @param a an array of objects.
	 * @param separator a separator that will be appended inbetween the string representations of the given objects.
	 * @return this mutable string.
	 */
	final public MutableString append( final Object[] a, final CharSequence separator ) {
		return append( a, 0, a.length, separator );
	}

    /** Appends the given character array to this mutable string.
     *
     * @param a an array to append.
     * @return this mutable string.
     */
	final public MutableString append( final char a[] ) {
		final int l = a.length;
		if ( l == 0 ) return this;

		final int newLength = length() + l;
		expand( newLength );
		System.arraycopy( a, 0, array, newLength - l, l );
		hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}
    
	/** Appends a part of the given character array to this mutable string.
	 *
	 * <strong>Warning</strong>: the semantics of this method of that of
	 * {@link #append(CharSequence, int, int)} are different.
	 * 
	 * @param a an array.
	 * @param offset the index of the first character to append.
	 * @param len the number of characters to append.
	 * @return this mutable string.
	 */
	final public MutableString append( final char[] a, final int offset, final int len ) {
		final int newLength = length() + len;
		expand( newLength );
		try {
			System.arraycopy( a, offset, array, newLength - len, len );
		}
		catch( IndexOutOfBoundsException e ) {
			if ( hashLength < 0 ) setCapacity( newLength - len );
			else hashLength = newLength - len;
			throw e;
		}
		if ( len != 0 ) hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}
    
	/** Appends the given character list to this mutable string.
	 *
	 * @param list the list to append.
	 * @return this mutable string.
	 */
	final public MutableString append( final CharList list ) {
		final int l = list.size();
		if ( l == 0 ) return this;

		final int newLength = length() + l;
		expand( newLength );
		list.getElements( 0, array, newLength - l, l );
		hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}
   
	/** Appends a part of the given character list to this mutable string.
	 *
	 * <strong>Warning</strong>: the semantics of this method of that of
	 * {@link #append(CharSequence, int, int)} are different.
	 * 
	 * @param list a character list.
	 * @param offset the index of the first character to append.
	 * @param len the number of characters to append.
	 * @return this mutable string.
	 */
	final public MutableString append( final CharList list, final int offset, final int len ) {
		final int newLength = length() + len;
		expand( newLength );
		try {
			list.getElements( offset, array, newLength - len, len );
		}
		catch( IndexOutOfBoundsException e ) {
			if ( hashLength < 0 ) setCapacity( newLength - len );
			else hashLength = newLength - len;
			throw e;
		}
		if ( len != 0 ) hashLength = hashLength < 0 ? -1 : newLength;
		return this;
	}
   
    /** Appends a boolean to this mutable string.
     *
     * @param b the boolean to be appended.
     * @return this mutable string.
     */
    final public MutableString append( boolean b ) { return append( String.valueOf( b ) ); }

    /** Appends a character to this mutable string.
     *
     * <P>Note that this method <em>will reallocate the backing array of a compact
     * mutable string for each character appended</em>.  Do not call it
     * lightly.
     *
     * @param c a character.
     * @return this mutable string.
     */
    final public MutableString append( char c ) {
		final int newLength = length() + 1;
		expand( newLength );
		array[ newLength - 1 ] = c;
		hashLength = hashLength < 0 ? -1 : newLength;
		return this;
    }

    /** Appends an integer to this mutable string.
     *
     * @param i the integer to be appended.
     * @return this mutable string.
     */
    final public MutableString append( final int i ) { return append( String.valueOf( i ) ); }

    /** Appends a long to this mutable string.
     *
     * @param l the long to be appended.
     * @return this mutable string.