ICU 75.1 75.1
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions
icu::DateTimePatternGenerator Class Reference

This class provides flexible generation of date format patterns, like "yy-MM-dd". More...

#include <dtptngen.h>

Inheritance diagram for icu::DateTimePatternGenerator:
icu::UObject icu::UMemory

Public Member Functions

virtual ~DateTimePatternGenerator ()
 Destructor.
 
DateTimePatternGeneratorclone () const
 Clone DateTimePatternGenerator object.
 
bool operator== (const DateTimePatternGenerator &other) const
 Return true if another object is semantically equal to this one.
 
bool operator!= (const DateTimePatternGenerator &other) const
 Return true if another object is semantically unequal to this one.
 
UnicodeString getSkeleton (const UnicodeString &pattern, UErrorCode &status)
 Utility to return a unique skeleton from a given pattern.
 
UnicodeString getBaseSkeleton (const UnicodeString &pattern, UErrorCode &status)
 Utility to return a unique base skeleton from a given pattern.
 
UDateTimePatternConflict addPattern (const UnicodeString &pattern, UBool override, UnicodeString &conflictingPattern, UErrorCode &status)
 Adds a pattern to the generator.
 
void setAppendItemFormat (UDateTimePatternField field, const UnicodeString &value)
 An AppendItem format is a pattern used to append a field if there is no good match.
 
const UnicodeStringgetAppendItemFormat (UDateTimePatternField field) const
 Getter corresponding to setAppendItemFormat.
 
void setAppendItemName (UDateTimePatternField field, const UnicodeString &value)
 Sets the names of field, eg "era" in English for ERA.
 
const UnicodeStringgetAppendItemName (UDateTimePatternField field) const
 Getter corresponding to setAppendItemNames.
 
UnicodeString getFieldDisplayName (UDateTimePatternField field, UDateTimePGDisplayWidth width) const
 The general interface to get a display name for a particular date/time field, in one of several possible display widths.
 
void setDateTimeFormat (const UnicodeString &dateTimeFormat)
 The DateTimeFormat is a message format pattern used to compose date and time patterns.
 
const UnicodeStringgetDateTimeFormat () const
 Getter corresponding to setDateTimeFormat.
 
void setDateTimeFormat (UDateFormatStyle style, const UnicodeString &dateTimeFormat, UErrorCode &status)
 dateTimeFormats are message patterns used to compose combinations of date and time patterns.
 
const UnicodeStringgetDateTimeFormat (UDateFormatStyle style, UErrorCode &status) const
 Getter corresponding to setDateTimeFormat.
 
UnicodeString getBestPattern (const UnicodeString &skeleton, UErrorCode &status)
 Return the best pattern matching the input skeleton.
 
UnicodeString getBestPattern (const UnicodeString &skeleton, UDateTimePatternMatchOptions options, UErrorCode &status)
 Return the best pattern matching the input skeleton.
 
UnicodeString replaceFieldTypes (const UnicodeString &pattern, const UnicodeString &skeleton, UErrorCode &status)
 Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
 
UnicodeString replaceFieldTypes (const UnicodeString &pattern, const UnicodeString &skeleton, UDateTimePatternMatchOptions options, UErrorCode &status)
 Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
 
StringEnumerationgetSkeletons (UErrorCode &status) const
 Return a list of all the skeletons (in canonical form) from this class.
 
const UnicodeStringgetPatternForSkeleton (const UnicodeString &skeleton) const
 Get the pattern corresponding to a given skeleton.
 
StringEnumerationgetBaseSkeletons (UErrorCode &status) const
 Return a list of all the base skeletons (in canonical form) from this class.
 
StringEnumerationgetRedundants (UErrorCode &status)
 Return a list of redundant patterns are those which if removed, make no difference in the resulting getBestPattern values.
 
void setDecimal (const UnicodeString &decimal)
 The decimal value is used in formatting fractions of seconds.
 
const UnicodeStringgetDecimal () const
 Getter corresponding to setDecimal.
 
UDateFormatHourCycle getDefaultHourCycle (UErrorCode &status) const
 Get the default hour cycle for a locale.
 
virtual UClassID getDynamicClassID () const override
 ICU "poor man's RTTI", returns a UClassID for the actual class.
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor.
 

Static Public Member Functions

static DateTimePatternGeneratorcreateInstance (UErrorCode &status)
 Construct a flexible generator according to default locale.
 
