requireKTX

requireKTX is a collection of small utility functions to make it easier to deal with some otherwise nullable APIs on Android, using the same idea as requireContext, requireArguments, and other similar Android SDK methods.

Types that requireKTX provides extensions for:

• Bundle
• Intent
• NavBackStackEntry
• WorkManager Data

Why?

Take the example of grabbing a Fragment argument bundle and reading a String ID from it that should always be there: you have two choices, and none of them are great:

// Providing no default value
// Results in a nullable return type, caller has to do null handling
val id: String = requireArguments().getString("user_id")!!

// Providing a (meaningless) default value
// Results in a platform return type, caller has to explicitly type as non-null
val id: String = requireArguments().getString("user_id", "")
if (id == "") { ... } // ... and check to avoid accidentally using the default value

requireKTX provides methods such as requireString so that you can demand that a value be there, or otherwise get an exception:

val id: String = requireArguments().requireString("user_id")

These methods in the library will throw meaningful exceptions based on the error that occurred - see the method docs for details.

getOrNull

To make the nullable case more obvious and explicit, requireKTX also includes getOrNull style methods for everything that it covers with require style methods. These match the conventions of the Kotlin Standard Library, and can make it clearer that null is returned if a value for a key couldn't be fetched.

val userId: String? = requireArguments().getStringOrNull("user_id")

Dependencies

requireKTX is available from MavenCentral.

repositories {
    mavenCentral()
}

It's available in several artifacts which you can import depending on which types you want to get extensions for - see the module descriptions below for more info:

dependencies {
    implementation "co.zsmb:requirektx-bundle:1.2.0"
    implementation "co.zsmb:requirektx-intent:1.2.0"
    implementation "co.zsmb:requirektx-navigation:1.2.0"
    implementation "co.zsmb:requirektx-work:1.2.0"
}

Available modules and extensions

Bundle

Given a Bundle, you can require the following types of values:

// Primitives (examples)
bundle.requireBoolean()
bundle.requireByte()
bundle.requireChar()
bundle.requireDouble()
bundle.requireFloat()

// Reference types
bundle.requireString()
bundle.requireBundle()
bundle.requireCharSequence()
bundle.requireParcelable()
bundle.requireSerializable()

// Arrays (examples)
bundle.requireBooleanArray()
bundle.requireByteArray()
bundle.requireCharArray()
bundle.requireDoubleArray()
bundle.requireFloatArray()

... and many more!

Intent

Given a Intent, you can require its extras Bundle (and then require values from it as seen above):

val extras: Bundle = intent.requireExtras()

Or you can require specific extras directly for various types of values:

// Primitives (examples)
intent.requireBooleanExtra()
intent.requireByteExtra()
intent.requireCharExtra()
intent.requireDoubleExtra()
intent.requireFloatExtra()

// Reference types
intent.requireStringExtra()
intent.requireBundleExtra()
intent.requireCharSequenceExtra()
intent.requireParcelableExtra()
intent.requireSerializableExtra()

// Arrays (examples)
intent.requireBooleanArrayExtra()
intent.requireByteArrayExtra()
intent.requireCharArrayExtra()
intent.requireDoubleArrayExtra()
intent.requireFloatArrayExtra()

... and many more!

NavBackStackEntry

The navigation module provides an extension to require the arguments of a NavBackStackEntry, same as you could do for a Fragment:

val args: Bundle = navBackStackEntry.requireArguments()

WorkManager Data

Given a WorkManager Data object (such as inputData inside a worker), you can require the following types of values:

class SomeWorker : Worker() {
    override fun doWork(): Result {
        // Values
        inputData.requireBoolean()
        inputData.requireByte()
        inputData.requireDouble()
        inputData.requireFloat()
        inputData.requireInt()
        inputData.requireLong()
        inputData.requireString()

        // Arrays
        inputData.requireBooleanArray()
        inputData.requireByteArray()
        inputData.requireDoubleArray()
        inputData.requireFloatArray()
        inputData.requireIntArray()
        inputData.requireLongArray()
        inputData.requireStringArray()

        // ...
    }
}

License

Copyright 2021 Márton Braun

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.