ADC Home > Reference Library > Reference > Internationalization > Carbon > Date, Time, and Measurement Utilities Reference >

Next Page > Hide TOC

Date, Time, and Measurement Utilities Reference

Framework
CoreServices/CoreServices.h
Declared in
DateTimeUtils.h
QuickTimeComponents.k.h
UTCUtils.h

Overview

You can use the Date, Time, and Measurement Utilities to manipulate the date-time information and geographic location data used by a Macintosh computer. A Macintosh computer contains a battery-operated clock chip that maintains information on the current date-time. In Mac OS 9, the date and time were retrieved from this clock chip. In Mac OS X, the date and time are retrieved through the BSD/CoreFoundation level.

You can use the routines provided by the Date, Time, and Measurement Utilities to

Please note, setting the time or geographical location requires authorization by using Authorization Services. See Authorization Concepts for more information.

To make the best use of the Date, Time, and Measurement Utilities, you should be familiar with the international resources, especially the numeric-format and long-date-format resources, and the Script Manager.

Carbon supports the majority of the Date, Time, and Measurement Utilities. However, obsolete functions that are prefixed with “iu” or “IU” (such as IUDateString and IUTimeString) are not supported.

Functions by Task

Converting Between Date-Time Formats

Converting Between Long Date-Time Format

Converting Date and Time Strings Into Numeric Representations

Converting Long Date and Time Values Into Strings

Converting Numeric Representations Into Date and Time Strings

Converting Between CF and Carbon Time Types

Converting Between UTC and Local Time

Getting the Current Date and Time

Modifying and Verifying Long Date-Time Records

Setting the Current Date and Time

Functions

GetTime

Obtains the current date-time information, expressed as a date and time. (Deprecated. Use CFAbsoluteTimeGetCurrent instead.)

void GetTime (
   DateTimeRec *d
);

Parameters
d

On return, the fields of the date-time structure contain the current date and time.

Discussion

The GetTime function first calls the GetDateTime function to obtain the number of seconds elapsed since midnight, January 1, 1904. It then calls the SecondsToDate function to convert the number of seconds into a date and time.

As an alternative to using the GetTime procedure, you can pass the value of the global variable Time to the SecondsToDate function; a SecondsToDate(Time) function call is identical to a GetTime(d) function call.

If an application disables interrupts for longer than a second, the date-time information returned by the GetTime function might not be exact. The GetTime function is intended to provide fairly accurate time information, but not scientifically precise data.

Availability
Declared In
QuickTimeComponents.k.h

UCConvertCFAbsoluteTimeToLongDateTime

Converts a value of type CFAbsoluteTime to LongDateTime.

OSStatus UCConvertCFAbsoluteTimeToLongDateTime (
   CFAbsoluteTime iCFTime,
   LongDateTime *oLongDate
);

Parameters
iCFTime

A CFAbsoluteTime value that represents the time from which you wish to convert.

oLongDate

A pointer to a value of type LongDateTime. On successful return, this will contain the converted time from the CFAbsoluteTime input.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use UCConvertCFAbsoluteTimeToLongDateTime to convert from a CFAbsoluteTime to a LongDateTime. Remember that the epoch for LongDateTime is January 1, 1904 while the epoch for CFAbsoluteTime is January 1, 2001.

Availability
Declared In
DateTimeUtils.h

UCConvertCFAbsoluteTimeToSeconds

Converts a value of type CFAbsoluteTime to seconds.

OSStatus UCConvertCFAbsoluteTimeToSeconds (
   CFAbsoluteTime iCFTime,
   UInt32 *oSeconds
);

Parameters
iCFTime

A CFAbsoluteTime value that represents the time from which you wish to convert.

oSeconds

A pointer to a value of type UInt32. On successful return, this contains the converted time from the CFAbsoluteTime input.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use UCConvertCFAbsoluteTimeToSeconds to convert from a CFAbsoluteTime to a UInt32 representation of seconds. Remember that the epoch for seconds is January 1, 1904 while the epoch for CFAbsoluteTime is January 1, 2001.

Availability
Declared In
DateTimeUtils.h

UCConvertCFAbsoluteTimeToUTCDateTime

Converts a value of type CFAbsoluteTime to UTCDateTime.

OSStatus UCConvertCFAbsoluteTimeToUTCDateTime (
   CFAbsoluteTime iCFTime,
   UTCDateTime *oUTCDate
);

Parameters
iCFTime

A CFAbsoluteTime value that represents the time from which you wish to convert.

oUTCDate

A pointer to a UTCDateTime. On successful return, this will contain the converted time from the CFAbsoluteTime input.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use UCConvertCFAbsoluteTimeToUTCDateTime to convert from a CFAbsoluteTime to a UTCDateTime. Remember that the epoch for UTCDateTime is January 1, 1904 while the epoch for CFAbsoluteTime is January 1, 2001.

Availability
Declared In
DateTimeUtils.h

UCConvertLongDateTimeToCFAbsoluteTime

Converts a value of type LongDateTime to CFAbsoluteTime.

OSStatus UCConvertLongDateTimeToCFAbsoluteTime (
   LongDateTime iLongTime,
   CFAbsoluteTime *oCFTime
);

Parameters
iLongTime

A LongDateTime value that represents the time from which you wish to convert.

oCFTime

A pointer to a CFAbsoluteTime. On successful return, this will contain the converted time from the input time type.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use UCConvertLongDateTimeToCFAbsoluteTime to convert from a LongDateTime to a CFAbsoluteTime. Remember that the epoch for LongDateTime is January 1, 1904 while the epoch for CFAbsoluteTime is January 1, 2001.

Availability
Declared In
DateTimeUtils.h

UCConvertSecondsToCFAbsoluteTime

Converts a value from the normal seconds time representation to CFAbsoluteTime.

OSStatus UCConvertSecondsToCFAbsoluteTime (
   UInt32 iSeconds,
   CFAbsoluteTime *oCFTime
);

Parameters
iSeconds

A UInt32 value that represents the time from which you wish to convert.

oCFTime

A pointer to a CFAbsoluteTime. On successful return, this will contain the converted time from the input time type.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use UCConvertSecondsToCFAbsoluteTime to convert from the normal seconds representation of time to a CFAbsoluteTime. Remember that the epoch for seconds is January 1, 1904 while the epoch for CFAbsoluteTime is January 1, 2001.

Keep in mind that this function converts local time (that is, the time in the local time zone) to GMT/UTC.

Availability
Declared In
DateTimeUtils.h

UCConvertUTCDateTimeToCFAbsoluteTime

Converts a value of type UTCDateTime time to CFAbsoluteTime.

OSStatus UCConvertUTCDateTimeToCFAbsoluteTime (
   const UTCDateTime *iUTCDate,
   CFAbsoluteTime *oCFTime
);

Parameters
iUTCDate

A pointer to a UTCDateTime structure that represents the time from which you wish to convert.

oCFTime

A pointer to a CFAbsoluteTime. On successful return, this contains the converted time from the input time type.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use UCConvertUTCDateTimeToCFAbsoluteTime to convert from a UTCDDateTime to a CFAbsoluteTime. Remember that the epoch for UTCDateTime is January 1, 1904 while the epoch for CFAbsoluteTime is January 1, 2001.

Availability
Declared In
DateTimeUtils.h

Data Types

DateCacheRecord

struct DateCacheRecord {
   short hidden[256];
};
typedef struct DateCacheRecord DateCacheRecord;
typedef DateCacheRecord * DateCachePtr;

Fields
hidden

The storage used for converting dates and times.

Discussion

The StringToDate and StringToTime functions use the date cache, defined by the DateCacheStructure data type, as an area to store date conversion data that is used by the date conversion functions. This structure must be initialized by a call to the InitDateCache function. The data in this structure is private—you should not attempt to access it.

