1 /*
2 * Copyright 2018 Andrew Rucker Jones.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.opencsv.bean;
17
18 import java.lang.annotation.*;
19 import java.math.RoundingMode;
20
21 /**
22 * This annotation indicates that the destination field is a number that is
23 * specially formatted.
24 * Numbers that have no more formatting than that which comes with a locale (or
25 * the default locale) do not require this annotation. If a locale is specified
26 * in the attendant CSV binding annotation ({@link CsvBindByName},
27 * {@link CsvBindByPosition}, etc.), it is used for the conversion. The
28 * following types are supported:
29 * <ul><li>byte / {@link java.lang.Byte}</li>
30 * <li>double / {@link java.lang.Double}</li>
31 * <li>float / {@link java.lang.Float}</li>
32 * <li>int / {@link java.lang.Integer}</li>
33 * <li>long / {@link java.lang.Long}</li>
34 * <li>short / {@link java.lang.Short}</li>
35 * <li>{@link java.math.BigDecimal}</li>
36 * <li>{@link java.math.BigInteger}</li></ul>
37 *
38 * @since 4.2
39 * @author Andrew Rucker Jones
40 */
41 @Documented
42 @Retention(RetentionPolicy.RUNTIME)
43 @Target(ElementType.FIELD)
44 @Repeatable(CsvNumbers.class)
45 public @interface CsvNumber {
46
47 /**
48 * A decimal format string.
49 * This must be a localized pattern understood by
50 * {@link java.text.DecimalFormat}. The locale is gleaned from one of the
51 * other CSV-related annotations if present there, or failing that, is the
52 * default locale for the JVM. If your code might run under different
53 * locales, you are strongly encouraged to always specify a locale for
54 * conversions, otherwise your code will behave unpredictably.
55 *
56 * @return The format string for parsing input
57 */
58 String value();
59
60 /**
61 * Whether or not the same format string is used for writing as for reading.
62 * If this is true, {@link #value()} is used for both reading and writing
63 * and {@link #writeFormat()} is ignored.
64 *
65 * @return Whether the read format is used for writing as well
66 * @since 5.0
67 */
68 boolean writeFormatEqualsReadFormat() default true;
69
70 /**
71 * A number format string.
72 * The default value is blank and only exists to make sure the parameter is
73 * optional.
74 *
75 * @return The format string for formatting output
76 * @see #value()
77 * @see #writeFormatEqualsReadFormat()
78 * @since 5.0
79 */
80 String writeFormat() default "";
81
82 /**
83 * A profile can be used to annotate the same field differently for
84 * different inputs or outputs.
85 * <p>Perhaps you have multiple input sources, and they all use different
86 * header names or positions for the same data. With profiles, you don't
87 * have to create different beans with the same fields and different
88 * annotations for each input. Simply annotate the same field multiple
89 * times and specify the profile when you parse the input.</p>
90 * <p>The same applies to output: if you want to be able to represent the
91 * same data in multiple CSV formats (that is, with different headers or
92 * orders), annotate the bean fields multiple times with different profiles
93 * and specify which profile you want to use on writing.</p>
94 * <p>Results are undefined if profile names are not unique.</p>
95 * <p>If the same configuration applies to multiple profiles, simply list
96 * all applicable profile names here. This parameter is an array of
97 * strings.</p>
98 * <p>The empty string, which is the default value, specifies the default
99 * profile and will be used if no annotation for the specific profile
100 * being used can be found, or if no profile is specified.</p>
101 *
102 * @return The names of the profiles this configuration is for
103 * @since 5.4
104 */
105 String[] profiles() default "";
106
107 /**
108 * The rounding mode for formatting decimals.
109 * The default rounding mode, in keeping with {@link java.text.DecimalFormat}'s
110 * default, is {@link java.math.RoundingMode.HALF_EVEN}.
111 *
112 * @return The rounding pattern to be used if decimals are formatted
113 * @since 5.9
114 */
115 RoundingMode roundingMode() default RoundingMode.HALF_EVEN;
116 }