-
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
43 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,75 +1,84 @@ | ||
# Constant Usage | ||
|
||
`Constant` is a component of the **AppState** library that allows you to define and access fixed values that should not change over time. Constants are ideal for representing static information or configuration values that remain the same throughout the lifecycle of the app. | ||
`Constant` in the **AppState** library provides read-only access to values within your application's state. It works similarly to `Slice`, but ensures that the accessed values are immutable. This makes `Constant` ideal for accessing values that may otherwise be mutable but should remain read-only in certain contexts. | ||
|
||
## Key Features | ||
|
||
- **Immutable Values**: Constants provide immutable values that cannot be modified once set. | ||
- **Scoped to Application**: Just like `State`, `Constant` is defined within the `Application` extension, making it easily accessible across the app. | ||
- **Thread-Safe**: Even though constants are immutable, `Constant` ensures safe access in concurrent environments. | ||
- **Read-Only Access**: Constants provide access to mutable state, but the values cannot be modified. | ||
- **Scoped to Application**: Like `Slice`, `Constant` is defined within the `Application` extension and scoped to access specific parts of the state. | ||
- **Thread-Safe**: `Constant` ensures safe access to state in concurrent environments. | ||
|
||
## Example Usage | ||
|
||
### Defining Constants in Application | ||
### Defining a Constant in Application | ||
|
||
Here's how you define constants within the `Application` extension: | ||
Here’s how you define a `Constant` in the `Application` extension to access a read-only value: | ||
|
||
```swift | ||
import AppState | ||
import SwiftUI | ||
|
||
struct ExampleValue { | ||
var username: String? | ||
var isLoading: Bool | ||
let value: String | ||
var mutableValue: String | ||
} | ||
|
||
extension Application { | ||
var appVersion: Constant<String> { | ||
constant("1.0.0") | ||
var exampleValue: State<ExampleValue> { | ||
state( | ||
initial: ExampleValue( | ||
username: "Leif", | ||
isLoading: false, | ||
value: "value", | ||
mutableValue: "" | ||
) | ||
) | ||
} | ||
} | ||
``` | ||
|
||
### Accessing the Constant in a SwiftUI View | ||
|
||
struct ConstantExampleView: View { | ||
@Constant(\.appVersion) var appVersion: String | ||
In a SwiftUI view, you can use the `@Constant` property wrapper to access the constant state in a read-only manner: | ||
|
||
```swift | ||
import AppState | ||
import SwiftUI | ||
|
||
struct ExampleView: View { | ||
@Constant(\.exampleValue, \.value) var constantValue: String | ||
|
||
var body: some View { | ||
VStack { | ||
Text("App Version: \(appVersion)") | ||
} | ||
Text("Constant Value: \(constantValue)") | ||
} | ||
} | ||
``` | ||
|
||
### Using Optional Constants | ||
### Read-Only Access to Mutable State | ||
|
||
You can also define optional constants if the value might not always be present: | ||
Even if the value is mutable elsewhere, when accessed through `@Constant`, the value becomes immutable: | ||
|
||
```swift | ||
import AppState | ||
import SwiftUI | ||
|
||
extension Application { | ||
var supportEmail: OptionalConstant<String> { | ||
optionalConstant(nil) | ||
} | ||
} | ||
|
||
struct OptionalConstantExampleView: View { | ||
@OptionalConstant(\.supportEmail) var supportEmail: String? | ||
struct ExampleView: View { | ||
@Constant(\.exampleValue, \.mutableValue) var constantMutableValue: String | ||
|
||
var body: some View { | ||
VStack { | ||
if let email = supportEmail { | ||
Text("Support Email: \(email)") | ||
} else { | ||
Text("Support email not available") | ||
} | ||
} | ||
Text("Read-Only Mutable Value: \(constantMutableValue)") | ||
} | ||
} | ||
``` | ||
|
||
## Best Practices | ||
|
||
- **Use for Static Data**: `Constant` is perfect for storing static data like version numbers, configuration values, or any data that should not change. | ||
- **Use `OptionalConstant` for Flexible Scenarios**: If there is a chance that the constant value may be absent, use `OptionalConstant` to safely handle `nil` values. | ||
- **Thread Safety**: Even though constants are immutable, `Constant` provides thread-safe access in case multiple tasks read the value concurrently. | ||
- **Use for Read-Only Access**: Use `Constant` to access parts of the state that should not be modified within certain contexts, even if they are mutable elsewhere. | ||
- **Thread-Safe**: Like other AppState components, `Constant` ensures thread-safe access to state. | ||
- **Use `OptionalConstant` for Optional Values**: If the part of the state you're accessing may be `nil`, use `OptionalConstant` to safely handle the absence of a value. | ||
|
||
## Conclusion | ||
|
||
`Constant` and `OptionalConstant` are valuable tools for managing fixed or immutable data within your app. They ensure that static values remain easily accessible throughout the application, while ensuring thread-safe access to the data. | ||
`Constant` and `OptionalConstant` provide an efficient way to access specific parts of your app's state in a read-only manner. They ensure that values which may otherwise be mutable are treated as immutable when accessed within a view, ensuring safety and clarity in your code. |