1 /*
2  * Copyright (c) 2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef DATE_TIME_FORMAT_H
17 #define DATE_TIME_FORMAT_H
18 
19 /**
20 * @addtogroup I18N
21 * @{
22 *
23 * @brief Provides functions related to internationalization (i18n), with which you can format date, time and numbers.
24 *
25 * @since 2.2
26 * @version 1.0
27 */
28 
29 /**
30 * @file date_time_format.h
31 *
32 * @brief Declares functions for formatting time and obtaining the name for a month or a day of the week,
33     and an AM/PM marker.
34 *
35 * Example code: \n
36 * Creating a <b>LocaleInfo</b> instance: \n
37 * {@code LocaleInfo locale("zh", "Hans", "CN"); // zh indicates the language , Hans indicates
38     the script, and CN indicates the country.
39 * Creating a <b>DateTimeFormat</b> instance: \n
40 * {@code DateTimeFormat formatter(AvailableDateTimeFormatPattern::HOUR_MINUTE, locale);}
41 * Formatting data: \n
42 * {@code
43 *     time_t time = 3600 * 3;
44 *     std::string zoneInfo = "+1:00"; // UTC + 1;
45 *     std::string out; // Save the formatting result in <b>out</b>.
46 *     Ii8nStatus status = Ii8nStatus::ISUCCESS;
47 *     formatter.Format(time, zoneInfo, out, status);}
48 * Output: \n
49 *     4:00
50 *
51 * @since 2.2
52 * @version 1.0
53 */
54 
55 #include <string>
56 #include "date_time_format_impl.h"
57 #include "types.h"
58 #include "locale_info.h"
59 #include "number_format.h"
60 #include "time.h"
61 
62 namespace OHOS {
63 namespace I18N {
64 class DateTimeFormat {
65 public:
66     /**
67     * @brief A constructor used to create a <b>DateTimeFormat</b> instance with specified pattern and locale.
68     *
69     * @param requestPattern Indicates the specified pattern for formatting.
70     * @param locale Indicates the specified locale.
71     * @since 2.2
72     * @version 1.0
73     */
74     DateTimeFormat(AvailableDateTimeFormatPattern requestPattern, const LocaleInfo &locale);
75 
76     /**
77     * @brief A destructor used to delete the <b>DateTimeFormat</b> instance.
78     *
79     * @since 2.2
80     * @version 1.0
81     */
82     ~DateTimeFormat();
83 
84     /**
85     * @brief Performs an initialization to load data.
86     *
87     * @return Returns <b>true</b> if the initialization is successful; returns <b>false</b> otherwise.
88     * @since 2.2
89     * @version 1.0
90     */
91     bool Init();
92 
93     /**
94     * @brief Formats a time value, number of seconds elapsed since the Unix epoch (00:00:00 UTC on 1 January 1970),
95     *   into a string based on a pattern.
96     *
97     * @param cal Indicates the time value to format.
98     * @param zoneInfo Indicates the time zone information in the <b>+/-ab:cd</b> pattern. <b>+</b> indicates
99     *   that the time zone offset is a positive value, <b>-</b> indicates that the time zone offset is a negative value,
100     *   and <b>ab:cd</b> indicates <b>hour:minute</b>.
101     * @param appendTo Used to save the formatting result.
102     * @param status Indicates the formatting status.
103     * @since 2.2
104     * @version 1.0
105     */
106     void Format(const time_t &cal, const std::string &zoneInfo, std::string &appendTo, I18nStatus &status);
107 
108     /**
109     * @brief Applies a pattern for this formatting.
110     *
111     * @param pattern Indicates the pattern to apply.
112     * @since 2.2
113     * @version 1.0
114     */
115     void ApplyPattern(const AvailableDateTimeFormatPattern &pattern);
116 
117     /**
118     * @brief Obtains the name for a day of the week based on the specified <b>index</b> and <b>type</b>.
119     *
120     * @param index Indicates the index for the name of a day of the week. The values <b>0</b> to <b>6</b>
121     *   indicate <b>Sunday</b> to <b>Saturday</b>, respectively.
122     * @param type Indicates the type of a day of the week, as enumerated in {@link DateTimeDataType}.
123     * @return Returns the name for a day of the week.
124     * @since 2.2
125     * @version 1.0
126     */
127     std::string GetWeekName(const int32_t &index, DateTimeDataType type);
128 
129     /**
130     * @brief Obtains the month name based on the specified <b>index</b> and <b>type</b>.
131     *
132     * @param index Indicates the index for the month name. The values <b>0</b> to <b>11</b>
133     *   indicate <b>January</b> to <b>December</b>, respectively.
134     * @param type Indicates the month type, as enumerated in {@link DateTimeDataType}.
135     * @return Returns the month name.
136     * @since 2.2
137     * @version 1.0
138     */
139     std::string GetMonthName(const int32_t &index, DateTimeDataType type);
140 
141     /**
142     * @brief Obtains the AM/PM marker based on the specified <b>index</b> and <b>type</b>.
143     *
144     * @param index Indicates the index for the AM/PM marker. The value <b>0</b> indicates the AM marker,
145     *   and <b>1</b> indicates the PM marker.
146     * @param type Indicates the AM/PM marker type, as enumerated in {@link DateTimeDataType}.
147     * @return Returns the AM/PM marker.
148     * @since 2.2
149     * @version 1.0
150     */
151     std::string GetAmPmMarker(const int32_t &index,
152         DateTimeDataType type = DateTimeDataType::STANDALONE_ABBR);
153 
154     /**
155     * @brief Formats a time value, number of seconds elapsed since the Unix epoch (00:00:00 UTC on 1 January 1970),
156     *   into a string based on 12-hour:minute:second or 12-hour:minute, without am/pm.
157     *
158     * @param cal Indicates the time value to format.
159     * @param zoneInfo Indicates the time zone information in the <b>+/-ab:cd</b> pattern. <b>+</b> indicates
160     *   that the time zone offset is a positive value, <b>-</b> indicates that the time zone offset is a negative value,
161     *   and <b>ab:cd</b> indicates <b>hour:minute</b>.
162     * @param appendTo Used to save the formatting result.
163     * @param status Indicates the formatting status.
164     * @return Returns 1 or -1 if am/pm markers should be put at the beginning or end of the returned string when we call
165     *   format with HOUR12_MINUTE_SECOND, returns 0 if no am/pm markers should be added.
166     */
167     int8_t Get12HourTimeWithoutAmpm(const time_t &cal, const std::string &zoneInfo,
168         std::string &appendTo, I18nStatus &status);
169 
170     /**
171     * @brief format a elapsed duration in the pattern indicated by the type.
172     *
173     * @param milliseconds indicates the time to be formatted.
174     * @param type pattern used to format string.
175     * @param status Indicates the formatting status.
176     * @return the formatted string.
177     */
178     std::string FormatElapsedDuration(int32_t milliseconds, ElapsedPatternType type, I18nStatus &status);
179 
180     /**
181     * @brief Obtains the time separator.
182     *
183     * @return Returns the time separator.
184     * @since 2.2
185     * @version 1.0
186     */
187     std::string GetTimeSeparator();
188 private:
189     DateTimeFormatImpl *impl = nullptr;
190     LocaleInfo locale;
191     AvailableDateTimeFormatPattern requestPattern;
192 };
193 } // namespace I18N
194 } // namespace OHOS
195 /** @} */
196 #endif
197