001/**
002 * MutableTextValue.java
003 * 
004 * Copyright (c) 2004-2012, Nicole C. Tedesco. All rights reserved.
005 * 
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
007 * use this file except in compliance with the License. You may obtain a copy of
008 * the License at:
009 * 
010 * http://www.apache.org/licenses/LICENSE-2.0
011 * 
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations under
016 * the License.
017 */
018
019package net.sf.jaccumulator.texts;
020
021import java.util.Collection;
022
023import net.sf.jaccumulator.MutableAlgebraicStructure;
024
025/**
026 * A changeable {@link String text} property value
027 * 
028 * @param <VALUE>
029 *        this value type (used to facilitate operation chaining)
030 * @since JAccumulator 4.0
031 * @author Nicole Tedesco (<a
032 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
033 */
034public interface MutableTextValue<VALUE extends MutableTextValue<VALUE>>
035    extends
036        Appendable
037{
038    public VALUE append( final boolean aValue )
039        throws UnsupportedOperationException;
040
041    @Override
042    public VALUE append( final char aValue )
043        throws UnsupportedOperationException;
044
045    public VALUE append( final char[] content )
046        throws UnsupportedOperationException;
047
048    public VALUE append( final char[] content, final int contentIndex )
049        throws UnsupportedOperationException;
050
051    public VALUE append(
052        final char[] content,
053        int contentIndex,
054        int contentLength ) throws UnsupportedOperationException;
055
056    @Override
057    public VALUE append( final CharSequence content )
058        throws UnsupportedOperationException;
059
060    public VALUE append( final CharSequence content, final int contentStartIndex )
061        throws UnsupportedOperationException;
062
063    @Override
064    public VALUE append(
065        final CharSequence content,
066        int contentStartIndex,
067        int contentEndIndexPlusOne ) throws UnsupportedOperationException;
068
069    public VALUE append( final double aValue )
070        throws UnsupportedOperationException;
071
072    public VALUE append( final float aValue )
073        throws UnsupportedOperationException;
074
075    public VALUE append( final int aValue )
076        throws UnsupportedOperationException;
077
078    public VALUE append( final long aValue )
079        throws UnsupportedOperationException;
080
081    public VALUE append( final Object aValue )
082        throws UnsupportedOperationException;
083
084    public VALUE append( final StringBuffer sb )
085        throws UnsupportedOperationException;
086
087    public VALUE appendCodePoint( final int codePoint )
088        throws UnsupportedOperationException;
089
090    /**
091     * Same as {@link Collection#clear()}. So as to maintain compatibility, this
092     * function will not return the customary reference back to this primitive.
093     * In text primitives, this function will clear the current text contents
094     * 
095     * @throws UnsupportedOperationException
096     *         if this text cannot be cleared
097     * 
098     * @see #clearText();
099     * @see Collection#clear()
100     * @see MutableAlgebraicStructure#clearContents()
101     */
102    public void clear() throws UnsupportedOperationException;
103
104    /**
105     * Clear all characters from this primitive and re-interpret/re-set
106     * 
107     * @return this object (facilitates operation chaining)
108     * @throws UnsupportedOperationException
109     *         if this object's text cannot be changed
110     * @see #clear();
111     * @see Collection#clear()
112     * @see MutableAlgebraicStructure#clearContents()
113     */
114    public VALUE clearText() throws UnsupportedOperationException;
115
116    public VALUE delete( final int start, final int end )
117        throws UnsupportedOperationException;
118
119    public VALUE deleteCharAt( final int anIndex )
120        throws UnsupportedOperationException;
121
122    public VALUE insert( final int anIndex, boolean aValue )
123        throws UnsupportedOperationException;
124
125    public VALUE insert( final int anIndex, char aValue )
126        throws UnsupportedOperationException;
127
128    public VALUE insert( final int anIndex, char[] content )
129        throws UnsupportedOperationException;
130
131    public VALUE insert(
132        final int targetIndex,
133        char[] content,
134        int contentIndex,
135        int contentLength ) throws UnsupportedOperationException;
136
137    public VALUE insert( final int anIndex, CharSequence content )
138        throws UnsupportedOperationException;
139
140    public VALUE insert(
141        final int targetIndex,
142        CharSequence content,
143        int contentIndex ) throws UnsupportedOperationException;
144
145    public VALUE insert(
146        final int targetIndex,
147        CharSequence content,
148        int contentStartIndex,
149        int contentEndIndexPlusOne ) throws UnsupportedOperationException;
150
151    public VALUE insert( final int anIndex, double aValue )
152        throws UnsupportedOperationException;
153
154    public VALUE insert( final int anIndex, float aValue )
155        throws UnsupportedOperationException;
156
157    public VALUE insert( final int anIndex, final int aValue )
158        throws UnsupportedOperationException;
159
160    public VALUE insert( final int anIndex, long aValue )
161        throws UnsupportedOperationException;
162
163    public VALUE insert( final int anIndex, final Object aValue )
164        throws UnsupportedOperationException;
165
166    /**
167     * For text-based objects, convert all characters in the text to lower case.
168     * For numeric objects, convert their character (BMP) or integer value
169     * (Unicode) to lower case, depending on the object's precision level
170     * 
171     * @return this object (facilitates operation chaining)
172     */
173    public VALUE lowerCase();
174
175    public VALUE prepend( final boolean aValue )
176        throws UnsupportedOperationException;
177
178    public VALUE prepend( final char aValue )
179        throws UnsupportedOperationException;
180
181    public VALUE prepend( final char[] content )
182        throws UnsupportedOperationException;
183
184    public VALUE prepend( final char[] content, final int contentIndex )
185        throws UnsupportedOperationException;
186
187    public VALUE prepend(
188        final char[] content,
189        int contentIndex,
190        int contentLength ) throws UnsupportedOperationException;
191
192    public VALUE prepend( final CharSequence content )
193        throws UnsupportedOperationException;
194
195    public VALUE prepend( final CharSequence content, final int contentIndex )
196        throws UnsupportedOperationException;
197
198    public VALUE prepend(
199        final CharSequence content,
200        int contentStartIndex,
201        int contentEndIndexPlusOne ) throws UnsupportedOperationException;
202
203    public VALUE prepend( final double aValue )
204        throws UnsupportedOperationException;
205
206    public VALUE prepend( final float aValue )
207        throws UnsupportedOperationException;
208
209    public VALUE prepend( final int aValue )
210        throws UnsupportedOperationException;
211
212    public VALUE prepend( final long aValue )
213        throws UnsupportedOperationException;
214
215    public VALUE prepend( final Object aValue )
216        throws UnsupportedOperationException;
217
218    public VALUE replace(
219        final CharSequence target,
220        final CharSequence replacement ) throws UnsupportedOperationException;
221
222    public VALUE replace( final int start, final int end, final String str )
223        throws UnsupportedOperationException;
224
225    public VALUE replaceAll( final String regex, final String replacement )
226        throws UnsupportedOperationException;
227
228    public VALUE replaceCharacter( final char oldChar, final char newChar )
229        throws UnsupportedOperationException;
230
231    public VALUE replaceFirst( final String regex, final String replacement )
232        throws UnsupportedOperationException;
233
234    public VALUE reverse() throws UnsupportedOperationException;
235
236    public VALUE setCharAt( final int index, final char ch )
237        throws UnsupportedOperationException;
238
239    public VALUE setLength( final int newLength )
240        throws UnsupportedOperationException;
241
242    /**
243     * Set this property to the specified {@link String text} value and answer
244     * this object (facilitates chaining)
245     * 
246     * @param content
247     *        a {@link String text} value
248     * @return this object (facilitates operation chaining)
249     * @throws UnsupportedOperationException
250     *         if this object's value cannot be changed
251     * @throws IllegalArgumentException
252     *         if the specified value was incommensurate with this object's
253     *         specification
254     * @throws NullPointerException
255     *         a {@code null} value was provided and this implementation does
256     *         not accept {@code null} values
257     */
258    public VALUE setText( final CharSequence content )
259        throws UnsupportedOperationException,
260            IllegalArgumentException,
261            NullPointerException;
262
263    /**
264     * Decrement the real value of this text then return the original text prior
265     * to decrementing
266     * 
267     * @return the original value of this text
268     * @throws UnsupportedOperationException
269     *         if this object's value cannot be changed
270     * @throws IllegalArgumentException
271     *         if the new value was incommensurate with this object's
272     *         specification
273     * @throws ArithmeticException
274     *         the new numeric value was incompatible with with algebraic
275     *         interpretation of this object
276     */
277    public String textPostDecrement()
278        throws UnsupportedOperationException,
279            ArithmeticException,
280            IllegalArgumentException;
281
282    /**
283     * Increment the real value of this text then return the original text prior
284     * to incrementing
285     * 
286     * @return the original value of this text
287     * @throws UnsupportedOperationException
288     *         if this object's value cannot be changed
289     * @throws IllegalArgumentException
290     *         if the new value was incommensurate with this object's
291     *         specification
292     * @throws ArithmeticException
293     *         the new numeric value was incompatible with with algebraic
294     *         interpretation of this object
295     */
296    public String textPostIncrement()
297        throws UnsupportedOperationException,
298            ArithmeticException,
299            IllegalArgumentException;
300
301    /**
302     * For text-based objects, convert all characters in the text to
303     * {@link Character#toTitleCase(char) title} case. For numeric objects,
304     * convert their character (BMP) or integer value (Unicode) to title case,
305     * depending on the object's precision level
306     * 
307     * @return this object (facilitates operation chaining)
308     */
309    public VALUE titleCase();
310
311    /**
312     * Remove both leading and trailing {@link Character#isWhitespace(char)
313     * whitespace}
314     * 
315     * @return this object (facilitates operation chaining)
316     */
317    public VALUE trim();
318
319    /**
320     * For text-based objects, convert all characters in the text to upper case.
321     * For numeric objects, convert their character (BMP) or integer value
322     * (Unicode) to upper case, depending on the object's precision level
323     * 
324     * @return this object (facilitates operation chaining)
325     */
326    public VALUE upperCase();
327}