static DateTimePatternGeneratorcreateInstance (const Locale &uLocale, UErrorCode &status)
 Construct a flexible generator according to data for a given locale.
 
static DateTimePatternGeneratorcreateInstanceNoStdPat (const Locale &uLocale, UErrorCode &status)
 For ICU use only.
 
static DateTimePatternGeneratorcreateEmptyInstance (UErrorCode &status)
 Create an empty generator, to be constructed with addPattern(...) etc.
 
static UnicodeString staticGetSkeleton (const UnicodeString &pattern, UErrorCode &status)
 Utility to return a unique skeleton from a given pattern.
 
static UnicodeString staticGetBaseSkeleton (const UnicodeString &pattern, UErrorCode &status)
 Utility to return a unique base skeleton from a given pattern.
 
static UClassID getStaticClassID ()
 ICU "poor man's RTTI", returns a UClassID for this class.
 

Detailed Description

This class 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 getBestPattern(String skeleton), since normally this class 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.

Stable:
ICU 3.8

Definition at line 58 of file dtptngen.h.

Constructor & Destructor Documentation

◆ ~DateTimePatternGenerator()

virtual icu::DateTimePatternGenerator::~DateTimePatternGenerator ( )
virtual

Destructor.

Stable:
ICU 3.8

Member Function Documentation

◆ addPattern()

UDateTimePatternConflict icu::DateTimePatternGenerator::addPattern ( const UnicodeString pattern,
UBool  override,
UnicodeString conflictingPattern,
UErrorCode status 
)

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
patternInput pattern, such as "dd/MMM"
overrideWhen existing values are to be overridden use true, otherwise use false.
conflictingPatternPrevious pattern with the same skeleton.
statusOutput param set to success/failure code on exit, 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

◆ clone()

DateTimePatternGenerator * icu::DateTimePatternGenerator::clone ( ) const

Clone DateTimePatternGenerator object.

Clients are responsible for deleting the DateTimePatternGenerator object cloned.

Stable:
ICU 3.8

◆ createEmptyInstance()

static DateTimePatternGenerator * icu::DateTimePatternGenerator::createEmptyInstance ( UErrorCode status)
static

Create an empty generator, to be constructed with addPattern(...) etc.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Stable:
ICU 3.8

◆ createInstance() [1/2]

static DateTimePatternGenerator * icu::DateTimePatternGenerator::createInstance ( const Locale uLocale,
UErrorCode status 
)
static

Construct a flexible generator according to data for a given locale.

Parameters
uLocale
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Stable:
ICU 3.8

◆ createInstance() [2/2]

static DateTimePatternGenerator * icu::DateTimePatternGenerator::createInstance ( UErrorCode status)
static

Construct a flexible generator according to default locale.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Stable:
ICU 3.8

◆ createInstanceNoStdPat()

static DateTimePatternGenerator * icu::DateTimePatternGenerator::createInstanceNoStdPat ( const Locale uLocale,
UErrorCode status 
)
static

For ICU use only.

Skips loading the standard date/time patterns (which is done via DateFormat).

Internal:
Do not use. This API is for internal use only.

◆ getAppendItemFormat()

const UnicodeString & icu::DateTimePatternGenerator::getAppendItemFormat ( UDateTimePatternField  field) const

Getter corresponding to setAppendItemFormat.

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

Parameters
fieldsuch as UDATPG_ERA_FIELD.
Returns
append pattern for field
Stable:
ICU 3.8

◆ getAppendItemName()

const UnicodeString & icu::DateTimePatternGenerator::getAppendItemName ( UDateTimePatternField  field) const

Getter corresponding to setAppendItemNames.

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

Parameters
fieldsuch as UDATPG_ERA_FIELD.
Returns
name for field
See also
getFieldDisplayName
Stable:
ICU 3.8

◆ getBaseSkeleton()

UnicodeString icu::DateTimePatternGenerator::getBaseSkeleton ( const UnicodeString pattern,
UErrorCode status 
)

Utility to return 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). getBaseSkeleton() works exactly like staticGetBaseSkeleton(). Use staticGetBaseSkeleton() instead of getBaseSkeleton().

Parameters
patternInput pattern, such as "dd/MMM"
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
base skeleton, such as "MMMd"
Stable:
ICU 3.8

◆ getBaseSkeletons()

StringEnumeration * icu::DateTimePatternGenerator::getBaseSkeletons ( UErrorCode status) const

Return a list of all the base skeletons (in canonical form) from this class.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
a StringEnumeration with the base skeletons. The caller must delete the object.
Stable:
ICU 3.8

◆ getBestPattern() [1/2]

UnicodeString icu::DateTimePatternGenerator::getBestPattern ( const UnicodeString skeleton,
UDateTimePatternMatchOptions  options,
UErrorCode status 
)

Return the best pattern matching the input skeleton.

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

Parameters
skeletonThe skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
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.
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
bestPattern The best pattern found from the given skeleton.
Stable:
ICU 4.4

◆ getBestPattern() [2/2]

UnicodeString icu::DateTimePatternGenerator::getBestPattern ( const UnicodeString skeleton,
UErrorCode status 
)

Return the best pattern matching the input skeleton.

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

Parameters
skeletonThe skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
bestPattern The best pattern found from the given skeleton.
Stable:
ICU 3.8

◆ getDateTimeFormat() [1/2]

const UnicodeString & icu::DateTimePatternGenerator::getDateTimeFormat ( ) const

Getter corresponding to setDateTimeFormat.

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

Returns
DateTimeFormat.
Stable:
ICU 3.8

◆ getDateTimeFormat() [2/2]

const UnicodeString & icu::DateTimePatternGenerator::getDateTimeFormat ( UDateFormatStyle  style,
UErrorCode status 
) const

Getter corresponding to setDateTimeFormat.

Parameters
styleone of UDAT_FULL..UDAT_SHORT. Error if out of range.
statusin/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
the current dateTimeFormat for the the specified style, or empty string in case of error. The UnicodeString reference, or the contents of the string, may no longer be valid if setDateTimeFormat is called, or the DateTimePatternGenerator object is deleted.
Stable:
ICU 71

◆ getDecimal()

const UnicodeString & icu::DateTimePatternGenerator::getDecimal ( ) const

Getter corresponding to setDecimal.

Returns
UnicodeString corresponding to the decimal point
Stable:
ICU 3.8

◆ getDefaultHourCycle()

UDateFormatHourCycle icu::DateTimePatternGenerator::getDefaultHourCycle ( UErrorCode status) const

Get the default hour cycle for a locale.

Uses the locale that the DateTimePatternGenerator was initially created with.

Cannot be used on an empty DateTimePatternGenerator instance.

Parameters
statusOutput param set to success/failure code on exit, which 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

◆ getDynamicClassID()

virtual UClassID icu::DateTimePatternGenerator::getDynamicClassID ( ) const
overridevirtual

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
ICU 3.8

Reimplemented from icu::UObject.

◆ getFieldDisplayName()

UnicodeString icu::DateTimePatternGenerator::getFieldDisplayName ( UDateTimePatternField  field,
UDateTimePGDisplayWidth  width 
) const

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

Parameters
fieldThe desired UDateTimePatternField, such as UDATPG_ERA_FIELD.
widthThe desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED.
Returns
The display name for field
Stable:
ICU 61

◆ getPatternForSkeleton()

const UnicodeString & icu::DateTimePatternGenerator::getPatternForSkeleton ( const UnicodeString skeleton) const

Get the pattern corresponding to a given skeleton.

Parameters
skeleton
Returns
pattern corresponding to a given skeleton.
Stable:
ICU 3.8

◆ getRedundants()

StringEnumeration * icu::DateTimePatternGenerator::getRedundants ( UErrorCode status)

Return a list of redundant patterns are those which if removed, make no difference in the resulting getBestPattern values.

This method returns a list of them, to help check the consistency of the patterns used to build this generator.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
a StringEnumeration with the redundant pattern. The caller must delete the object.
Internal:
Do not use. This API is for internal use only. ICU 3.8

◆ getSkeleton()

UnicodeString icu::DateTimePatternGenerator::getSkeleton ( const UnicodeString pattern,
UErrorCode status 
)

Utility to return a unique skeleton from a given pattern.

For example, both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". getSkeleton() works exactly like staticGetSkeleton(). Use staticGetSkeleton() instead of getSkeleton().

Parameters
patternInput pattern, such as "dd/MMM"
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
skeleton such as "MMMdd"
Stable:
ICU 3.8

◆ getSkeletons()

