Swiftpack.co - Package - dragosrobertn/KNContacts
Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.


Cocoapods CI codecov codebeat badge contributions

KNContacts is wrapper for CNContacts for easier access to information like current age and age at next birthday, full contact name, creating contact books (groups), ordering them and creating contact schedules.

More information

KNContacts framework features a couple of classes, structs and enums to facilitate access to contacts, contact books and schedule of contacts.

Type Name Description
struct KNContact Wrapper struct for CNContact, provides access to helper methods and original contact details.
class KNContactBook Collection of KNContacts with methods for adding, removing, sorting and retrieving specific or random elements
struct KNContactBookOrdering Helper ordering methods to sort contacts in KNContactBook
struct KNContactsSchedule Dictionary wrapper for creating contact schedule for using custom time formats for scheduling and retrieving at a particular time
struct KNDatesUtils Date formatting helper methods
enum KNTimeFormat Enum with pre-defined time formats


You can check the full documentation here.


Sample initialisation and usage

KNContact and KNContactBook

KNContact is a wrapper structure and you can initialise a new obejct by passing in a CNContact or CNMutableContact object. KNContactBook is a collection of KNContact objects which can be sorted and random elements extracted.

import Contacts
import KNContacts

var contactBook = KNContactBook(id: "allContacts")

// Retrieve or create your CNContact list from a store - KNContacts does *not* handle authorisation for you.
// Make sure you have all necessary key descriptors.

var keys = [CNContactGivenNameKey, CNContactMiddleNameKey, CNContactFamilyNameKey,
            CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactPhoneNumbersKey,
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName)] as! [CNKeyDescriptor]

let requestForContacts = CNContactFetchRequest(keysToFetch: keys)

