diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 1b2869a..a130858 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-08-19T02:33:10","documenter_version":"1.5.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-08-26T02:32:54","documenter_version":"1.5.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 647b0a0..ddbae63 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -103,4 +103,4 @@ propoffset, getprop, setprop -)

Where typedefs are the new user-facing type definition and the internal type definitions, typefuncs are type related functions from Base for the new types, conv are convert methods to those types, propsize is the implementation for FieldFlags.fieldsize, propoffset is the implementation for FieldFlags.propertyoffset, getprop is the definition for the getproperty overload for the user facing type and setprop is the definition for the setproperty! overloda for the user facing type.

See also FieldFlags.bitflags.

source
FieldFlags.cast_extend_truncate — Function
cast_extend_truncate(T::DataType, x) -> T

Takes an object x of a primitive type and either bitcasts it to type T (if their sizes are egal), zero extends the bitrepresentation of x to the size of T, or truncates the bitrepresentation of x to sizeof(T).

Returns a T.

See also FieldFlags.cast_or_extend.

source
FieldFlags.cast_or_extend — Function
cast_or_extend(T::DataType, x) -> T

Takes an object x of a primitive type and either bitcasts it to T (if their sizes are egal) or zero-extends the bitrepresentation of x to the size of T. sizeof(x) <= sizeof(T) must hold.

Returns a T.

See also FieldFlags.cast_extend_truncate.

source
+)

Where typedefs are the new user-facing type definition and the internal type definitions, typefuncs are type related functions from Base for the new types, conv are convert methods to those types, propsize is the implementation for FieldFlags.fieldsize, propoffset is the implementation for FieldFlags.propertyoffset, getprop is the definition for the getproperty overload for the user facing type and setprop is the definition for the setproperty! overloda for the user facing type.

See also FieldFlags.bitflags.

source
FieldFlags.cast_extend_truncate — Function
cast_extend_truncate(T::DataType, x) -> T

Takes an object x of a primitive type and either bitcasts it to type T (if their sizes are egal), zero extends the bitrepresentation of x to the size of T, or truncates the bitrepresentation of x to sizeof(T).

Returns a T.

See also FieldFlags.cast_or_extend.

source
FieldFlags.cast_or_extend — Function
cast_or_extend(T::DataType, x) -> T

Takes an object x of a primitive type and either bitcasts it to T (if their sizes are egal) or zero-extends the bitrepresentation of x to the size of T. sizeof(x) <= sizeof(T) must hold.

Returns a T.

See also FieldFlags.cast_extend_truncate.

source
diff --git a/dev/examples/index.html b/dev/examples/index.html index e190c94..9b127e2 100644 --- a/dev/examples/index.html +++ b/dev/examples/index.html @@ -29,4 +29,4 @@ b:3 _ c:2 - end

The above defines a struct MyField, with three fields a, b and c, with sizes (in bits) 1, 3 and 2 respectively. There are also two definitions of explicit padding between fields, the first being 2 bits in size and the second one being 1 bit in size; taken implicitly from _ not having a size annotated. The layout of the above struct is like so:

MSBLSB
10-16cc_bbb__a

With the additional padding bits, we come to a total of 9 bits. This is again rounded up to the next multiple of 8, which is 16 bits or 2 bytes:

julia> sizeof(MyField)2
+ end

The above defines a struct MyField, with three fields a, b and c, with sizes (in bits) 1, 3 and 2 respectively. There are also two definitions of explicit padding between fields, the first being 2 bits in size and the second one being 1 bit in size; taken implicitly from _ not having a size annotated. The layout of the above struct is like so:

MSBLSB
10-16cc_bbb__a

With the additional padding bits, we come to a total of 9 bits. This is again rounded up to the next multiple of 8, which is 16 bits or 2 bytes:

julia> sizeof(MyField)2
diff --git a/dev/index.html b/dev/index.html index 6f944a0..fb06406 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -FieldFlags.jl Documentation · FieldFlags.jl
GitHub

FieldFlags.jl Documentation

FieldFlags.jl is a small package without dependencies, giving users the ability to create structs containing packed integers of various bitsizes.

The two main exports of this package are the two macros @bitflags and @bitfield, for creating bit packed boolean flag structs and bit packed integer field structs respectively.

This package is heavily inspired by C-style bitfields, though there are some limitations.

Goals

  • Low/Negligible overhead
    • I can get a bextract on my machine from extremely high level julia code
  • High performance
  • Good optimization by the compiler (constant folding, elimination of error paths)
    • The package should "feel" as if there were no special implementation
  • Good debuggability with JET.jl

Limitations

  • Thread safety
    • Accessing the objects produced by this package is not thread safe and atomic access is not planned to be supported. Users are advised to use proper locking to ensure safety.
  • Size of the objects
    • Due to a compiler limitation, the size of all objects created by this package is a multiple of 8 bits. This restriction may be removed in the future.
  • Type parameters cannot be supported - the size of a field needs to be known at definition time, so that the various bitshifts and masking operations done internally can be compiled away.
  • The widest a field can currently be is 8*sizeof(UInt) bits, as UInt is currently the default return type for fields (other than those of width 1, which return a Bool).

Planned Features

  • Custom field type annotations
    • This would look like a regular field type annotation for exact sizes (i.e. a::UInt16), or like e.g. a:3::UInt16 for objects that want to store the lower 3 bits of an UInt16 and want to get that type back out when accessing the field.
    • Due to the nature of how these objects are stored internally, the types will need to be at least isbitstype, possibly even isprimitivetype, as it's unclear whether the padding potentially contained in an isbitstype is legal to observe (I suspect it isn't).
    • <: Signed types will need to be at least 2 bits in size, to store the sign bit.
    • See #9 for the issue tracking this.
+FieldFlags.jl Documentation · FieldFlags.jl
GitHub

FieldFlags.jl Documentation

FieldFlags.jl is a small package without dependencies, giving users the ability to create structs containing packed integers of various bitsizes.

The two main exports of this package are the two macros @bitflags and @bitfield, for creating bit packed boolean flag structs and bit packed integer field structs respectively.

This package is heavily inspired by C-style bitfields, though there are some limitations.

Goals

  • Low/Negligible overhead
    • I can get a bextract on my machine from extremely high level julia code
  • High performance
  • Good optimization by the compiler (constant folding, elimination of error paths)
    • The package should "feel" as if there were no special implementation
  • Good debuggability with JET.jl

Limitations

  • Thread safety
    • Accessing the objects produced by this package is not thread safe and atomic access is not planned to be supported. Users are advised to use proper locking to ensure safety.
  • Size of the objects
    • Due to a compiler limitation, the size of all objects created by this package is a multiple of 8 bits. This restriction may be removed in the future.
  • Type parameters cannot be supported - the size of a field needs to be known at definition time, so that the various bitshifts and masking operations done internally can be compiled away.
  • The widest a field can currently be is 8*sizeof(UInt) bits, as UInt is currently the default return type for fields (other than those of width 1, which return a Bool).

Planned Features

  • Custom field type annotations
    • This would look like a regular field type annotation for exact sizes (i.e. a::UInt16), or like e.g. a:3::UInt16 for objects that want to store the lower 3 bits of an UInt16 and want to get that type back out when accessing the field.
    • Due to the nature of how these objects are stored internally, the types will need to be at least isbitstype, possibly even isprimitivetype, as it's unclear whether the padding potentially contained in an isbitstype is legal to observe (I suspect it isn't).
    • <: Signed types will need to be at least 2 bits in size, to store the sign bit.
    • See #9 for the issue tracking this.