Mozo.Fwob
1.4.2
See the version list below for details.
dotnet add package Mozo.Fwob --version 1.4.2
NuGet\Install-Package Mozo.Fwob -Version 1.4.2
<PackageReference Include="Mozo.Fwob" Version="1.4.2" />
paket add Mozo.Fwob --version 1.4.2
#r "nuget: Mozo.Fwob, 1.4.2"
// Install Mozo.Fwob as a Cake Addin #addin nuget:?package=Mozo.Fwob&version=1.4.2 // Install Mozo.Fwob as a Cake Tool #tool nuget:?package=Mozo.Fwob&version=1.4.2
Fixed-Width Ordered Binary (FWOB) Format Library
This repository contains the library implementation of the FWOB file format.
Features
- Enfores increasing order of data frames by key
- Binary format storage
- User-defined flat data structure
- High-efficient (de)serializer (40% performance vs the best C++ implementation)
- Built-in support for a string table
- Supports on-disk file and in-memory storage
Capacity
- File length: up to 2^63 - 1 bytes (8,192 PiB)
- String table length: up to 2^31 - 1 bytes (2 GiB)
- Fwob title: up to 16 bytes
- Frame name: up to 16 bytes
- Frame type: up to 16 fields
- Field name: up to 8 bytes
- Field type: of any primitive types (non-nullable) and string type
- String field length: up to 255 bytes
Build from source
# Restore any necessary imported packages
dotnet restore
# Build the entire solution
dotnet build --no-restore
# Run the test cases in the test directory and generate coverage report
dotnet test --no-build --verbosity normal /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura
# Visualize coverage report in HTML (requires the dotnet tool dotnet-reportgenerator-globaltool to be installed)
reportgenerator -reports:test/coverage.cobertura.xml -targetdir:CoverageReport -reporttypes:Html -historydir:CoverageHistory
# Publish a portable Mozo.Fwob.dll for any supported system that have the .NET 7.0 installed
dotnet publish src -c Release -f net7.0 --no-self-contained
# Pack the built manifests into a .nupkg package
dotnet pack -c Release
How to Use
Define your frame data structure
The data structure can be any POCO class or record class with a key field (annotated or by convention the first type-matched field) defined as a struct type that implements IComparable<TKey>
.
The data structure can have fields, methods, indexers, properties, custom parameterized constructors and non-public members. But only public fields and the parameterless constructor will be accessed by the FWOB library.
Since the frame must be fixed-width, a field of string type must define a fixed length. This can be achieved by annotating with the Mozo.Fwob.LengthAttribute
.
Here is an example,
public class StockTick
{
public uint Price;
[Key]
public uint Time;
public double RealPrice
{
get => Price / 10000.0;
set => Price = (uint)Math.Round(value * 10000);
}
public int Size;
[Ignore]
public int Extra;
[Length(4)]
public string SpecCond;
}
Only the public fields Price
, Time
, Size
and SpecCond
will hold data in a FWOB file. The RealPrice
property, which is not a field, and the Extra
field, which is ignored with the Mozo.Fwob.IgnoreAttribute
annotation, won't hold any data in the file. By convention, the library use the first field defined of TKey
type as the key. To specify a custom key, use the Mozo.Fwob.KeyAttribute
to annotate a field of TKey
type. The key field will be used by the library to compare and order the frames in the file.
The library checks the schema in the initialization of either an FwobFile<TFrame, TKey>
or an InMemoryFwobFile<TFrame, TKey>
file object. Exceptions will be thrown if conflicts is detected or rules are violated.
Create an on-disk FWOB file
var fwobFile = new FwobFile<StockTick, uint>(fileName, "FileTitle");
Open an existing on-disk FWOB file
var fwobFile = new FwobFile<StockTick, uint>(fileName);
Create an in-memory FWOB file
var fwobFile = new InMemoryFwobFile<StockTick, uint>(title);
Read frames
// Get the first frame in the file
var firstFrame = fwobFile.FirstFrame;
// Get the last frame in the file
var lastFrame = fwobFile.LastFrame;
// Get the frame of a given index in the file
var frame = fwobFile.GetFrameAt(index);
// Get an enumerator for iterating the frames of a given key in the file
var frames = fwobFile.GetFrames(key);
// Get an enumerator for iterating the frames of a given increasing sequence of keys in the file
var frames = fwobFile.GetFrames(key1, key2, key3);
// Get an enumerator for iterating the frames of a given key range [firstKey, lastKey) in the file
var frames = fwobFile.GetFramesBetween(firstKey, lastKey);
// Get an enumerator for iterating the frames of a given higher bound (inclusive) in the file
var frames = fwobFile.GetFramesBefore(lastKey);
// Get an enumerator for iterating the frames of a given lower bound (inclusive) in the file
var frames = fwobFile.GetFramesAfter(firstKey);
// Get an enumerator for iterating all the frames in the file
var frames = fwobFile.GetAllFrames();
Write frames
// Append frames to the end of the file, only the ascending prefixing frames will be taken
long appendedCount = fwobFile.AppendFrames(frames);
// Append frames to the end of the file while enforcing the ascending order by key and no data will be appended if the ordering rule is violated
long appendedCount = fwobFile.AppendFramesTx(frames);
Delete frames
// Deletes the frames whose key is equal to the given key
long deletedCount = fwobFile.DeleteFrames(key);
// Deletes the frames whose key is equal to any in the given increasing sequence of keys
long deletedCount = fwobFile.DeleteFrames(key1, key2, key3);
// Deletes the frames whose key is in a given key range [firstKey, lastKey)
long deletedCount = fwobFile.GetFramesBetween(firstKey, lastKey);
// Deletes the frames whose key is less than or equal to the given key
long deletedCount = fwobFile.DeleteFramesBefore(lastKey);
// Deletes the frames whose key is greater than or equal to the given key
long deletedCount = fwobFile.DeleteFramesAfter(firstKey);
// Deletes all frames from the storage
long deletedCount = fwobFile.DeleteAllFrames();
String table
// Load and unload the string table into memory, not needed for the in-memory storage
fwobFile.LoadStringTable();
fwobFile.UnloadStringTable();
// The string table is accessible via a list
var list = fwobFile.Strings;
// Get a specific string at a given index
var str = fwobFile.GetString(index);
// Get a specific index of a given string
int index = fwobFile.GetString(str);
// Append a string to the back of the string table (duplicate allowed)
int index = fwobFile.AppendString(str);
// Check if a string is in the string table
bool exist = fwobFile.ContainsString(str);
// Remove all strings from the string table
int deletedCount = fwobFile.DeleteAllStrings();
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 is compatible. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.8
- No dependencies.
-
.NETStandard 2.0
- No dependencies.
-
net7.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.