Availability
Declared In
DateTimeUtils.h

DateDelta

typedef SInt8 DateDelta;

Availability
Declared In
DateTimeUtils.h

DateTimeRec

struct DateTimeRec {
   short year;
   short month;
   short day;
   short hour;
   short minute;
   short second;
   short dayOfWeek;
};
typedef struct DateTimeRec DateTimeRec;

Fields
year

The year, ranging from 1904 to 2040. Note that to indicate the year 1984, this field would store the integer 1984, not just 84. This field accepts input of 0 or negative values, but these values produce unpredictable results in the year, month, and day fields when you use the SecondsToDate and DateToSeconds functions. In addition, using SecondsToDate and DateToSeconds with year values greater than 2040 causes a wraparound to 1904 plus the number of years over 2040. For example, setting the year to 2045 returns a value of 1909, and the other fields in this record return unpredictable results.

month

The month of the year, where 1 represents January, and 12 represents December. Values greater than 12 cause a wraparound to a future year and month. This field accepts input of 0 or negative values, but these values produce unpredictable results in the year, month, and day fields when you use the SecondsToDate and DateToSeconds functions.

day

The day of the month, ranging from 1 to 31. Values greater than the number of days in a given month cause a wraparound to a future month and day. This feature is useful for working with leap years. For example, the 366th day of January in 1992 (1992 was a leap year) evaluates as December 31, 1992, and the 367th day of that year evaluates as January 1, 1993.

This field accepts 0 or negative values, but when you use the SecondsToDate and DateToSeconds procedures, a value of 0 in this field returns the last day of the previous month. For example, a month value of 2 and a day value of 0 return 1 and 31, respectively.

Using SecondsToDate and DateToSeconds with a negative number in this field subtracts that number of days from the last day in the previous month. For example, a month value of 5 and a day value of –1 return 4 for the month and 29 for the day a month value of 2 and a day value of –15 return 1 and 16, respectively.

hour

The hour of the day, ranging from 0 to 23, where 0 represents midnight and 23 represents 11:00 P.M. Values greater than 23 cause a wraparound to a future day and hour. This field accepts input of negative values, but these values produce unpredictable results in the month, day, hour, and minute fields you use the SecondsToDate and DateToSeconds procedures.

minute

The minute of the hour, ranging from 0 to 59. Values greater than 59 cause a wraparound to a future hour and minute. When you use the SecondsToDate and DateToSeconds procedures, a negative value in this field has the effect of subtracting that number from the beginning of the given hour. For example, an hour value of 1 and a minute value of –10 return 0 hours and 50 minutes. However, if the negative value causes the hour value to be less than 0, for example hour = 0, minute = –61, unpredictable results occur.

second

The second of the minute, ranging from 0 to 59. Values greater than 59 cause a wraparound to a future minute and second. When you use the SecondsToDate and DateToSeconds procedures, a negative value in this field has the effect of subtracting that number from the beginning of the given minute. For example, a minute value of 1 and a second value of –10 returns 0 minutes and 50 seconds. However, if the negative value causes the hour value to be less than 0, for example hour = 0, minute = 0, and second = –61, unpredictable results occur.

dayOfWeek

The day of the week, where 1 indicates Sunday and 7 indicates Saturday. This field accepts 0, negative values, or values greater than 7. When you use the SecondsToDate and DateToSeconds procedures, you get correct values because this field is automatically calculated from the values in the year, month, and day fields.

Discussion

The date-time record describes the date-time information as a date and time. The Date, Time, and Measurement Utilities use a date-time record to read and write date-time information to and from the system.

The date-time record can be used to hold date and time values only for a Gregorian calendar. The long date-time record, LongDateRec, can be used for a Gregorian calendar as well as other calendar systems.

Availability
Declared In
DateTimeUtils.h

LocalDateTime

struct LocalDateTime {
   UInt16 highSeconds;
   UInt32 lowSeconds;
   UInt16 fraction;
};
typedef struct LocalDateTime LocalDateTime;
typedef LocalDateTime * LocalDateTimePtr;
typedef LocalDateTimePtr * LocalDateTimeHandle;

Discussion

UTCDateTime and LocalDateTime are both 64 bits wide. The first 48 bits represent the number of seconds since 1904. The remaining 16 bits are used to indicate a fractional seconds value, which has no inherent precision. Each unit of this 16-bit value represents 1/65535 of a second. Developers may apply the appropriate arithmetic to derive milliseconds or microseconds.

Note that the decision to have the lowSeconds field divided between the high and low 32 bits of the 64 bit structure was intentional. The structure above is perfect for performing 64 bit math and logical comparisons. Having the lowSeconds field in the low or high 32 bits would have been easier for the compilers to handle and probably execute faster, however it would have rendered the structure unusable for 64 bit math and logical comparisons.

Availability
Declared In
UTCUtils.h

LongDateCvt

union LongDateCvt {
   SInt64 c
   struct {
      UInt32 lHigh;
      UInt32 lLow;
   } hl;
};
typedef union LongDateCvt LongDateCvt;

Fields
c

The date and time, specified in seconds relative to midnight, January 1, 1904, as a signed, 64-bit integer in SANE comp format. The high-order bit of this field represents the sign of the 64-bit integer. Negative values allow you to indicate dates and times prior to midnight, January 1, 1904.

hl

The high-order 32 bits when converting from a standard date-time value. Set this field to 0.

Discussion

The Date, Time, and Measurement Utilities provide the LongDateCvt structure to help in setting up LongDateTime values.

Availability
Declared In
DateTimeUtils.h

LongDateRec

union LongDateRec {
   struct {
      short era;
      short year;
      short month;
      short day;
      short hour;
      short minute;
      short second;
      short dayOfWeek;
      short dayOfYear;
      short weekOfYear;
      short pm;
      short res1;
      short res2;
      short res3;
   } ld;
   short list[14]
   struct {
      short eraAlt;
      DateTimeRec oldDate;
   } od;
};
typedef union LongDateRec LongDateRec;

Fields
era

The value 0 represents A.D. and -1 represents B.C

year

The year, from 30081 B.C. to 29940 A.D.

month

The month (1 = January and 12 = December).

day

The day of the month, from 1 to 31.

hour

The hour, from 0 to 23.

minute

The minute, from 0 to 59.

second

The second., from 0 to 59

dayOfWeek

The day of the week (1 through 7).

dayOfYear

The day of the year, from 1 to 365.

weekOfYear

The week of the year. from 1 through 52.

pm

The value 0 represents AM and the value 1 represents PM.

res1

Reserved.

res2

Reserved.

res3

Reserved.

list

An array [0 . . 13] whose values indicate which of the fields in a long date-time record need to be verified.

eraAlt

Indicates the era, used only for conversion from a date-time record to a long date-time record.

oldDate

Used only for conversion from a date-time record to a long date-time record.

Discussion

In addition to the date-time record, system software provides the long date-time record, which extends the date-time record format by adding several more fields. This format lets you use dates and times with a much longer span (30,000 B.C. to 30,000 A.D.). In addition, the long date-time record allows conversions to different calendar systems, such as a lunar calendar.

Availability
Declared In
DateTimeUtils.h

LongDateTime

typedef SInt64 LongDateTime;

Discussion

The long date-time value specifies the date and time as seconds relative to midnight, January 1, 1904. But where the standard date-time value is an unsigned, 32-bit long integer, the long date-time value is a signed, 64-bit integer in SANE comp format. This format lets you use dates and times with a much longer span—roughly 500 billion years. You can use this value to represent dates and times prior to midnight, January 1, 1904. The LongDateTime data type defines the long date-time value.

When storing a long date-time value in files, you can use a 5-byte or 6-byte format for a range of roughly 35,000 years. You should sign extend this value to restore it to a comp format. Use the LongDateCvt structure to help you in setting up a LongDateTime value.

Availability
Declared In
DateTimeUtils.h

String2DateStatus

typedef StringToDateStatus String2DateStatus;

Availability
Declared In
DateTimeUtils.h

StringToDateStatus

typedef short StringToDateStatus;

Availability
Declared In
DateTimeUtils.h

TogglePB

struct TogglePB {
   long togFlags;
   ResType amChars;
   ResType pmChars;
   long reserved[4];
};
typedef struct TogglePB TogglePB;

Fields
togFlags

The high-order word of this field contains flags that specify special conditions for the ToggleDate function.

The low-order word of this field contains masks representing fields to be checked by the ValidDate function. Each mask corresponds to a value in the enumerated type LongDateField. See Long Date Mask Constants for a description of the values which you can use in this field. You can set this field to check the era through second fields by using the predeclared constant dateStdMask.

amChars

The trailing string to display for morning (for example, A.M.). This string is read from the numeric-format resource (resource type 'itl0') of the current script system.

pmChars

The trailing to display for evening (for example, P.M.). This string is read from the numeric-format resource (resource type 'itl0') of the current script system.

reserved

Reserved. Set each of the three elements of this field to 0.

Discussion

The ToggleDate function exchanges information with your application using the toggle parameter block, defined by the TogglePB data type.

Availability
Declared In
DateTimeUtils.h

UTCDateTime

struct UTCDateTime {
   UInt16 highSeconds;
   UInt32 lowSeconds;
   UInt16 fraction;
};
typedef struct UTCDateTime UTCDateTime;
typedef UTCDateTime * UTCDateTimePtr;
typedef UTCDateTimePtr * UTCDateTimeHandle;

Discussion

UTCDateTime and LocalDateTime are both 64 bits wide. The first 48 bits represent the number of seconds since 1904. The remaining 16 bits are used to indicate a fractional seconds value, which has no inherent precision. Each unit of this 16-bit value represents 1/65535 of a second. Developers may apply the appropriate arithmetic to derive milliseconds or microseconds.

Note that the decision to divide the lowSeconds field between the high and low 32 bits of the 64 bit structure was intentional. You can use the structure to perform 64 bit math and logical comparisons. Having the lowSeconds field in the low or high 32 bits would have been easier for the compilers to handle and probably execute faster, however it would have rendered the structure unusable for 64 bit math and logical comparisons.

Important: You cannot access this structure as a UInt64 data type. Doing so on systems that use little-endian byte odering may produce the wrong result.

Availability
Declared In
UTCUtils.h

Constants

Date Form Constants

typedef SInt8 DateForm;
enum {
   shortDate = 0,
   longDate = 1,
   abbrevDate = 2
};

Default Options

Options for use with the functions SetDateTime and GetDateTime.

enum {
   kUTCDefaultOptions = 0
};

Error Codes

enum {
   fatalDateTime = 0x8000,
   longDateFound = 1,
   leftOverChars = 2,
   sepNotIntlSep = 4,
   fieldOrderNotIntl = 8,
   extraneousStrings = 16,
   tooManySeps = 32,
   sepNotConsistent = 64,
   tokenErr = 0x8100,
   cantReadUtilities = 0x8200,
   dateTimeNotFound = 0x8400,
   dateTimeInvalid = 0x8800
};

Long Date Field Constants

typedef SInt8 LongDateField;
enum {
   eraField = 0,
   yearField = 1,
   monthField = 2,
   dayField = 3,
   hourField = 4,
   minuteField = 5,
   secondField = 6,
   dayOfWeekField = 7,
   dayOfYearField = 8,
   weekOfYearField = 9,
   pmField = 10,
   res1Field = 11,
   res2Field = 12,
   res3Field = 13
};

Long Date Mask Constants

enum {
   eraMask = 0x0001,
   yearMask = 0x0002,
   monthMask = 0x0004,
   dayMask = 0x0008,
   hourMask = 0x0010,
   minuteMask = 0x0020,
   secondMask = 0x0040,
   dayOfWeekMask = 0x0080,
   dayOfYearMask = 0x0100,
   weekOfYearMask = 0x0200,
   pmMask = 0x0400,
   dateStdMask = 0x007F
};

Constants
eraMask

Verify the era.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

yearMask

Verify the year.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

monthMask

Verify the month.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

dayMask

Verify the day

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

hourMask

Verify the hour.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

minuteMask

Verify the minute.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

secondMask

Verify the second.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

dayOfWeekMask

Verify the day of the week.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

dayOfYearMask

Verify the day of the year.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

weekOfYearMask

Verify the week of the year.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

pmMask

Verify the evening (P.M.).

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

dateStdMask

Verify the era through the second.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

Discussion

These constants are used in the field parameter of the ToggleDate function to specify the LongDateRec fields for the ValidDate function to check.

Flags

enum {
   smallDateBit = 31,
   togChar12HourBit = 30,
   togCharZCycleBit = 29,
   togDelta12HourBit = 28,
   genCdevRangeBit = 27,
   validDateFields = -1,
   maxDateField = 10
};

Constants
smallDateBit

If this bit is set, the valid date and time are restricted to the range of the system global variable Time—that is, between midnight on January 1, 1904 and 6:28:15 A.M. on February 6, 2040.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

togChar12HourBit

If this bit is set, modifying the hour by character is limited to the 12-hour range defined by togCharZCycleBit, mapped to the appropriate half of the 24-hour range, as determined by the pm field. This bit works with system software version 6.0.4 and later.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

togCharZCycleBit

If this bit is set, the input character is treated as if it modifies an hour whose value is in the range 0–11. If this bit is not set, the input character is treated as if it modifies an hour whose value is in the range 12, 1–11. This bit works with system software version 6.0.4 and later.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

togDelta12HourBit

If this bit is set, modifying the hour up or down is limited to a 12-hour range. For example, increasing by one from 11 produces 0, increasing by one from 23 produces 12, and so on. This bit works with system software version 6.0.4 and later.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

genCdevRangeBit

If this bit is set in addition to smallDateBit, then the date range is restricted to that used by the General Controls control panel—January 1, 1920 to December 31, 2019 in the Gregorian calendar (the routine works correctly for other calendars as well). For dates outside this range but within the range specified by the system global variable Time—January 1, 1904 to February 6, 2040 in the Gregorian calendar—ToggleDate adds or subtracts 100 years to bring the dates into the range of the General Controls control panel if these bits are set. The ToggleDate function returns an error if the smallDateBit is set and the date is outside the range specified by the system global variable Time. This bit works with system software version 6.0.4 and later.

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

validDateFields

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

maxDateField

Available in Mac OS X v10.0 and later.

Declared in DateTimeUtils.h.

Toggle Results

typedef SInt16 ToggleResults;
enum {
   toggleUndefined = 0,
   toggleOK = 1,
   toggleBadField = 2,
   toggleBadDelta = 3,
   toggleBadChar = 4,
   toggleUnknown = 5,
   toggleBadNum = 6,
   toggleOutOfRange = 7,
   toggleErr3 = 7,
   toggleErr4 = 8,
   toggleErr5 = 9
};

Result Codes

The most common result codes returned by Date, Time, and Measurement Utilities are listed below.

Result CodeValueDescription
clkRdErr-85

Unable to read the same clock value twice.

Available in Mac OS X v10.0 and later.

clkWrErr-86

The time written did not verify.

Available in Mac OS X v10.0 and later.

kUTCUnderflowErr-8850

An underflow error occurred.

Available in Mac OS X v10.0 and later.

kUTCOverflowErr-8851

An overflow error occurred.

Available in Mac OS X v10.0 and later.

kIllegalClockValueErr-8852

An illegal clock value was encountered.

Available in Mac OS X v10.0 and later.



Next Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-09-29)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.