View Javadoc
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      */
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      */
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      */
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      */
155     public Format.Field getFieldAttribute() {
156         return attribute;
157     }
158 
159     /**
160      * Retrieves the field identifier.
161      *
162      * @return the field identifier
163      */
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      */
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      */
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      */
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      */
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      */
213     Format.FieldDelegate getFieldDelegate() {
214         return new Delegate();
215     }
216 
217     /**
218      * Overrides equals
219      */
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      */
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      */
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      */
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      */
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 
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 
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 }