diff --git a/README.md b/README.md index db82c71b..2fb98759 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@ DateTools was written to streamline date and time handling in iOS. Classes and c [![CocoaPods](https://cocoapod-badges.herokuapp.com/v/DateTools/badge.png)](http://cocoapods.org/?q=datetools) [![CocoaPods](https://cocoapod-badges.herokuapp.com/v/DateToolsSwift/badge.png)](http://cocoapods.org/?q=datetoolsswift) -####Featured In +#### Featured In +
@@ -111,13 +112,13 @@ The following bundle is necessary if you would like to support internationalizat * [**Credits**](#credits) * [**License**](#license) -##DateTools +## DateTools **Full code documentation can be found [here](http://cocoadocs.org/docsets/DateToolsSwift/2.0.0/)** One of the missions of DateTools was to make Date feel more complete. There are many other languages that allow direct access to information about dates from their date classes, but Date (sadly) does not. It safely works only in the Unix time offsets through the timeIntervalSince... methods for building dates and remains calendar agnostic. But that's not always what we want to do. Sometimes, we want to work with dates based on their date components (like year, month, day, etc) at a more abstract level. This is where DateTools comes in. -####Time Ago +#### Time Ago No date library would be complete without the ability to quickly make an NSString based on how much earlier a date is than now. DateTools has you covered. These "time ago" strings come in a long and short form, with the latter closely resembling Twitter. You can get these strings like so: @@ -178,7 +179,7 @@ This project is user driven (by people like you). Pull requests close faster tha Thanks to Kevin Lawler for his work on [NSDate+TimeAgo](https://github.com/kevinlawler/NSDate-TimeAgo), which has been officially merged into this library. -####Date Components +#### Date Components There is a lot of boilerplate associated with getting date components from an Date. You have to set up a calendar, use the desired flags for the components you want, and finally extract them out of the calendar. @@ -200,7 +201,7 @@ let year = Date().year let month = Date().month ``` -####Date Editing +#### Date Editing The date editing methods in DateTools makes it easy to shift a date earlier or later by adding and subtracting date components. For instance, if you would like a date that is 1 year later from a given date, simply call the method dateByAddingYears. @@ -224,7 +225,7 @@ NSDate *newDate = [date dateByAddingYears:1]; Subtraction of date components is also fully supported through the dateBySubtractingYears -####Date Comparison +#### Date Comparison Another mission of the DateTools category is to greatly increase the flexibility of date comparisons. Date gives you four basic methods: * isEqualToDate: @@ -262,15 +263,15 @@ Methods for comparison in this category include: * minutesFrom:, minutesUntil, minutesAgo, minutesEarlierThan:, minutesLaterThan: * secondsFrom:, secondsUntil, secondsAgo, secondsEarlierThan:, secondsLaterThan: -####Formatted Date Strings +#### Formatted Date Strings Just for kicks, DateTools has a few convenience methods for quickly creating strings from dates. Those two methods are formattedDateWithStyle: and formattedDateWithFormat:. The current locale is used unless otherwise specified by additional method parameters. Again, just for kicks, really. -##Time Periods +## Time Periods Dates are important, but the real world is a little less discrete than that. Life is made up of spans of time, like an afternoon appointment or a weeklong vacation. In DateTools, time periods are represented by the TimePeriod class and come with a suite of initializaiton, manipulation, and comparison methods to make working with them a breeze. -####Initialization +#### Initialization Time peroids consist of an Date start date and end date. To initialize a time period, call the init function. @@ -282,7 +283,7 @@ or, if you would like to create a time period of a known length that starts or e DTTimePeriod *timePeriod = [DTTimePeriod timePeriodWithSize:DTTimePeriodSizeHour amount:5 startingAt:[NSDate date]]; ``` -####Time Period Info +#### Time Period Info A host of methods have been extended to give information about an instance of TimePeriod. A few are listed below * hasStartDate - Returns true if the period has a start date @@ -290,7 +291,7 @@ A host of methods have been extended to give information about an instance of Ti * isMoment - Returns true if the period has the same start and end date * durationIn.... - Returns the length of the time period in the requested units -####Manipulation +#### Manipulation Time periods may also be manipulated. They may be shifted earlier or later as well as expanded and contracted. @@ -310,7 +311,7 @@ DTTimePeriod *timePeriod = [DTTimePeriod timePeriodWithSize:DTTimePeriodSizeMin ``` This doubles a time period of duration 1 minute to duration 2 minutes. The end date of "now" is retained and only the start date is shifted 1 minute earlier. -####Relationships +#### Relationships There may come a need, say when you are making a scheduling app, when it might be good to know how two time periods relate to one another. Are they the same? Is one inside of another? All these questions may be asked using the relationship methods of TimePeriod. @@ -334,13 +335,14 @@ All of the possible relationships have been enumerated in the TimePeriodRelation ![TimePeriods](https://raw.githubusercontent.com/MatthewYork/Resources/master/DateTools/TimePeriodsDemo.gif) -##Time Period Groups +## Time Period Groups Time period groups are the final abstraction of date and time in DateTools. Here, time periods are gathered and organized into something useful. There are two main types of time period groups, TimePeriodCollection and TimePeriodChain. At a high level, think about a collection as a loose group where overlaps may occur and a chain a more linear, tight group where overlaps are not allowed. Both collections and chains operate like an NSArray. You may add,insert and remove TimePeriod objects from them just as you would objects in an array. The difference is how these periods are handled under the hood. -###Time Period Collections +### Time Period Collections + Time period collections serve as loose sets of time periods. They are unorganized unless you decide to sort them, and have their own characteristics like a StartDate and EndDate that are extrapolated from the time periods within. Time period collections allow overlaps within their set of time periods. ![TimePeriodCollections](https://raw.githubusercontent.com/MatthewYork/Resources/master/DateTools/TimePeriodCollection.png) @@ -373,7 +375,8 @@ It is also possible to check an Date's or TimePeriod's relationship to the colle ![TimePeriodCollectionOperations](https://raw.githubusercontent.com/MatthewYork/Resources/master/DateTools/TimePeriodCollectionOperations.png) -###Time Period Chains +### Time Period Chains + Time period chains serve as a tightly coupled set of time periods. They are always organized by start and end date, and have their own characteristics like a StartDate and EndDate that are extrapolated from the time periods within. Time period chains do not allow overlaps within their set of time periods. This type of group is ideal for modeling schedules like sequential meetings or appointments. ![TimePeriodChains](https://raw.githubusercontent.com/MatthewYork/Resources/master/DateTools/TimePeriodChain.png) @@ -402,10 +405,11 @@ Like collections, chains have an equality check and the ability to be shifted ea ![TimePeriodChainOperations](https://raw.githubusercontent.com/MatthewYork/Resources/master/DateTools/TimePeriodChainOperations.png) -##Documentation +## Documentation + All methods and variables have been documented and are available for option+click inspection, just like the SDK classes. This includes an explanation of the methods as well as what their input and output parameters are for. Please raise an issue if you ever feel documentation is confusing or misleading and we will get it fixed up! -##Unit Tests +## Unit Tests Unit tests were performed on all the major classes in the library for quality assurance. You can find theses under the "Tests" folder at the top of the library. There are over 300 test cases in all! @@ -413,7 +417,7 @@ If you ever find a test case that is incomplete, please open an issue so we can Continuous integration testing is performed by Travis CI: [![Build Status](https://travis-ci.org/MatthewYork/DateTools.svg?branch=master)](https://travis-ci.org/MatthewYork/DateTools) -##Credits +## Credits Many thanks to [Grayson Webster](https://github.com/GraysonWebster) for helping rethink DateTools for Swift and crank out the necessary code! @@ -425,7 +429,7 @@ Images were first published through itenso.com through [Code Project](http://www I would also like to thank **God** through whom all things live and move and have their being. [Acts 17:28](http://www.biblegateway.com/passage/?search=Acts+17%3A16-34&version=NIV) -##License +## License The MIT License (MIT)