1 /*
2  * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 /*
27  * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
28  * (C) Copyright IBM Corp. 1996 - All Rights Reserved
29  *
30  *   The original version of this source code and documentation is copyrighted
31  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
32  * materials are provided under terms of a License Agreement between Taligent
33  * and Sun. This technology is protected by multiple US and International
34  * patents. This notice and attribution to Taligent may not be removed.
35  *   Taligent is a registered trademark of Taligent, Inc.
36  *
37  */
38 
39 package java.text;
40 
41 /**
42  * <code>FieldPosition</code> is a simple class used by <code>Format</code>
43  * and its subclasses to identify fields in formatted output. Fields can
44  * be identified in two ways:
45  * <ul>
46  *  <li>By an integer constant, whose names typically end with
47  *      <code>_FIELD</code>. The constants are defined in the various
48  *      subclasses of <code>Format</code>.
49  *  <li>By a <code>Format.Field</code> constant, see <code>ERA_FIELD</code>
50  *      and its friends in <code>DateFormat</code> for an example.
51  * </ul>
52  * <p>
53  * <code>FieldPosition</code> keeps track of the position of the
54  * field within the formatted output with two indices: the index
55  * of the first character of the field and the index of the last
56  * character of the field.
57  *
58  * <p>
59  * One version of the <code>format</code> method in the various
60  * <code>Format</code> classes requires a <code>FieldPosition</code>
61  * object as an argument. You use this <code>format</code> method
62  * to perform partial formatting or to get information about the
63  * formatted output (such as the position of a field).
64  *
65  * <p>
66  * If you are interested in the positions of all attributes in the
67  * formatted string use the <code>Format</code> method
68  * <code>formatToCharacterIterator</code>.
69  *
70  * @author      Mark Davis
71  * @see         java.text.Format
72  */
73 public class FieldPosition {
74 
75     /**
76      * Input: Desired field to determine start and end offsets for.
77      * The meaning depends on the subclass of Format.
78      */
79     int field = 0;
80 
81     /**
82      * Output: End offset of field in text.
83      * If the field does not occur in the text, 0 is returned.
84      */
85     int endIndex = 0;
86 
87     /**
88      * Output: Start offset of field in text.
89      * If the field does not occur in the text, 0 is returned.
90      */
91     int beginIndex = 0;
92 
93     /**
94      * Desired field this FieldPosition is for.
95      */
96     private Format.Field attribute;
97 
98     /**
99      * Creates a FieldPosition object for the given field.  Fields are
100      * identified by constants, whose names typically end with _FIELD,
101      * in the various subclasses of Format.
102      *
103      * @param field the field identifier
104      * @see java.text.NumberFormat#INTEGER_FIELD
105      * @see java.text.NumberFormat#FRACTION_FIELD
106      * @see java.text.DateFormat#YEAR_FIELD
107      * @see java.text.DateFormat#MONTH_FIELD
108      */
FieldPosition(int field)109     public FieldPosition(int field) {
110         this.field = field;
111     }
112 
113     /**
114      * Creates a FieldPosition object for the given field constant. Fields are
115      * identified by constants defined in the various <code>Format</code>
116      * subclasses. This is equivalent to calling
117      * <code>new FieldPosition(attribute, -1)</code>.
118      *
119      * @param attribute Format.Field constant identifying a field
120      * @since 1.4
121      */
FieldPosition(Format.Field attribute)122     public FieldPosition(Format.Field attribute) {
123         this(attribute, -1);
124     }
125 
126     /**
127      * Creates a <code>FieldPosition</code> object for the given field.
128      * The field is identified by an attribute constant from one of the
129      * <code>Field</code> subclasses as well as an integer field ID
130      * defined by the <code>Format</code> subclasses. <code>Format</code>
131      * subclasses that are aware of <code>Field</code> should give precedence
132      * to <code>attribute</code> and ignore <code>fieldID</code> if
133      * <code>attribute</code> is not null. However, older <code>Format</code>
134      * subclasses may not be aware of <code>Field</code> and rely on
135      * <code>fieldID</code>. If the field has no corresponding integer
136      * constant, <code>fieldID</code> should be -1.
137      *
138      * @param attribute Format.Field constant identifying a field
139      * @param fieldID integer constant identifying a field
140      * @since 1.4
141      */
FieldPosition(Format.Field attribute, int fieldID)142     public FieldPosition(Format.Field attribute, int fieldID) {
143         this.attribute = attribute;
144         this.field = fieldID;
145     }
146 
147     /**
148      * Returns the field identifier as an attribute constant
149      * from one of the <code>Field</code> subclasses. May return null if
150      * the field is specified only by an integer field ID.
151      *
152      * @return Identifier for the field
153      * @since 1.4
154      */
getFieldAttribute()155     public Format.Field getFieldAttribute() {
156         return attribute;
157     }
158 
159     /**
160      * Retrieves the field identifier.
161      *
162      * @return the field identifier
163      */
getField()164     public int getField() {
165         return field;
166     }
167 
168     /**
169      * Retrieves the index of the first character in the requested field.
170      *
171      * @return the begin index
172      */
getBeginIndex()173     public int getBeginIndex() {
174         return beginIndex;
175     }
176 
177     /**
178      * Retrieves the index of the character following the last character in the
179      * requested field.
180      *
181      * @return the end index
182      */
getEndIndex()183     public int getEndIndex() {
184         return endIndex;
185     }
186 
187     /**
188      * Sets the begin index.  For use by subclasses of Format.
189      *
190      * @param bi the begin index
191      * @since 1.2
192      */
setBeginIndex(int bi)193     public void setBeginIndex(int bi) {
194         beginIndex = bi;
195     }
196 
197     /**
198      * Sets the end index.  For use by subclasses of Format.
199      *
200      * @param ei the end index
201      * @since 1.2
202      */
setEndIndex(int ei)203     public void setEndIndex(int ei) {
204         endIndex = ei;
205     }
206 
207     /**
208      * Returns a <code>Format.FieldDelegate</code> instance that is associated
209      * with the FieldPosition. When the delegate is notified of the same
210      * field the FieldPosition is associated with, the begin/end will be
211      * adjusted.
212      */
getFieldDelegate()213     Format.FieldDelegate getFieldDelegate() {
214         return new Delegate();
215     }
216 
217     /**
218      * Overrides equals
219      */
equals(Object obj)220     public boolean equals(Object obj)
221     {
222         if (obj == null) return false;
223         if (!(obj instanceof FieldPosition))
224             return false;
225         FieldPosition other = (FieldPosition) obj;
226         if (attribute == null) {
227             if (other.attribute != null) {
228                 return false;
229             }
230         }
231         else if (!attribute.equals(other.attribute)) {
232             return false;
233         }
234         return (beginIndex == other.beginIndex
235             && endIndex == other.endIndex
236             && field == other.field);
237     }
238 
239     /**
240      * Returns a hash code for this FieldPosition.
241      * @return a hash code value for this object
242      */
hashCode()243     public int hashCode() {
244         return (field << 24) | (beginIndex << 16) | endIndex;
245     }
246 
247     /**
248      * Return a string representation of this FieldPosition.
249      * @return  a string representation of this object
250      */
toString()251     public String toString() {
252         return getClass().getName() +
253             "[field=" + field + ",attribute=" + attribute +
254             ",beginIndex=" + beginIndex +
255             ",endIndex=" + endIndex + ']';
256     }
257 
258 
259     /**
260      * Return true if the receiver wants a <code>Format.Field</code> value and
261      * <code>attribute</code> is equal to it.
262      */
matchesField(Format.Field attribute)263     private boolean matchesField(Format.Field attribute) {
264         if (this.attribute != null) {
265             return this.attribute.equals(attribute);
266         }
267         return false;
268     }
269 
270     /**
271      * Return true if the receiver wants a <code>Format.Field</code> value and
272      * <code>attribute</code> is equal to it, or true if the receiver
273      * represents an inteter constant and <code>field</code> equals it.
274      */
matchesField(Format.Field attribute, int field)275     private boolean matchesField(Format.Field attribute, int field) {
276         if (this.attribute != null) {
277             return this.attribute.equals(attribute);
278         }
279         return (field == this.field);
280     }
281 
282 
283     /**
284      * An implementation of FieldDelegate that will adjust the begin/end
285      * of the FieldPosition if the arguments match the field of
286      * the FieldPosition.
287      */
288     private class Delegate implements Format.FieldDelegate {
289         /**
290          * Indicates whether the field has been  encountered before. If this
291          * is true, and <code>formatted</code> is invoked, the begin/end
292          * are not updated.
293          */
294         private boolean encounteredField;
295 
formatted(Format.Field attr, Object value, int start, int end, StringBuffer buffer)296         public void formatted(Format.Field attr, Object value, int start,
297                               int end, StringBuffer buffer) {
298             if (!encounteredField && matchesField(attr)) {
299                 setBeginIndex(start);
300                 setEndIndex(end);
301                 encounteredField = (start != end);
302             }
303         }
304 
formatted(int fieldID, Format.Field attr, Object value, int start, int end, StringBuffer buffer)305         public void formatted(int fieldID, Format.Field attr, Object value,
306                               int start, int end, StringBuffer buffer) {
307             if (!encounteredField && matchesField(attr, fieldID)) {
308                 setBeginIndex(start);
309                 setEndIndex(end);
310                 encounteredField = (start != end);
311             }
312         }
313     }
314 }
315