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  * @since 1.1

    72  * @see         java.text.Format

    73  */

    74 public class FieldPosition {

    75 

    76     /**

    77      * Input: Desired field to determine start and end offsets for.

    78      * The meaning depends on the subclass of Format.

    79      */

    80     int field = 0;

    81 

    82     /**

    83      * Output: End offset of field in text.

    84      * If the field does not occur in the text, 0 is returned.

    85      */

    86     int endIndex = 0;

    87 

    88     /**

    89      * Output: Start offset of field in text.

    90      * If the field does not occur in the text, 0 is returned.

    91      */

    92     int beginIndex = 0;

    93 

    94     /**

    95      * Desired field this FieldPosition is for.

    96      */

    97     private Format.Field attribute;

    98 

    99     /**

   100      * Creates a FieldPosition object for the given field.  Fields are

   101      * identified by constants, whose names typically end with _FIELD,

   102      * in the various subclasses of Format.

   103      *

   104      * @param field the field identifier

   105      * @see java.text.NumberFormat#INTEGER_FIELD

   106      * @see java.text.NumberFormat#FRACTION_FIELD

   107      * @see java.text.DateFormat#YEAR_FIELD

   108      * @see java.text.DateFormat#MONTH_FIELD

   109      */

   110     public FieldPosition(int field) {

   111         this.field = field;

   112     }

   113 

   114     /**

   115      * Creates a FieldPosition object for the given field constant. Fields are

   116      * identified by constants defined in the various <code>Format</code>

   117      * subclasses. This is equivalent to calling

   118      * <code>new FieldPosition(attribute, -1)</code>.

   119      *

   120      * @param attribute Format.Field constant identifying a field

   121      * @since 1.4

   122      */

   123     public FieldPosition(Format.Field attribute) {

   124         this(attribute, -1);

   125     }

   126 

   127     /**

   128      * Creates a <code>FieldPosition</code> object for the given field.

   129      * The field is identified by an attribute constant from one of the

   130      * <code>Field</code> subclasses as well as an integer field ID

   131      * defined by the <code>Format</code> subclasses. <code>Format</code>

   132      * subclasses that are aware of <code>Field</code> should give precedence

   133      * to <code>attribute</code> and ignore <code>fieldID</code> if

   134      * <code>attribute</code> is not null. However, older <code>Format</code>

   135      * subclasses may not be aware of <code>Field</code> and rely on

   136      * <code>fieldID</code>. If the field has no corresponding integer

   137      * constant, <code>fieldID</code> should be -1.

   138      *

   139      * @param attribute Format.Field constant identifying a field

   140      * @param fieldID integer constant identifying a field

   141      * @since 1.4

   142      */

   143     public FieldPosition(Format.Field attribute, int fieldID) {

   144         this.attribute = attribute;

   145         this.field = fieldID;

   146     }

   147 

   148     /**

   149      * Returns the field identifier as an attribute constant

   150      * from one of the <code>Field</code> subclasses. May return null if

   151      * the field is specified only by an integer field ID.

   152      *

   153      * @return Identifier for the field

   154      * @since 1.4

   155      */

   156     public Format.Field getFieldAttribute() {

   157         return attribute;

   158     }

   159 

   160     /**

   161      * Retrieves the field identifier.

   162      *

   163      * @return the field identifier

   164      */

   165     public int getField() {

   166         return field;

   167     }

   168 

   169     /**

   170      * Retrieves the index of the first character in the requested field.

   171      *

   172      * @return the begin index

   173      */

   174     public int getBeginIndex() {

   175         return beginIndex;

   176     }

   177 

   178     /**

   179      * Retrieves the index of the character following the last character in the

   180      * requested field.

   181      *

   182      * @return the end index

   183      */

   184     public int getEndIndex() {

   185         return endIndex;

   186     }

   187 

   188     /**

   189      * Sets the begin index.  For use by subclasses of Format.

   190      *

   191      * @param bi the begin index

   192      * @since 1.2

   193      */

   194     public void setBeginIndex(int bi) {

   195         beginIndex = bi;

   196     }

   197 

   198     /**

   199      * Sets the end index.  For use by subclasses of Format.

   200      *

   201      * @param ei the end index

   202      * @since 1.2

   203      */

   204     public void setEndIndex(int ei) {

   205         endIndex = ei;

   206     }

   207 

   208     /**

   209      * Returns a <code>Format.FieldDelegate</code> instance that is associated

   210      * with the FieldPosition. When the delegate is notified of the same

   211      * field the FieldPosition is associated with, the begin/end will be

   212      * adjusted.

   213      */

   214     Format.FieldDelegate getFieldDelegate() {

   215         return new Delegate();

   216     }

   217 

   218     /**

   219      * Overrides equals

   220      */

   221     public boolean equals(Object obj)

   222     {

   223         if (obj == null) return false;

   224         if (!(obj instanceof FieldPosition))

   225             return false;

   226         FieldPosition other = (FieldPosition) obj;

   227         if (attribute == null) {

   228             if (other.attribute != null) {

   229                 return false;

   230             }

   231         }

   232         else if (!attribute.equals(other.attribute)) {

   233             return false;

   234         }

   235         return (beginIndex == other.beginIndex

   236             && endIndex == other.endIndex

   237             && field == other.field);

   238     }

   239 

   240     /**

   241      * Returns a hash code for this FieldPosition.

   242      * @return a hash code value for this object

   243      */

   244     public int hashCode() {

   245         return (field << 24) | (beginIndex << 16) | endIndex;

   246     }

   247 

   248     /**

   249      * Return a string representation of this FieldPosition.

   250      * @return  a string representation of this object

   251      */

   252     public String toString() {

   253         return getClass().getName() +

   254             "[field=" + field + ",attribute=" + attribute +

   255             ",beginIndex=" + beginIndex +

   256             ",endIndex=" + endIndex + ']';

   257     }

   258 

   259 

   260     /**

   261      * Return true if the receiver wants a <code>Format.Field</code> value and

   262      * <code>attribute</code> is equal to it.

   263      */

   264     private boolean matchesField(Format.Field attribute) {

   265         if (this.attribute != null) {

   266             return this.attribute.equals(attribute);

   267         }

   268         return false;

   269     }

   270 

   271     /**

   272      * Return true if the receiver wants a <code>Format.Field</code> value and

   273      * <code>attribute</code> is equal to it, or true if the receiver

   274      * represents an inteter constant and <code>field</code> equals it.

   275      */

   276     private boolean matchesField(Format.Field attribute, int field) {

   277         if (this.attribute != null) {

   278             return this.attribute.equals(attribute);

   279         }

   280         return (field == this.field);

   281     }

   282 

   283 

   284     /**

   285      * An implementation of FieldDelegate that will adjust the begin/end

   286      * of the FieldPosition if the arguments match the field of

   287      * the FieldPosition.

   288      */

   289     private class Delegate implements Format.FieldDelegate {

   290         /**

   291          * Indicates whether the field has been  encountered before. If this

   292          * is true, and <code>formatted</code> is invoked, the begin/end

   293          * are not updated.

   294          */

   295         private boolean encounteredField;

   296 

   297         public void formatted(Format.Field attr, Object value, int start,

   298                               int end, StringBuffer buffer) {

   299             if (!encounteredField && matchesField(attr)) {

   300                 setBeginIndex(start);

   301                 setEndIndex(end);

   302                 encounteredField = (start != end);

   303             }

   304         }

   305 

   306         public void formatted(int fieldID, Format.Field attr, Object value,

   307                               int start, int end, StringBuffer buffer) {

   308             if (!encounteredField && matchesField(attr, fieldID)) {

   309                 setBeginIndex(start);

   310                 setEndIndex(end);

   311                 encounteredField = (start != end);

   312             }

   313         }

   314     }

   315 }