StringEnumeration * icu::DateTimePatternGenerator::getSkeletons ( UErrorCode status) const

Return a list of all the skeletons (in canonical form) from this class.

Call getPatternForSkeleton() to get the corresponding pattern.

Parameters
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
StringEnumeration with the skeletons. The caller must delete the object.
Stable:
ICU 3.8

◆ getStaticClassID()

static UClassID icu::DateTimePatternGenerator::getStaticClassID ( )
static

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
ICU 3.8

◆ operator!=()

bool icu::DateTimePatternGenerator::operator!= ( const DateTimePatternGenerator other) const

Return true if another object is semantically unequal to this one.

Parameters
otherthe DateTimePatternGenerator object to be compared with.
Returns
true if other is semantically unequal to this.
Stable:
ICU 3.8

◆ operator==()

bool icu::DateTimePatternGenerator::operator== ( const DateTimePatternGenerator other) const

Return true if another object is semantically equal to this one.

Parameters
otherthe DateTimePatternGenerator object to be compared with.
Returns
true if other is semantically equal to this.
Stable:
ICU 3.8

◆ replaceFieldTypes() [1/2]

UnicodeString icu::DateTimePatternGenerator::replaceFieldTypes ( const UnicodeString pattern,
const UnicodeString skeleton,
UDateTimePatternMatchOptions  options,
UErrorCode status 
)

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.

Parameters
patternInput pattern
skeletonThe skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
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.
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
pattern adjusted to match the skeleton fields widths and subtypes.
Stable:
ICU 4.4

◆ replaceFieldTypes() [2/2]

UnicodeString icu::DateTimePatternGenerator::replaceFieldTypes ( const UnicodeString pattern,
const UnicodeString skeleton,
UErrorCode status 
)

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.

Parameters
patternInput pattern
skeletonThe skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
pattern adjusted to match the skeleton fields widths and subtypes.
Stable:
ICU 3.8

◆ setAppendItemFormat()

void icu::DateTimePatternGenerator::setAppendItemFormat ( UDateTimePatternField  field,
const UnicodeString value 
)

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
fieldsuch as UDATPG_ERA_FIELD.
valuepattern, such as "{0}, {1}"
Stable:
ICU 3.8

◆ setAppendItemName()

void icu::DateTimePatternGenerator::setAppendItemName ( UDateTimePatternField  field,
const UnicodeString value 
)

Sets the names 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
fieldsuch as UDATPG_ERA_FIELD.
valuename of the field
Stable:
ICU 3.8

◆ setDateTimeFormat() [1/2]

void icu::DateTimePatternGenerator::setDateTimeFormat ( const UnicodeString dateTimeFormat)

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 DateTimePatternGenerator object, corresponding to date styles UDAT_FULL..UDAT_SHORT. This method sets all of them to the specified pattern. To set them individually, see setDateTimeFormat(UDateFormatStyle style, ...).

Parameters
dateTimeFormatmessage format pattern, here {1} will be replaced by the date pattern and {0} will be replaced by the time pattern.
Stable:
ICU 3.8

◆ setDateTimeFormat() [2/2]

void icu::DateTimePatternGenerator::setDateTimeFormat ( UDateFormatStyle  style,
const UnicodeString dateTimeFormat,
UErrorCode status 
)

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
styleone of DateFormat.FULL..DateFormat.SHORT. Error if out of range.
dateTimeFormatthe new dateTimeFormat to set for the the specified style
statusin/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

◆ setDecimal()

void icu::DateTimePatternGenerator::setDecimal ( const UnicodeString decimal)

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
decimal
Stable:
ICU 3.8

◆ staticGetBaseSkeleton()

static UnicodeString icu::DateTimePatternGenerator::staticGetBaseSkeleton ( const UnicodeString pattern,
UErrorCode status 
)
static

Utility to return 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).

Parameters
patternInput pattern, such as "dd/MMM"
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
base skeleton, such as "MMMd"
Stable:
ICU 56

◆ staticGetSkeleton()

static UnicodeString icu::DateTimePatternGenerator::staticGetSkeleton ( const UnicodeString pattern,
UErrorCode status 
)
static

Utility to return a unique skeleton from a given pattern.

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

Parameters
patternInput pattern, such as "dd/MMM"
statusOutput param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns
skeleton such as "MMMdd"
Stable:
ICU 56

The documentation for this class was generated from the following file: