Update docs to reflect addition of week number support

README.md

@@ -10,14 +10,13 @@ Features:
 - Date ranges and time intervals, integrating with Kotlin ranges and progressions
 - Read and write strings in ISO formats
 - DSL-based definition of custom parsers
-- Access to localized text for names of months, days of the week, time zones, etc.
-- Operators like `date.next(MONDAY)`, `dateTime.startOfWeek`, or `date.weekRange(WeekSettings.systemDefault())`
-- Conversion to and from platform-specific date-time types
+- Access localized text for names of months, days of the week, time zones, etc.
+- Convenience operators like `date.next(MONDAY)`, `dateTime.startOfWeek`, or `date.weekRange(WeekSettings.systemDefault())`
+- Convert to and from platform-specific date-time types
 - Works on JVM, Android, iOS, macOS, tvOS, and watchOS
 
 Current limitations:
 - No custom format strings (must write platform-specific code to do this)
-- Doesn't support all week-related fields or week-based dates
 - Only supports the ISO calendar system
 
 Island Time is still early in development and "moving fast" so to speak. The API is likely to experience changes between minor version increments.

core/src/commonMain/generated/io/islandtime/_DateProperties.kt

@@ -83,8 +83,7 @@ val Date.weekOfWeekBasedYear: Int
 fun Date.weekOfWeekBasedYear(settings: WeekSettings): Int = weekOfWeekBasedYearImpl(settings)
 
 /**
- * The length of the ISO week-based year that this date falls in. This will be either 52 or 53
- * weeks.
+ * The length of the ISO week-based year that this date falls in, either 52 or 53 weeks.
  */
 val Date.lengthOfWeekBasedYear: IntWeeks
   get() = lengthOfWeekBasedYearImpl
@@ -155,8 +154,7 @@ val DateTime.weekOfWeekBasedYear: Int
 fun DateTime.weekOfWeekBasedYear(settings: WeekSettings): Int = date.weekOfWeekBasedYear(settings)
 
 /**
- * The length of the ISO week-based year that this date-time falls in. This will be either 52 or 53
- * weeks.
+ * The length of the ISO week-based year that this date-time falls in, either 52 or 53 weeks.
  */
 val DateTime.lengthOfWeekBasedYear: IntWeeks
   inline get() = date.lengthOfWeekBasedYear
@@ -228,8 +226,7 @@ fun OffsetDateTime.weekOfWeekBasedYear(settings: WeekSettings): Int =
     dateTime.weekOfWeekBasedYear(settings)
 
 /**
- * The length of the ISO week-based year that this date-time falls in. This will be either 52 or 53
- * weeks.
+ * The length of the ISO week-based year that this date-time falls in, either 52 or 53 weeks.
  */
 val OffsetDateTime.lengthOfWeekBasedYear: IntWeeks
   inline get() = dateTime.lengthOfWeekBasedYear
@@ -301,8 +298,7 @@ fun ZonedDateTime.weekOfWeekBasedYear(settings: WeekSettings): Int =
     dateTime.weekOfWeekBasedYear(settings)
 
 /**
- * The length of the ISO week-based year that this date-time falls in. This will be either 52 or 53
- * weeks.
+ * The length of the ISO week-based year that this date-time falls in, either 52 or 53 weeks.
  */
 val ZonedDateTime.lengthOfWeekBasedYear: IntWeeks
   inline get() = dateTime.lengthOfWeekBasedYear

docs/basics/dates-and-times.md

@@ -138,9 +138,9 @@ println(zonedDateTime.adjustedTo(TimeZone("America/Los_Angeles")))
 // Output: 2020-03-07T23:30-08:00
 ```
 
-## Patterns and Operators
+## Patterns, Properties, and Operators
 
-Throughout Island Time's date-time primitives, you'll find a set of patterns that remain (relatively) constant as well as a number of operators that simplify common tasks.
+Throughout Island Time's date-time primitives, you'll find a set of patterns that remain (relatively) constant as well as a number of properties and operators that simplify common tasks.
 
 ### `at`
 
@@ -165,7 +165,7 @@ val dateTime = DateTime.now().copy(dayOfMonth = 15)
 val dateTimeAtMidnight = dateTime.copy(time = Time.MIDNIGHT)
 ```
 
-### Addition and Subtraction
+### Addition and subtraction
 
 A [duration](durations.md) of time can be added or subtracted from a date-time primitive. Which units are supported will vary depending on whether the primitive is date-based, time-based, or both.
 
@@ -268,6 +268,34 @@ val roundedDownTo100Millis = dateTime.roundedDownToNearest(100.milliseconds)
 // Output: 2020-06-30T06:32:14.1
 ```
 
+### Week numbers
+
+You can obtain the week number and year as defined in the [ISO week date system](https://en.wikipedia.org/wiki/ISO_week_date) like this:
+
+```kotlin
+val date = Date.now()
+
+// Get the week-based year, which may differ from the regular year
+val isoWeekYear: Int = date.weekBasedYear
+
+// Get the week of the week-based year
+val isoWeekNumber: Int = date.weekOfWeekBasedYear
+
+// Or convert the date to a full ISO week date representation in a single step
+date.toWeekDate { year: Int, week: Int, day: Int ->
+    // ...
+}
+```
+
+Different week definitions can be used by specifying the [`WeekSettings`](../api/core/io.islandtime.calendar/-week-settings/index.md) explicitly.
+
+```kotlin
+val usaWeekNumber: Int = date.weekOfWeekBasedYear(WeekSettings.SUNDAY_START)
+```
+
+!!! info "`weekOfYear` vs. `weekOfWeekBasedYear`"
+    The week number associated with a particular date could fall in the prior or subsequent year, depending on how the week is defined. `weekOfYear` will return the week number relative to the date's regular `year` -- `0` if it falls in the prior year, for example. On the other hand, `weekOfWeekBasedYear` will adjust the number to the `weekBasedYear`.
+
 ## ISO Representation
 
 Any date-time primitive can be converted to an appropriate ISO string format by simply calling `toString()`. To convert a string into a date-time primitive, use the appropriate conversion function, such as `String.toDate()` or `String.toInstant()`.

docs/index.md

@@ -18,5 +18,4 @@ across platforms while taking full advantage of the features offered by the Kotl
 
 ## Current Limitations
 - No custom format strings (must write platform-specific code to do this)
-- Doesn't support all week-related fields or week-based dates
 - Only supports the ISO calendar system

tools/code-generator/src/main/kotlin/io/islandtime/codegen/generators/DatePropertiesGenerator.kt

@@ -198,8 +198,8 @@ private fun buildDatePropertiesFile() = file(
         property(name = "lengthOfWeekBasedYear", returnType = measures("IntWeeks")) {
             kdoc {
                 """
-                    The length of the ISO week-based year that this ${receiverClass.simpleName} falls in. This will be
-                    either 52 or 53 weeks.
+                    The length of the ISO week-based year that this ${receiverClass.simpleName} falls in, either 52 or
+                    53 weeks.
                 """.trimIndent()
             }