Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ Add Quantity.From/TryFrom quantity name and unit name #1258

Merged
merged 4 commits into from
Jun 10, 2023

Conversation

angularsen
Copy link
Owner

@angularsen angularsen commented Jun 10, 2023

Make it easier to construct quantities from strings describing the quantity name and unit name, if the unit enum value is not readily available.

This is useful for custom serialization of quantities, such as mapping to simple custom quantity DTO types instead of relying on JSON serialization converters.

Changes

  • Add Quantity.From and TryFrom
  • Refactor UnitConverter to reuse code for constructing quantity from strings
  • Add tests for From and TryFrom
  • Add test CustomSerializationTests.CanMapToJsonAndBackViaCustomDto to showcase serialization

Example

public record QuantityDto(double Value, string QuantityName, string UnitName); 

// The original quantity.
IQuantity q = Length.FromCentimeters(5);

// Map to DTO.
QuantityDto dto = new(
    Value: (double)q.Value,
    QuantityName: q.QuantityInfo.Name,
    UnitName: q.Unit.ToString());

/* Serialize to JSON:
{
    "Value": 5,
    "QuantityName": "Length",
    "UnitName": "Centimeter"
}
*/
var json = System.Text.Json.JsonSerializer.Serialize(dto);

// Deserialize from JSON.
QuantityDto deserialized = System.Text.Json.JsonSerializer.Deserialize<QuantityDto>(json)!;

// Map to IQuantity.
Quantity.TryFrom(deserialized.Value, deserialized.QuantityName, deserialized.UnitName, out IQuantity? deserializedQuantity);

Make it easier to construct quantities from strings describing the quantity name and unit name, instead of unit enum type.
This is useful for custom serialization of quantities, such as mapping to simple custom quantity DTO types instead of relying on JSON serialization converters.
@codecov
Copy link

codecov bot commented Jun 10, 2023

Codecov Report

Patch coverage: 100% and project coverage change: -1 ⚠️

Comparison is base (4d92cc9) 85% compared to head (1cc1e85) 85%.

Additional details and impacted files
@@          Coverage Diff           @@
##           master   #1258   +/-   ##
======================================
- Coverage      85%     85%   -1%     
======================================
  Files         330     330           
  Lines       33836   33831    -5     
======================================
- Hits        28847   28841    -6     
- Misses       4989    4990    +1     
Impacted Files Coverage Δ
...Serialization.JsonNet/UnitsNetBaseJsonConverter.cs 95% <ø> (ø)
UnitsNet/CustomCode/Quantity.cs 89% <100%> (+3%) ⬆️
UnitsNet/UnitConverter.cs 84% <100%> (-3%) ⬇️

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

@angularsen angularsen enabled auto-merge (squash) June 10, 2023 21:31
@angularsen angularsen merged commit 63040c3 into master Jun 10, 2023
2 of 3 checks passed
@angularsen angularsen deleted the agl/quantity-from branch June 10, 2023 21:42
@angularsen
Copy link
Owner Author

@tmilnthorp I'm merging this, but I'd like your eyes on this when you have the chance.

It was inspired by #1256.

We have already started migrating from enum-based to string-based methods in the codebase, since this works better with custom quantities, and this change follows that thinking.

Offering custom serializers is still convenient for many use cases, but in APIs and other areas where a breaking change would be disastrous, I would never trust a third party library to do the serialization. In my mind, custom mapping is the way to go here and this PR helps facilitate that.
I also updated the wiki with an example on how to do this, and took the liberty of declaring it the "recommended" approach. Would love your perspective on this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant