ICU 74.1 74.1
Namespaces | Typedefs | Enumerations | Functions
udatpg.h File Reference

C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h). More...

#include "unicode/utypes.h"
#include "unicode/udat.h"
#include "unicode/uenum.h"
#include "unicode/localpointer.h"

Go to the source code of this file.

Namespaces

namespace  icu
 File coll.h.
 

Typedefs

typedef void * UDateTimePatternGenerator
 Opaque type for a date/time pattern generator object. More...
 
typedef enum UDateTimePatternField UDateTimePatternField
 Field number constants for udatpg_getAppendItemFormats() and similar functions. More...
 
typedef enum UDateTimePGDisplayWidth UDateTimePGDisplayWidth
 Field display name width constants for udatpg_getFieldDisplayName(). More...
 
typedef enum UDateTimePatternMatchOptions UDateTimePatternMatchOptions
 Masks to control forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise). More...
 
typedef enum UDateTimePatternConflict UDateTimePatternConflict
 Status return values from udatpg_addPattern(). More...
 

Enumerations

enum  UDateTimePatternField {
  UDATPG_ERA_FIELD , UDATPG_YEAR_FIELD , UDATPG_QUARTER_FIELD , UDATPG_MONTH_FIELD ,
  UDATPG_WEEK_OF_YEAR_FIELD , UDATPG_WEEK_OF_MONTH_FIELD , UDATPG_WEEKDAY_FIELD , UDATPG_DAY_OF_YEAR_FIELD ,
  UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD , UDATPG_DAY_FIELD , UDATPG_DAYPERIOD_FIELD , UDATPG_HOUR_FIELD ,
  UDATPG_MINUTE_FIELD , UDATPG_SECOND_FIELD , UDATPG_FRACTIONAL_SECOND_FIELD , UDATPG_ZONE_FIELD ,
  UDATPG_FIELD_COUNT
}
 Field number constants for udatpg_getAppendItemFormats() and similar functions. More...
 
enum  UDateTimePGDisplayWidth { UDATPG_WIDE , UDATPG_ABBREVIATED , UDATPG_NARROW }
 Field display name width constants for udatpg_getFieldDisplayName(). More...
 
enum  UDateTimePatternMatchOptions {
  UDATPG_MATCH_NO_OPTIONS = 0 , UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD , UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD , UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD ,
  UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1
}
 Masks to control forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise). More...
 
enum  UDateTimePatternConflict { UDATPG_NO_CONFLICT , UDATPG_BASE_CONFLICT , UDATPG_CONFLICT , UDATPG_CONFLICT_COUNT }
 Status return values from udatpg_addPattern(). More...
 

Functions

U_CAPI UDateTimePatternGeneratorudatpg_open (const char *locale, UErrorCode *pErrorCode)
 Open a generator according to a given locale. More...
 
U_CAPI UDateTimePatternGeneratorudatpg_openEmpty (UErrorCode *pErrorCode)
 Open an empty generator, to be constructed with udatpg_addPattern(...) etc. More...
 
U_CAPI void udatpg_close (UDateTimePatternGenerator *dtpg)
 Close a generator. More...
 
U_CAPI UDateTimePatternGeneratorudatpg_clone (const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode)
 Create a copy pf a generator. More...
 
U_CAPI int32_t udatpg_getBestPattern (UDateTimePatternGenerator *dtpg, const UChar *skeleton, int32_t length, UChar *bestPattern, int32_t capacity, UErrorCode *pErrorCode)
 Get the best pattern matching the input skeleton. More...
 
U_CAPI int32_t udatpg_getBestPatternWithOptions (UDateTimePatternGenerator *dtpg, const UChar *skeleton, int32_t length, UDateTimePatternMatchOptions options, UChar *bestPattern, int32_t capacity, UErrorCode *pErrorCode)
 Get the best pattern matching the input skeleton. More...
 
U_CAPI int32_t udatpg_getSkeleton (UDateTimePatternGenerator *unusedDtpg, const UChar *pattern, int32_t length, UChar *skeleton, int32_t capacity, UErrorCode *pErrorCode)
 Get a unique skeleton from a given pattern. More...
 
U_CAPI int32_t udatpg_getBaseSkeleton (UDateTimePatternGenerator *unusedDtpg, const UChar *pattern, int32_t length, UChar *baseSkeleton, int32_t capacity, UErrorCode *pErrorCode)
 Get a unique base skeleton from a given pattern. More...
 
U_CAPI UDateTimePatternConflict udatpg_addPattern (UDateTimePatternGenerator *dtpg, const UChar *pattern, int32_t patternLength, UBool override, UChar *conflictingPattern, int32_t capacity, int32_t *pLength, UErrorCode *pErrorCode)
 Adds a pattern to the generator. More...
 
U_CAPI void udatpg_setAppendItemFormat (UDateTimePatternGenerator *dtpg, UDateTimePatternField field, const UChar *value, int32_t length)
 An AppendItem format is a pattern used to append a field if there is no good match. More...
 
U_CAPI const UCharudatpg_getAppendItemFormat (const UDateTimePatternGenerator *dtpg, UDateTimePatternField field, int32_t *pLength)
 Getter corresponding to setAppendItemFormat. More...
 
U_CAPI void udatpg_setAppendItemName (UDateTimePatternGenerator *dtpg, UDateTimePatternField field, const UChar *value, int32_t length)
 Set the name of field, eg "era" in English for ERA. More...
 
U_CAPI const UCharudatpg_getAppendItemName (const UDateTimePatternGenerator *dtpg, UDateTimePatternField field, int32_t *pLength)
 Getter corresponding to setAppendItemNames. More...
 
U_CAPI int32_t udatpg_getFieldDisplayName (const UDateTimePatternGenerator *dtpg, UDateTimePatternField field, UDateTimePGDisplayWidth width, UChar *fieldName, int32_t capacity, UErrorCode *pErrorCode)
 The general interface to get a display name for a particular date/time field, in one of several possible display widths. More...
 
U_CAPI void udatpg_setDateTimeFormat (const UDateTimePatternGenerator *dtpg, const UChar *dtFormat, int32_t length)
 The DateTimeFormat is a message format pattern used to compose date and time patterns. More...
 
U_CAPI const UCharudatpg_getDateTimeFormat (const UDateTimePatternGenerator *dtpg, int32_t *pLength)
 Getter corresponding to setDateTimeFormat. More...
 
U_CAPI void udatpg_setDateTimeFormatForStyle (UDateTimePatternGenerator *udtpg, UDateFormatStyle style, const UChar *dateTimeFormat, int32_t length, UErrorCode *pErrorCode)
 dateTimeFormats are message patterns used to compose combinations of date and time patterns. More...
 
U_CAPI const UCharudatpg_getDateTimeFormatForStyle (const UDateTimePatternGenerator *udtpg, UDateFormatStyle style, int32_t *pLength, UErrorCode *pErrorCode)
 Getter corresponding to udatpg_setDateTimeFormatForStyle. More...
 
U_CAPI void udatpg_setDecimal (UDateTimePatternGenerator *dtpg, const UChar *decimal, int32_t length)
 The decimal value is used in formatting fractions of seconds. More...
 
U_CAPI const UCharudatpg_getDecimal (const UDateTimePatternGenerator *dtpg, int32_t *pLength)
 Getter corresponding to setDecimal. More...
 
U_CAPI int32_t udatpg_replaceFieldTypes (UDateTimePatternGenerator *dtpg, const UChar *pattern, int32_t patternLength, const UChar *skeleton, int32_t skeletonLength, UChar *dest, int32_t destCapacity, UErrorCode *pErrorCode)
 Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton. More...
 
U_CAPI int32_t udatpg_replaceFieldTypesWithOptions (UDateTimePatternGenerator *dtpg, const UChar *pattern, int32_t patternLength, const UChar *skeleton, int32_t skeletonLength, UDateTimePatternMatchOptions options, UChar *dest, int32_t destCapacity, UErrorCode *pErrorCode)
 Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton. More...
 
U_CAPI UEnumerationudatpg_openSkeletons (const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode)
 Return a UEnumeration list of all the skeletons in canonical form. More...
 
U_CAPI UEnumerationudatpg_openBaseSkeletons (const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode)
 Return a UEnumeration list of all the base skeletons in canonical form. More...
 
