Package Loyc.SyncLib

Namespaces
package	Impl

Classes
struct	FieldId
	The data type of a field name in SyncLib, which can be implicitly converted from a string. It includes both a Name string and an Id integer, in order to support both string-keyed fields (e.g. JSON) and int-keyed fields (e.g. Protocol Buffers). By convention, an Id of int.MinValue indicates that int-keyed implementations of ISyncManager should choose an ID automatically based on the field order. More...
interface	ISyncField< SyncManager, T >
	Represents the low-level synchronization behavior for a single list item. SyncManagerHelper needs this. More...
interface	ISyncManager
	This is the central interface of Loyc.SyncLib. To learn more, please visit the web site: http://synclib.loyc.net/ More...
interface	ISyncObject< SyncManager, T >
	This interface is equivalent to SyncObjectFunc{SyncManager,T}, reformulated as an interface. It only exists because the CLR (C# runtime) supports optimizations on generic parameters that are structs, but similar optimizations don't exist for delegates. For this reason it is possible to achieve higher performance by providing a synchronizer in the form of a struct rather than a delegate (see Remarks) More...
interface	ISyncOptions
	An interface for the options objects of ISyncManager implementations (e.g. SyncJson.Options), returned from ISyncManager.Options. It exposes settings whose meaning is not specific to a single data format. More...
class	SyncJson
	Contains optimized ISyncManager implementations for reading and writing JSON data (SyncJson.Reader and SyncJson.Writer) plus an options type (SyncJson.Options) and convenience methods for reading and writing objects as JSON (Read, ReadI, Write, WriteI and WriteString methods.) The JSON format is designed to be compatible with Newtonsoft.Json. More...
class	SyncManagerExt
	Standard extension methods for ISyncManager. More...
class	SyncManagerExtBigInteger
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtBool
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtByte
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtChar
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtDecimal
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtDouble
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtFloat
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtInt
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtLong
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtSByte
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtShort
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtString
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtUInt
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtULong
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncManagerExtUShort
	The methods in this class belong in SyncManagerExt but they must be put in a different class to avoid C# compiler error CS0111, "Type 'SyncManagerExt' already defines a member called 'SyncList' with the same parameter types". More...
class	SyncTimeExt
	Extension methods of ISyncManager for synchronizing the date/time types DateTime, DateTimeOffset and TimeSpan (plus DateOnly and TimeOnly on .NET 6+, but no target framework of Loyc.Essentials is currently new enough to include them). More...

Enumerations
enum	ObjectMode {   ObjectMode.Normal = 0, ObjectMode.List = 1, ObjectMode.Tuple = 3,   ObjectMode.Deduplicate = 4, ObjectMode.NotNull = 8, ObjectMode.NoTypeTag = 16,   ObjectMode.Compact = 128, ObjectMode.ReadNullAsDefault = 256 }
	Lists the kinds of child objects supported by ISyncManager. The three basic kinds are Normal, List and Tuple, which are mutually exclusive; Nullable and Deduplicate are flags that can be combined with the three basic kinds. More...
enum	SyncMode {   SyncMode.Reading = 1, SyncMode.Writing = 2, SyncMode.Schema = 4 | Reading,   SyncMode.Query = 4 | Writing, SyncMode.Merge = Writing | Reading | Query }
	These are the four categories of ISyncManager types. More...
enum	SyncType {   SyncType.Unknown = -1, SyncType.Missing = 0, SyncType.Exists = 1,   SyncType.Boolean = 2, SyncType.Byte = 3, SyncType.Unsigned = 4,   SyncType.Integer = 5, SyncType.Float = 6, SyncType.Char = 7,   SyncType.Object = 8, SyncType.Null = 16, NullableBoolean = Null | Boolean,   NullableByte = Null | Byte, NullableUnsigned = Null | Unsigned, NullableInteger = Null | Integer,   NullableFloat = Null | Float, NullableChar = Null | Char, NullableObject = Null | Object,   SyncType.List = 32, BooleanList = List | Boolean, ByteList = List | Byte,   UnsignedList = List | Unsigned, IntegerList = List | Integer, FloatList = List | Float,   CharList = List | Char, ObjectList = List | Object, SyncType.String = CharList }
	Abstract types used with ISyncManager.GetFieldType. More...

Functions
delegate T	SyncObjectFunc< in SyncManager, T > (SyncManager sync, [AllowNull] T value)
delegate T	SyncFieldFunc< T > (FieldId name, [AllowNull] T value)

Enumeration Type Documentation

enum Loyc.SyncLib.ObjectMode

Lists the kinds of child objects supported by ISyncManager. The three basic kinds are Normal, List and Tuple, which are mutually exclusive; Nullable and Deduplicate are flags that can be combined with the three basic kinds.

Enumerator
Normal	A normal object, in which fields may have names.
List	A list object, in which there are a variable number of unnamed fields. ISyncManager.IsInsideList will be true inside this kind of subobject, and ISyncManager.ReachedEndOfList will be non-null in the Loading and Schema modes. When calling one of the ISyncManager.SyncList methods, this mode will be used implicitly if both the List and Tuple flags are missing.
Tuple	A tuple object, in which there are a fixed number of unnamed fields (and the number of fields is known before starting to load the tuple). ISyncManager.IsInsideList will be true inside this kind of subobject. This mode is used together with a constant tupleLength parameter that is greater than 0. Some implementations of ISyncManager treat this mode identically to List mode, but Tuple mode gives permission not to store the list length in the data stream, in order to make the output more compact. When loading data that was saved in Tuple mode (without a list length), Tuple mode must be specified by the loading code, and it must already know the list length, as ISyncManager.MinimumListLength and ISyncManager.ReachedEndOfList will be null. Many extension methods have a tupleLength parameter which specifies this missing list length.
Deduplicate	Deduplication is performed on the subobject, allowing object graphs that contain cycles. If ISyncManager.SupportsReordering is true, it's possible in Loading Mode that it is already known whether the input data stream used deduplication or not. In that case, it doesn't make a difference whether this flag is present or not. <![CDATA[Note: ObjectMode.Deduplicate is incompatible with Memory<T> and ReadOnlyMemory<T>]]>.
NotNull	The object is not allowed to be null. Certain serializers may use the knowledge that a sub-object is never null to save space. Also, this flag should be used (without Deduplicate) when reading/writing value types as a hint to the serializer to avoid boxing.
NoTypeTag	Requests that no type tag be read or written for this object, even if its synchronizer has a TypeTagAttribute or was registered with a tag in a TypeSyncRegistry. This is useful for compactness when the object's type is known statically, or for interoperability with data formats that lack type tags. Since most data formats are not self-describing (e.g. SyncBinary), the same flag must be used when writing an object and when reading it back; otherwise the data cannot be read correctly. Note: an object written with this flag cannot be read dynamically unless its static type is registered, because without a tag, the reader cannot choose a synchronizer based on the data alone.
Compact	Requests that compact formatting be used when writing this object. When using SyncJson.Writer, this mode suppresses newlines. When using SyncBinary, this mode flag is ignored.
ReadNullAsDefault	Requests that when there is a null value in the data stream and a value type is being read, the default value should be returned instead of throwing an exception. Since synchronizers for primitive types (such as Int32) do not accept an ObjectMode parameter, a separate way of indicating this mode is needed for primitive types. For example, when using SyncJson.Reader, you can enable the SyncJson.Options.ForReader.ReadNullPrimitivesAsDefault option to get a similar effect.

enum Loyc.SyncLib.SyncMode

These are the four categories of ISyncManager types.

Enumerator
Reading	Data is being loaded. Your sync function should return a new object.
Writing	Data is being saved. Your sync function should save the object provided. This mode could also used for synchronization behaviors in which a one-way synchronization occurs from the object to an underlying data store, e.g. updating some kind of virtual DOM. In this mode, the return value of every Sync function must be the same value that was passed into the savable parameter.
Schema	A schema is being saved. Similar to the Loading mode, your sync function will not be given an object value in this mode. Your sync function should call the same methods it would call if it were loading an object, in order to teach the synchronizer about the schema of the current type. However, the Sync methods of a schema saver have no actual data and tend to return default/null values instead, and it will skip subobjects whose schema is already known.
Query	A variation of the "saving" mode in which not all the data will be saved because some kind of query is being used to select which parts of the data to include in the output. This mode may also be used to gather schema information, but unlike the Schema mode, this mode provides your code with an existing object.
Merge	A mode in which "synchronization" happens. You can think of this as a combination of the Saving, Loading, and Query modes. Like Saving mode, this mode provides an object to the synchronizer function. Like Loading mode, the values returned from Sync methods in ISyncManager should be stored into the object. And like Query mode, some objects in the object graph may be ignored (not traversed). None of the synchronizers bundled with Loyc.Serialization use this mode, and the way it works hasn't been finalized. This mode is not supported in the current version of SyncLib: the list synchronization helpers throw NotSupportedException when it is used.

enum Loyc.SyncLib.SyncType

Abstract types used with ISyncManager.GetFieldType.

Designing this enum was a tradeoff between detail and simplicity.

Often, serialized data streams do not identify types in a way that we could compare a .NET Type object to them. For example, it is not possible for an ISyncManager to check whether the JSON object {"R":5,"G":99,"B":17} matches type System.Drawing.Color, because it doesn't know what schema will be used to read the object. Therefore, all composite types are identified simply as Object or as one of the List types.

I decided instead to represent types using an enum, but I didn't want to burden ISyncManager implementations with excessive complexity or detail, so the enum doesn't contain every primitive type (e.g. short and long integers are both classified as Integer).

Enumerator
Unknown	This is returned by ISyncManager.GetFieldType when the reader cannot determine whether the field exists, or when the ISyncManager is not a reader (i.e. the mode is not SyncMode.Loading)
Missing	This is returned by ISyncManager.GetFieldType when the reader has determined that the field does not exist, or that it does exist but is incompatible with the expectedType parameter.
Exists	Indicates that the field exists but that the implementation of ISyncManager cannot determine the data type of the field in advance.
Boolean	Boolean true or false.
Byte	An 8-bit unsigned integer. This exists as a separate value from Unsigned or Integer mainly so that ByteList can be defined as Byte | List, because byte lists are treated specially in some software (e.g. byte lists often represent file contents, but Unsigned lists do not.)
Unsigned	Unsigned integer (data sources often don't support this).
Integer	Signed or unsigned integer of any size (including possibly a byte).
Float	Floating-point number of any size.
Char	Character or code unit (size is implementation-defined). In some implementations, Char only appears as part of a CharList, not by itself.
Object	A composite object. Note: SyncJson sometimes reports that a list is an "object" because deduplicated lists are represented as JSON objects. It is even possible to read such a list as though it is an object, but it can also be read as a list. Unfortunately it is not possible to determine whether such an object actually represents a list, except by attempting to read it as a list.
Null	When returned from HasField(), this value indicates that the stream contains the null value.
List	When returned from HasField(), this value indicates that the stream contains a list, when the type of the list items is dynamic or unknown.
String	A synonym for CharList. If possible, ISyncManager implementations should treat strings as lists of characters.