do {
    try CNContactStore().enumerateContacts(with: requestForContacts) { (cnContact, _) in
        let knContact = KNContact(cnContact)
} catch let error {
    // Handle error somehow!

// And then perform actions on KNContactBook
let randomContacts = contactBook.randomElements(number: 1)
let randomElements = contactBook.randomElements(number: 3, except: randomContacts)

randomElements.forEach({ (contact) in 
    print(contact.fullName(format: .fullName))
    if (contact.isBirthdayToday()) {
        print("It's their birthday today!")
    } else if (contact.isBirthdayComing(in: 7)) {
        print("Birthday coming up in the next week!")
    } else {
        print("Birthday on \(contact.formatBirthday())")

KNContactsSchedule, KNContactBookOrdering, KNDatesUtils

KNContact can also return ordered array of elements. Two options are provided in KNContactBookOrdering But the toArray(orderedBy:) method can take any sorting function. KNDatesUtils provides easy access to string date formatters.

let order = KNContactBookOrdering.thisYearsBirthday
let contactsSortedByBirthday = contactBook.contacts.sorted(by: order)

// And finally schedules can be created for easier retrieval at a later date.
var thisWeeksBirthdaySchedule = KNContactsSchedule(name: "birthdaysThisYear")

for numberOfDays in 1...7 {
    let birthdayList = contactsSortedByBirthday.filter({ $0.isBirthdayComing(in: numberOfDays) }).map({ $0.id })
    let date = Calendar.current.date(byAdding: .day, value: numberOfDays, to: Date())!
    let dateString = KNDatesUtils.formatter(with: .fullDate).string(from: date)
    thisWeeksBirthdaySchedule.add(list: birthdayList, to: dateString)

// And retrieve schedule by date
let tomorrow = Calendar.current.date(byAdding: .day, value: 1, to: Date())!
let schedule = thisWeeksBirthdaySchedule.getSchedule(for: tomorrow)


KNContacts version Swift Version Package Managers Supported
from v1.3.0 Swift 5.0 Swift Package Manager, Cocoapods
from v1.2.0 Swift 5.0 Cocoapods
up to v1.1.1 Swift 4.2 Cocoapods


KNContacts is currently available using CocoaPods and Swift Package Manager. Just add this snippet into your podfile to use the latest version.


pod 'KNContacts'

or specify the desired version.

pod 'KNContacts', '~> 1.0.0'

Swift Package Manager

Once you have SPM set up, add this package to the dependencies. SPM has been supported only since version 1.3.0.

dependencies: [
    .package(url: "https://github.com/dragosrobertn/KNContacts.git", .upToNextMajor(from: "1.3.0"))

Applications using KNContacts

If your app uses KNContacts, feel free to submit a Pull Request.


Pull requests are welcome, all changes should be accompanied by tests and a passing build.

Issues or features requests are welcome, feel free to create implementations yourself. The development of this framework is done using trunk based development strategy so please create your pull requests against the master branch and ensure the build is passing.


This library is MIT Licensed.


Stars: 5


v.1.3.0 - Support for Swift Package Manager - 2020-05-02T12:28:20


This release version adds support for Swift Package Manager. Once you have SPM set up, add this package to the dependencies.

dependencies: [
    .package(url: "https://github.com/dragosrobertn/KNContacts.git", .upToNextMajor(from: "1.3.0"))

v.1.2.3 - Localised formatting for KNDatesUtils - 2020-05-01T21:41:16


  • All formatter methods in KNDatesUtils now accept a locale parameter to provide the formatted dates in the correct locale. Default is the device's current locale.

v.1.2.2 - Fix for birthdayIsUpcoming(in:startingdate:) to not consider current date - 2020-01-15T13:58:10


  • New method birthdayMatches(date:) added to KNContact class to check if contact's birthday matches a particular date.

Bug fixes

  • Recent changes to birthdayIsUpcoming(in:startingdate:) have introduced a bug that was considering current date as an upcoming date. This has now been fixed. If you have been using that functionality and it was working as expected for you, please pass a starting date to birthdayIsUpcoming(in:startingdate:), or use isBirthdayToday() to achieve the same result.

v1.2.1 - Fix bug for isBirthdayComing date miscalculation - 2020-01-02T12:33:49

Bug fixes

  • This version a bug fix release for the KNContact.isBirthdayComing(in:) method which saw wrong results at certain times.


  • Method signature changed to KNContact.isBirthdayComing(in: startingDate:) to accept a starting date from which to start counting instead of assuming current date. Default is current Date.

v1.2.0 - Swift 5 support, remove deprecated methods and bug fixes - 2019-12-28T03:24:10

Note: Upon further checks it looks like the date bug was not fixed properly in 1.2.0. Please use v1.2.1.

v1.2.0 features:

  • Support for Swift 5
  • It fixes a date bug caused by miscalculation when the date in the future would be in the following year.

v1.2.0 is a breaking change as:

Breaking changes

  • Drops support for Swift 4.2
  • Removes deprecated methods and warnings from v1.1.0

v.1.1.0 - Establish method naming convention. - 2019-06-30T23:53:46

Version 1.1.0 Introduces new methods and deprecates existing ones in favour of the new ones.

Mini-breaking changes

However, there will be small breaking changes, as follows:

  • KNDatesUtils and KNContactBookOrdering are now static structs and no longer require instantiation.



  • KNContact.details is deprecated in favour of KNContact.info


The following changes have been made:

  • KNContact.getAgeAsString(atNextBirthday: asOrdinal:) introduced and therefore:

    • KNContact.getAgeAsOrdinal() is deprecated.
    • KNContact.getAgeAtNextBirthday() is deprecated.
    • KNContact.getAgeAsOrdinalAtNextBirthday() is deprecated.
  • KNContact.formatBirthday(with: forCurrentYear:) introduced and therefore:

    • KNContact.formattedBirthday(with: currentYear:)
  • KNContact.getBirthday(forCurrentYear:) introduced and therefore:

    • KNContact.birthday(currentYear:) is deprecated



  • New read-only identifiers, contacts, contactsIdentifiers and count attributes introduced.


The following changes have been made:

  • KNContactBook.getContact(by:) and KNContactBook.getContacts(by:) introduced and therefore:

    • KNContactBook.updatedValues(for:) is deprecated
    • KNContactBook.get(forKey:) is deprecated
    • KNContactBook.getOptional(forKey:) is deprecated
  • As a result of the introduction of the contacts attribute, the KNContact.toArray() and KNContact.toArray(orderedBy:) are deprecated. Access the attribute directly and use sorted(by:) to achieve the same result.

  • As a result of the introduction of the identifiers attribute, the KNContact.keysArray() is deprecated. Access the attribute directly to retrieve the book keys.



The following changes have been made:

  • KNContactsSchedule.add(list:fromString:) is deprecated. To achieve the same result use KNContactsSchedule.add(list:to:) which signature's has now been modified.


This enum has now been renamed to KNDateTimeFormat and has gained two type aliases for maintaining compatibility. Please use KNDateTimeFormat or KNFormat instead.

v.1.0.1 - Improvements to type safety and documentation. - 2019-06-30T12:34:41

This release maintain backwards compatibility with version 1.0.0.


  • Improves type safety by removing potential nil values from certain return values.
  • Fully documented public classes and methods.