U_CAPI const UCharudatpg_getPatternForSkeleton (const UDateTimePatternGenerator *dtpg, const UChar *skeleton, int32_t skeletonLength, int32_t *pLength)
 Get the pattern corresponding to a given skeleton. More...
 
U_CAPI UDateFormatHourCycle udatpg_getDefaultHourCycle (const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode)
 Return the default hour cycle for a locale. More...
 

Detailed Description

C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h).

UDateTimePatternGenerator provides flexible generation of date format patterns, like "yy-MM-dd". The user can build up the generator by adding successive patterns. Once that is done, a query can be made using a "skeleton", which is a pattern which just includes the desired fields and lengths. The generator will return the "best fit" pattern corresponding to that skeleton.

The main method people will use is udatpg_getBestPattern, since normally UDateTimePatternGenerator is pre-built with data from a particular locale. However, generators can be built directly from other data as well.

Issue: may be useful to also have a function that returns the list of fields in a pattern, in order, since we have that internally. That would be useful for getting the UI order of field elements.

Definition in file udatpg.h.

Typedef Documentation

◆ UDateTimePatternConflict

Status return values from udatpg_addPattern().

Stable:
ICU 3.8

◆ UDateTimePatternField

Field number constants for udatpg_getAppendItemFormats() and similar functions.

These constants are separate from UDateFormatField despite semantic overlap because some fields are merged for the date/time pattern generator.

Stable:
ICU 3.8

◆ UDateTimePatternGenerator

Opaque type for a date/time pattern generator object.

Stable:
ICU 3.8

Definition at line 51 of file udatpg.h.

◆ UDateTimePatternMatchOptions

Masks to control forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise).

These may be combined to force the length of multiple fields. Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions.

Stable:
ICU 4.4

◆ UDateTimePGDisplayWidth

Field display name width constants for udatpg_getFieldDisplayName().

Stable:
ICU 61

Enumeration Type Documentation

◆ UDateTimePatternConflict

Status return values from udatpg_addPattern().

Stable:
ICU 3.8
Enumerator
UDATPG_NO_CONFLICT 
Stable:
ICU 3.8
UDATPG_BASE_CONFLICT 
Stable:
ICU 3.8
UDATPG_CONFLICT 
Stable:
ICU 3.8
UDATPG_CONFLICT_COUNT 

One more than the highest normal UDateTimePatternConflict value.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 143 of file udatpg.h.

◆ UDateTimePatternField

Field number constants for udatpg_getAppendItemFormats() and similar functions.

These constants are separate from UDateFormatField despite semantic overlap because some fields are merged for the date/time pattern generator.

Stable:
ICU 3.8
Enumerator
UDATPG_ERA_FIELD 
Stable:
ICU 3.8
UDATPG_YEAR_FIELD 
Stable:
ICU 3.8
UDATPG_QUARTER_FIELD 
Stable:
ICU 3.8
UDATPG_MONTH_FIELD 
Stable:
ICU 3.8
UDATPG_WEEK_OF_YEAR_FIELD 
Stable:
ICU 3.8
UDATPG_WEEK_OF_MONTH_FIELD 
Stable:
ICU 3.8
UDATPG_WEEKDAY_FIELD 
Stable:
ICU 3.8
UDATPG_DAY_OF_YEAR_FIELD 
Stable:
ICU 3.8
UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD 
Stable:
ICU 3.8
UDATPG_DAY_FIELD 
Stable:
ICU 3.8
UDATPG_DAYPERIOD_FIELD 
Stable:
ICU 3.8
UDATPG_HOUR_FIELD 
Stable:
ICU 3.8
UDATPG_MINUTE_FIELD 
Stable:
ICU 3.8
UDATPG_SECOND_FIELD 
Stable:
ICU 3.8
UDATPG_FRACTIONAL_SECOND_FIELD 
Stable:
ICU 3.8
UDATPG_ZONE_FIELD 
Stable:
ICU 3.8
UDATPG_FIELD_COUNT 

One more than the highest normal UDateTimePatternField value.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 59 of file udatpg.h.

◆ UDateTimePatternMatchOptions

Masks to control forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise).

These may be combined to force the length of multiple fields. Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions.

