Add README.md

README.md

@@ -0,0 +1,263 @@
+# Time
+
+This library is made for you if you have ever written something like this: 
+
+```kotlin
+val duration = 10 * 1000
+```
+to represent a duration of 10 seconds(in milliseconds) because most methods in Kotlin/Java take duration parameters in milliseconds.
+
+## Usage
+
+### Showcase
+
+```kotlin
+val tenSeconds = 10.seconds
+val fiveMinutes = 5.minutes
+val twoHours = 2.hours
+val threeDays = 3.days
+val tenMinutesFromNow = Calender.getInstance() + 10.minutes
+val tenSecondsInMilliseconds = 10.seconds.inMilliseconds
+```
+
+### Basics
+
+The main advantage of the library is that all time units are *strongly-typed*. So, for example:
+
+```kotlin
+val tenMinutes = 10.minutes
+```
+
+In the example above,  `tenMinutes` will be of type `Interval<Minute>`. There are seven time units available, from nanoseconds to days:
+
+```kotlin
+val tenNanoseconds = 10.nanoseconds 
+// type is Interval<Nanosecond>
+```
+```kotlin
+val tenMicroseconds = 10.microseconds 
+// type is Interval<Microsecond>
+```
+```kotlin
+val tenMilliseconds = 10.milliseconds 
+// type is Interval<Millisecond>
+```
+```kotlin
+val tenSeconds = 10.seconds 
+// type is Interval<Second>
+```
+```kotlin
+val tenMinutes = 10.minutes 
+// type is Interval<Minute>
+```
+```kotlin
+val tenHours = 10.hours 
+// type is Interval<Hour>
+```
+```kotlin
+val tenDays = 10.days 
+// type is Interval<Day>
+```
+
+### Operations
+
+You can perform all basic arithmetic operations on time intervals, even of different units:
+
+```kotlin
+val duration = 10.minutes + 15.seconds - 3.minutes + 2.hours // Interval<Minute>
+val doubled = duration * 2
+
+val seconds = 10.seconds + 3.minutes // Interval<Second>
+```
+
+You can also use these operations on `Calender`:
+
+```kotlin
+val twoHoursLater = Calendar.getInstance() + 2.hours
+```
+
+### Conversions
+
+Time intervals are easily convertible:
+
+```kotlin
+val twoMinutesInSeconds = 2.minutes.inSeconds // Interval<Second>
+val fourDaysInHours = 4.days.inHours // Interval<Hour>
+```
+
+You can also use the `converted()` method, although you would rarely need to:
+
+```kotlin
+val tenMinutesInSeconds: Interval<Second> = 10.minutes.converted()
+```
+
+### Comparison
+
+You can compare different time units as well:
+
+```kotlin
+50.seconds < 2.hours // true
+120.minutes == 2.hours // true
+100.milliseconds > 2.seconds // false
+48.hours in 2.days // true
+```
+
+### Creating your own time units
+
+If, for some reason, you need to create your own time unit, that's super easy to do:
+
+```kotlin
+class Week : TimeUnit {
+    // number of seconds in one week
+    override val timeIntervalRatio = 604800.0
+}
+```
+
+Now you can use it like any other time unit:
+
+```kotlin
+val fiveWeeks = Interval<Week>(5)
+```
+
+For the sake of convenience, don't forget to write those handy extensions:
+
+```kotlin
+class Week : TimeUnit {
+    override val timeIntervalRatio = 604800.0
+}
+
+val Number.weeks: Interval<Week>
+    get() = Interval(this.toDouble())
+
+val Interval<TimeUnit>.inWeeks: Interval<Week>
+    get() = converted()
+```
+Now you can write:
+
+```kotlin
+val fiveWeeks = 5.weeks // Interval<Week>
+```
+You can also easily convert to weeks:
+
+```kotlin
+val valueInWeeks = 14.days.inWeeks // Interval<Week>
+```
+
+### Extras
+
+The library includes some handy extensions for some classes:
+
+```kotlin
+val now = Calendar.getInstance() 
+val sixHoursLater = now + 6.hours
+val fourDaysAgo = now - 4.days
+```
+
+```kotlin
+val timer = Timer()
+timer.schedule(10.seconds) {
+    println("This block will be called in 10 seconds")
+}
+```
+
+The library also includes extensions for Android's Handler class, this is only available if you compile the "time-android" module.
+
+```kotlin
+val handler = Handler()
+handler.postDelayed({
+    Log.i("TAG", "This will be printed to the Logcat in 2 minutes")
+}, 2.minutes)
+```
+More extensions will be added to the library in the future.
+
+### Conversion safety everywhere
+
+For time-related methods in other third-party libraries in your project, if such methods are frequently used, it's best to write extention functions that let you use the time units in this libary in those methods. This is mostly just one line of code. 
+
+If such methods aren't frequently used, you can still benefit from the conversion safety that comes with this library.
+
+An example method in a third-party library that does something after a delay period in milliseconds:
+
+```kotlin
+class Person {
+    fun doSomething(delayMillis: Long) {
+        // method body
+    }
+}
+```
+
+To call the method above with a value of 5 minutes, one would usually write:
+
+```kotlin
+val person = Person()
+person.doSomething(5 * 60 * 1000)
+```
+
+The above line can be written in a safer and clearer way using this library:
+
+```kotlin
+val person = Person()
+person.doSomething(5.minutes.inMilliseconds.longValue)
+```
+
+If the method is frequently used, you can write an extension function:
+
+```kotlin
+fun Person.doSomething(delay: Interval<TimeUnit>) {
+    doSomething(delay.inMilliseconds.longValue)
+}
+```
+Now you can write:
+
+```kotlin
+val person = Person()
+person.doSomething(5.minutes)
+```
+
+## Installation
+
+Add the JitPack repository to your `build.gradle`:
+
+```groovy
+allprojects {
+ repositories {
+    maven { url "https://jitpack.io" }
+    }
+}
+```
+
+Add the dependency to your `build.gradle`:
+
+- For **non-Android** projects:
+
+```groovy
+dependencies {
+    compile 'com.github.kizitonwose.time:time:1.0.0'
+}
+```
+
+- For **Android** projects:
+
+```groovy
+dependencies {
+    compile 'com.github.kizitonwose.time:time-android:1.0.0'
+}
+```
+
+## Contributing
+The goal is for the library to be used wherever possible. If there are extension functions or features you think the library should have, feel free to add them and send a pull request or open an issue. Core Kotlin extensions belong in the "[time][time-core-module-url]" modue while Android extensions belong in "[time-android][time-android-module-url]" module. 
+
+
+## Inspiration
+Time was inspired by a Swift library of the same name - [Time][time-swift-url].
+
+The API of Time(Kotlin) has been designed to be as close as possible to Time(Swift) for consistency and because the two languages have many similarities. Check out [Time(Swift)][time-swift-url] if you want a library with the same functionality in Swift.
+
+
+## License
+Time is distributed under the MIT license. [See LICENSE](https://github.com/kizitonwose/Time/blob/master/LICENSE.md) for details.
+
+
+[time-swift-url]: https://github.com/dreymonde/Time 
+[time-core-module-url]: https://github.com/kizitonwose/Time/tree/master/time 
+[time-android-module-url]: https://github.com/kizitonwose/Time/tree/master/time-android