Stable:
ICU 4.4
Enumerator
UDATPG_MATCH_NO_OPTIONS 
Stable:
ICU 4.4
UDATPG_MATCH_HOUR_FIELD_LENGTH 
Stable:
ICU 4.4
UDATPG_MATCH_MINUTE_FIELD_LENGTH 
Internal:
Do not use. This API is for internal use only. ICU 4.4
UDATPG_MATCH_SECOND_FIELD_LENGTH 
Internal:
Do not use. This API is for internal use only. ICU 4.4
UDATPG_MATCH_ALL_FIELDS_LENGTH 
Stable:
ICU 4.4

Definition at line 124 of file udatpg.h.

◆ UDateTimePGDisplayWidth

Field display name width constants for udatpg_getFieldDisplayName().

Stable:
ICU 61
Enumerator
UDATPG_WIDE 
Stable:
ICU 61
UDATPG_ABBREVIATED 
Stable:
ICU 61
UDATPG_NARROW 
Stable:
ICU 61

Definition at line 108 of file udatpg.h.

Function Documentation

◆ udatpg_addPattern()

U_CAPI UDateTimePatternConflict udatpg_addPattern ( UDateTimePatternGenerator dtpg,
const UChar pattern,
int32_t  patternLength,
UBool  override,
UChar conflictingPattern,
int32_t  capacity,
int32_t *  pLength,
UErrorCode pErrorCode 
)

Adds a pattern to the generator.

If the pattern has the same skeleton as an existing pattern, and the override parameter is set, then the previous value is overridden. Otherwise, the previous value is retained. In either case, the conflicting status is set and previous vale is stored in conflicting pattern.

Note that single-field patterns (like "MMM") are automatically added, and don't need to be added explicitly!

Parameters
dtpga pointer to UDateTimePatternGenerator.
patterninput pattern, such as "dd/MMM"
patternLengththe length of pattern.
overrideWhen existing values are to be overridden use true, otherwise use false.
conflictingPatternPrevious pattern with the same skeleton.
capacitythe capacity of conflictingPattern.
pLengtha pointer to the length of conflictingPattern.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
conflicting status. The value could be UDATPG_NO_CONFLICT, UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
Stable:
ICU 3.8

◆ udatpg_clone()

U_CAPI UDateTimePatternGenerator * udatpg_clone ( const UDateTimePatternGenerator dtpg,
UErrorCode pErrorCode 
)

Create a copy pf a generator.

Parameters
dtpga pointer to UDateTimePatternGenerator to be copied.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
a pointer to a new UDateTimePatternGenerator.
Stable:
ICU 3.8

◆ udatpg_close()

U_CAPI void udatpg_close ( UDateTimePatternGenerator dtpg)

Close a generator.

Parameters
dtpga pointer to UDateTimePatternGenerator.
Stable:
ICU 3.8

◆ udatpg_getAppendItemFormat()

U_CAPI const UChar * udatpg_getAppendItemFormat ( const UDateTimePatternGenerator dtpg,
UDateTimePatternField  field,
int32_t *  pLength 
)

Getter corresponding to setAppendItemFormat.

Values below 0 or at or above UDATPG_FIELD_COUNT are illegal arguments.

Parameters
dtpgA pointer to UDateTimePatternGenerator.
fieldUDateTimePatternField, such as UDATPG_ERA_FIELD
pLengthA pointer that will receive the length of appendItemFormat.
Returns
appendItemFormat for field.
Stable:
ICU 3.8

◆ udatpg_getAppendItemName()

U_CAPI const UChar * udatpg_getAppendItemName ( const UDateTimePatternGenerator dtpg,
UDateTimePatternField  field,
int32_t *  pLength 
)

Getter corresponding to setAppendItemNames.

Values below 0 or at or above UDATPG_FIELD_COUNT are illegal arguments. Note: The more general function for getting date/time field display names is udatpg_getFieldDisplayName.

Parameters
dtpga pointer to UDateTimePatternGenerator.
fieldUDateTimePatternField, such as UDATPG_ERA_FIELD
pLengthA pointer that will receive the length of the name for field.
Returns
name for field
See also
udatpg_getFieldDisplayName
Stable:
ICU 3.8

◆ udatpg_getBaseSkeleton()

U_CAPI int32_t udatpg_getBaseSkeleton ( UDateTimePatternGenerator unusedDtpg,
const UChar pattern,
int32_t  length,
UChar baseSkeleton,
int32_t  capacity,
UErrorCode pErrorCode 
)

Get a unique base skeleton from a given pattern.

This is the same as the skeleton, except that differences in length are minimized so as to only preserve the difference between string and numeric form. So for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd" (notice the single d).

Note that this function uses a non-const UDateTimePatternGenerator: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Parameters
unusedDtpga pointer to UDateTimePatternGenerator. This parameter is no longer used. Callers may pass NULL.
patterninput pattern, such as "dd/MMM".
lengththe length of pattern.
baseSkeletonsuch as "Md"
capacitythe capacity of base skeleton.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
the length of baseSkeleton.
Stable:
ICU 3.8

◆ udatpg_getBestPattern()

U_CAPI int32_t udatpg_getBestPattern ( UDateTimePatternGenerator dtpg,
const UChar skeleton,
int32_t  length,
UChar bestPattern,
int32_t  capacity,
UErrorCode pErrorCode 
)

Get the best pattern matching the input skeleton.

It is guaranteed to have all of the fields in the skeleton.

Note that this function uses a non-const UDateTimePatternGenerator: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Parameters
dtpga pointer to UDateTimePatternGenerator.
skeletonThe skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
lengththe length of skeleton
bestPatternThe best pattern found from the given skeleton.
capacitythe capacity of bestPattern.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
the length of bestPattern.
Stable:
ICU 3.8

◆ udatpg_getBestPatternWithOptions()

U_CAPI int32_t udatpg_getBestPatternWithOptions ( UDateTimePatternGenerator dtpg,
const UChar skeleton,
int32_t  length,
UDateTimePatternMatchOptions  options,
UChar bestPattern,
int32_t  capacity,
UErrorCode pErrorCode 
)

Get the best pattern matching the input skeleton.

It is guaranteed to have all of the fields in the skeleton.

Note that this function uses a non-const UDateTimePatternGenerator: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Parameters
dtpga pointer to UDateTimePatternGenerator.
skeletonThe skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
lengththe length of skeleton
optionsOptions for forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise). For default behavior, use UDATPG_MATCH_NO_OPTIONS.
bestPatternThe best pattern found from the given skeleton.
capacitythe capacity of bestPattern.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
the length of bestPattern.
Stable:
ICU 4.4

◆ udatpg_getDateTimeFormat()

U_CAPI const UChar * udatpg_getDateTimeFormat ( const UDateTimePatternGenerator dtpg,
int32_t *  pLength 
)

Getter corresponding to setDateTimeFormat.

There are four DateTimeFormats in a UDateTimePatternGenerator object, corresponding to date styles UDAT_FULL..UDAT_SHORT. This method gets the style for UDAT_MEDIUM (the default). To get them individually, see udatpg_getDateTimeFormatForStyle.

Parameters
dtpga pointer to UDateTimePatternGenerator.
pLengthA pointer that will receive the length of the format
Returns
dateTimeFormat.
Stable:
ICU 3.8

◆ udatpg_getDateTimeFormatForStyle()

U_CAPI const UChar * udatpg_getDateTimeFormatForStyle ( const UDateTimePatternGenerator udtpg,
UDateFormatStyle  style,
int32_t *  pLength,
UErrorCode pErrorCode 
)

Getter corresponding to udatpg_setDateTimeFormatForStyle.

Parameters
udtpga pointer to the UDateTimePatternGenerator
styleone of UDAT_FULL..UDAT_SHORT. Error if out of range.
pLengtha pointer that will receive the length of the format. May be NULL if length is not desired.
pErrorCodea pointer to the UErrorCode (in/out parameter); if no failure status is already set, it will be set according to result of the function (e.g. U_ILLEGAL_ARGUMENT_ERROR for style out of range).
Returns
pointer to the current dateTimeFormat (0 terminated) for the specified style, or empty string in case of error. The pointer and its contents may no longer be valid if udatpg_setDateTimeFormat is called, or udatpg_setDateTimeFormatForStyle for the same style is called, or the UDateTimePatternGenerator object is closed.
Stable:
ICU 71

◆ udatpg_getDecimal()

U_CAPI const UChar * udatpg_getDecimal ( const UDateTimePatternGenerator dtpg,
int32_t *  pLength 
)

Getter corresponding to setDecimal.

Parameters
dtpga pointer to UDateTimePatternGenerator.
pLengthA pointer that will receive the length of the decimal string.
Returns
corresponding to the decimal point.
Stable:
ICU 3.8

◆ udatpg_getDefaultHourCycle()

U_CAPI UDateFormatHourCycle udatpg_getDefaultHourCycle ( const UDateTimePatternGenerator dtpg,
UErrorCode pErrorCode 
)

Return the default hour cycle for a locale.

Uses the locale that the UDateTimePatternGenerator was initially created with.

Cannot be used on an empty UDateTimePatternGenerator instance.

Parameters
dtpga pointer to UDateTimePatternGenerator.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call. Set to U_UNSUPPORTED_ERROR if used on an empty instance.
Returns
the default hour cycle.
Stable:
ICU 67

◆ udatpg_getFieldDisplayName()

U_CAPI int32_t udatpg_getFieldDisplayName ( const UDateTimePatternGenerator dtpg,
UDateTimePatternField  field,
UDateTimePGDisplayWidth  width,
UChar fieldName,
int32_t  capacity,
UErrorCode pErrorCode 
)

The general interface to get a display name for a particular date/time field, in one of several possible display widths.

Parameters
dtpgA pointer to the UDateTimePatternGenerator object with the localized display names.
fieldThe desired UDateTimePatternField, such as UDATPG_ERA_FIELD.
widthThe desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED.
fieldNameA pointer to a buffer to receive the NULL-terminated display name. If the name fits into fieldName but cannot be NULL-terminated (length == capacity) then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the name doesn't fit into fieldName then the error code is set to U_BUFFER_OVERFLOW_ERROR.
capacityThe size of fieldName (in UChars).
pErrorCodeA pointer to a UErrorCode to receive any errors
Returns
The full length of the name; if greater than capacity, fieldName contains a truncated result.
Stable:
ICU 61

◆ udatpg_getPatternForSkeleton()

U_CAPI const UChar * udatpg_getPatternForSkeleton ( const UDateTimePatternGenerator dtpg,
const UChar skeleton,
int32_t  skeletonLength,
int32_t *  pLength 
)

Get the pattern corresponding to a given skeleton.

Parameters
dtpga pointer to UDateTimePatternGenerator.
skeleton
skeletonLengthpointer to the length of skeleton.
pLengthpointer to the length of return pattern.
Returns
pattern corresponding to a given skeleton.
Stable:
ICU 3.8

◆ udatpg_getSkeleton()

U_CAPI int32_t udatpg_getSkeleton ( UDateTimePatternGenerator unusedDtpg,
const UChar pattern,
int32_t  length,
UChar skeleton,
int32_t  capacity,
UErrorCode pErrorCode 
)

Get a unique skeleton from a given pattern.

For example, both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".

Note that this function uses a non-const UDateTimePatternGenerator: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Parameters
unusedDtpga pointer to UDateTimePatternGenerator. This parameter is no longer used. Callers may pass NULL.
patterninput pattern, such as "dd/MMM".
lengththe length of pattern.
skeletonsuch as "MMMdd"
capacitythe capacity of skeleton.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
the length of skeleton.
Stable:
ICU 3.8

◆ udatpg_open()

U_CAPI UDateTimePatternGenerator * udatpg_open ( const char *  locale,
UErrorCode pErrorCode 
)

Open a generator according to a given locale.

Parameters
locale
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
a pointer to UDateTimePatternGenerator.
Stable:
ICU 3.8

◆ udatpg_openBaseSkeletons()

U_CAPI UEnumeration * udatpg_openBaseSkeletons ( const UDateTimePatternGenerator dtpg,
UErrorCode pErrorCode 
)

Return a UEnumeration list of all the base skeletons in canonical form.

Parameters
dtpga pointer to UDateTimePatternGenerator.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
a UEnumeration list of all the base skeletons The caller must close the object.
Stable:
ICU 3.8

◆ udatpg_openEmpty()

U_CAPI UDateTimePatternGenerator * udatpg_openEmpty ( UErrorCode pErrorCode)

Open an empty generator, to be constructed with udatpg_addPattern(...) etc.

Parameters
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
a pointer to UDateTimePatternGenerator.
Stable:
ICU 3.8

◆ udatpg_openSkeletons()

U_CAPI UEnumeration * udatpg_openSkeletons ( const UDateTimePatternGenerator dtpg,
UErrorCode pErrorCode 
)

Return a UEnumeration list of all the skeletons in canonical form.

Call udatpg_getPatternForSkeleton() to get the corresponding pattern.

Parameters
dtpga pointer to UDateTimePatternGenerator.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call
Returns
a UEnumeration list of all the skeletons The caller must close the object.
Stable:
ICU 3.8

◆ udatpg_replaceFieldTypes()

U_CAPI int32_t udatpg_replaceFieldTypes ( UDateTimePatternGenerator dtpg,
const UChar pattern,
int32_t  patternLength,
const UChar skeleton,
int32_t  skeletonLength,
UChar dest,
int32_t  destCapacity,
UErrorCode pErrorCode 
)

Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.

That is, if you supply a pattern like "d-M H:m", and a skeleton of "MMMMddhhmm", then the input pattern is adjusted to be "dd-MMMM hh:mm". This is used internally to get the best match for the input skeleton, but can also be used externally.

Note that this function uses a non-const UDateTimePatternGenerator: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Parameters
dtpga pointer to UDateTimePatternGenerator.
patternInput pattern
patternLengththe length of input pattern.
skeleton
skeletonLengththe length of input skeleton.
destpattern adjusted to match the skeleton fields widths and subtypes.
destCapacitythe capacity of dest.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
the length of dest.
Stable:
ICU 3.8

◆ udatpg_replaceFieldTypesWithOptions()

U_CAPI int32_t udatpg_replaceFieldTypesWithOptions ( UDateTimePatternGenerator dtpg,
const UChar pattern,
int32_t  patternLength,
const UChar skeleton,
int32_t  skeletonLength,
UDateTimePatternMatchOptions  options,
UChar dest,
int32_t  destCapacity,
UErrorCode pErrorCode 
)

Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.

That is, if you supply a pattern like "d-M H:m", and a skeleton of "MMMMddhhmm", then the input pattern is adjusted to be "dd-MMMM hh:mm". This is used internally to get the best match for the input skeleton, but can also be used externally.

Note that this function uses a non-const UDateTimePatternGenerator: It uses a stateful pattern parser which is set up for each generator object, rather than creating one for each function call. Consecutive calls to this function do not affect each other, but this function cannot be used concurrently on a single generator object.

Parameters
dtpga pointer to UDateTimePatternGenerator.
patternInput pattern
patternLengththe length of input pattern.
skeleton
skeletonLengththe length of input skeleton.
optionsOptions controlling whether the length of specified fields in the pattern are adjusted to match those in the skeleton (when this would not happen otherwise). For default behavior, use UDATPG_MATCH_NO_OPTIONS.
destpattern adjusted to match the skeleton fields widths and subtypes.
destCapacitythe capacity of dest.
pErrorCodea pointer to the UErrorCode which must not indicate a failure before the function call.
Returns
the length of dest.
Stable:
ICU 4.4

◆ udatpg_setAppendItemFormat()

U_CAPI void udatpg_setAppendItemFormat ( UDateTimePatternGenerator dtpg,
UDateTimePatternField  field,
const UChar value,
int32_t  length 
)

An AppendItem format is a pattern used to append a field if there is no good match.

For example, suppose that the input skeleton is "GyyyyMMMd", and there is no matching pattern internally, but there is a pattern matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the G. The way these two are conjoined is by using the AppendItemFormat for G (era). So if that value is, say "{0}, {1}" then the final resulting pattern is "d-MM-yyyy, G".

There are actually three available variables: {0} is the pattern so far, {1} is the element we are adding, and {2} is the name of the element.

This reflects the way that the CLDR data is organized.

Parameters
dtpga pointer to UDateTimePatternGenerator.
fieldUDateTimePatternField, such as UDATPG_ERA_FIELD
valuepattern, such as "{0}, {1}"
lengththe length of value.
Stable:
ICU 3.8

◆ udatpg_setAppendItemName()

U_CAPI void udatpg_setAppendItemName ( UDateTimePatternGenerator dtpg,
UDateTimePatternField  field,
const UChar value,
int32_t  length 
)

Set the name of field, eg "era" in English for ERA.

These are only used if the corresponding AppendItemFormat is used, and if it contains a {2} variable.

This reflects the way that the CLDR data is organized.

Parameters
dtpga pointer to UDateTimePatternGenerator.
fieldUDateTimePatternField
valuename for the field.
lengththe length of value.
Stable:
ICU 3.8

◆ udatpg_setDateTimeFormat()

U_CAPI void udatpg_setDateTimeFormat ( const UDateTimePatternGenerator dtpg,
const UChar dtFormat,
int32_t  length 
)

The DateTimeFormat is a message format pattern used to compose date and time patterns.

The default pattern in the root locale is "{1} {0}", where {1} will be replaced by the date pattern and {0} will be replaced by the time pattern; however, other locales may specify patterns such as "{1}, {0}" or "{1} 'at' {0}", etc.

This is used when the input skeleton contains both date and time fields, but there is not a close match among the added patterns. For example, suppose that this object was created by adding "dd-MMM" and "hh:mm", and its DateTimeFormat is the default "{1} {0}". Then if the input skeleton is "MMMdhmm", there is not an exact match, so the input skeleton is broken up into two components "MMMd" and "hmm". There are close matches for those two skeletons, so the result is put together with this pattern, resulting in "d-MMM h:mm".

There are four DateTimeFormats in a UDateTimePatternGenerator object, corresponding to date styles UDAT_FULL..UDAT_SHORT. This method sets all of them to the specified pattern. To set them individually, see udatpg_setDateTimeFormatForStyle.

Parameters
dtpga pointer to UDateTimePatternGenerator.
dtFormatmessage format pattern, here {1} will be replaced by the date pattern and {0} will be replaced by the time pattern.
lengththe length of dtFormat.
Stable:
ICU 3.8

◆ udatpg_setDateTimeFormatForStyle()

U_CAPI void udatpg_setDateTimeFormatForStyle ( UDateTimePatternGenerator udtpg,
UDateFormatStyle  style,
const UChar dateTimeFormat,
int32_t  length,
UErrorCode pErrorCode 
)

dateTimeFormats are message patterns used to compose combinations of date and time patterns.

There are four length styles, corresponding to the inferred style of the date pattern; these are UDateFormatStyle values:

  • UDAT_FULL (for date pattern with weekday and long month), else
  • UDAT_LONG (for a date pattern with long month), else
  • UDAT_MEDIUM (for a date pattern with abbreviated month), else
  • UDAT_SHORT (for any other date pattern). For details on dateTimeFormats, see https://www.unicode.org/reports/tr35/tr35-dates.html#dateTimeFormats. The default pattern in the root locale for all styles is "{1} {0}".
Parameters
udtpga pointer to the UDateTimePatternGenerator
styleone of UDAT_FULL..UDAT_SHORT. Error if out of range.
dateTimeFormatthe new dateTimeFormat to set for the the specified style
lengththe length of dateTimeFormat, or -1 if unknown and pattern is null-terminated
pErrorCodea pointer to the UErrorCode (in/out parameter); if no failure status is already set, it will be set according to result of the function (e.g. U_ILLEGAL_ARGUMENT_ERROR for style out of range).
Stable:
ICU 71

◆ udatpg_setDecimal()

U_CAPI void udatpg_setDecimal ( UDateTimePatternGenerator dtpg,
const UChar decimal,
int32_t  length 
)

The decimal value is used in formatting fractions of seconds.

If the skeleton contains fractional seconds, then this is used with the fractional seconds. For example, suppose that the input pattern is "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and the decimal string is ",". Then the resulting pattern is modified to be "H:mm:ss,SSSS"

Parameters
dtpga pointer to UDateTimePatternGenerator.
decimal
lengththe length of decimal.
Stable:
ICU 3.8