Home

Michael Heilmann's Arcadia Ring 1

This is the documentation for Michael Heilmann's Arcadia Ring 1. Arcadia Ring 1 facilitates the creation of C programs - in particular interpreters - that are portable, maintainable, as well as safe.

Files

You can find the sources of Arcadia Ring 1 in my GitHub repository https://github.com/michaelheilmann/michaelheilmann.com. The subdirectory of Arcadia Ring 1 in the repository is here https://github.com/michaelheilmann/michaelheilmann.com/tree/main/repository/Arcadia.Ring1.

Arcadia Ring 1 supports various platforms (including but not restricted to Windows, Linux, and many more), however, we currently only officially support Windows. For instructions on how to build, test, and use Arcadia Ring 1, refer to README.md in the root folder of the repository.

Further References

Arcadia Ring 1 relies on ARMS1.

Documentation

Arcadia_BooleanValue

typedef implementation detail Arcadia_BooleanValue The C representation of the Arcadia.Boolean type.

Arcadia_BooleanValue_True

#define Arcadia_BooleanValue_True implementation detail The C representation of the value Arcadia.Boolean.True denoting logically true. It converts to 1 in arithmetic expressions.

Arcadia_BooleanValue_False

#define Arcadia_BooleanValue_False implementation detail The C representation of the value Arcadia.Boolean.False denoting logically false. It converts to 0 in arithmetic expressions.

Arcadia_ForeignProcedureValue

typedef implementation detail Arcadia_ForeignProcedureValue; A pointer to a function adhering to the calling conventions for C functions.

Arcadia_ForeignProcedureValue_Null

#define Arcadia_ForeignProcedureValue_Null implementation detail The Arcadia_ForeignProcedureValue value indicating the absence of a function. This usually evaluates to ((void*)0).

Arcadia_ForeignProcedureValue_NumberOfBits

#define Arcadia_ForeignProcedureValue_NumberOfBits implementation detail The number of Bits an Arcadia_ForeignProcedureValue occupies. This is a value is a positive multiple of 8.

Arcadia_ForeignProcedureValue_NumberOfBytes

#define Arcadia_ForeignProcedureValue_NumberOfBytes implementation detail The number of Bytes of the type which is usually Arcadia_ForeignProcedureValue_NumberOfBits divided by 8.

Arcadia_Integer*Value

typedef implementation detail Arcadia_IntegerSuffixValue Two's complment integer number types where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

Arcadia_Integer*Value_NumberOfBits

#define Arcadia_IntegerSuffixValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_IntegerSuffix occupies where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64. The value is always equal to the value of the respective Suffix.

Arcadia_Integer*Value_NumberOfBytes

#define Arcadia_IntegerSuffixValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_IntegerSuffixValue occupies where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64. The value is always equal to Arcadia_IntegerSuffixValue_NumberOfBits divided by 8.

Arcadia_Integer*Value_Minimum

#define Arcadia_IntegerSuffixValue_Minimum implementation detail The least value representable by a the Arcadia_IntegerSuffixValue type where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 -128
16 -32768
32 -2147483648
64 -9223372036854775808

Arcadia_Integer*Value_Maximum

#define Arcadia_IntegerSuffixValue_Maximum implementation detail The greatest value representable by a the Arcadia_IntegerSuffixValue type where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The following table denotes the value of the constant for the respective Suffix

SuffixValue
8 127
16 32767
32 2147483647
64 9223372036854775807

Arcadia_Integer*Value_Literal

#define Arcadia_IntegerSuffixValue_Literal(x) implementation detail Macro used to write a literal of the type Arcadia_IntegerSuffixValue in C source code where Suffix denotes the number of Bits of the two's complement integer and can be one of 8, 16, 32, or 64.

The following table denotes the expansions of the macro:

SuffixValue
8 x
16 x
32 x
64 x##LL

Arcadia_Natural*Value

typedef implementation detail Arcadia_NaturalSuffixValue Unsigned integer number type where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64.

Arcadia_Natural*Value_NumberOfBits

#define Arcadia_NaturalSuffixValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_NaturalSuffix occupies where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64. The value is always equal to the value of the respective Suffix.

Arcadia_Natural*Value_NumberOfBytes

#define Arcadia_IntegerSuffixValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_NaturalSuffixValue occupies where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64. The value is always equal to Arcadia_NaturalSuffixValue_NumberOfBits divided by 8.

Arcadia_Natural*Value_Minimum

#define Arcadia_NaturalSuffixValue_Minimum implementation detail The least value representable by a the Arcadia_NaturalSuffixValue type where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64. Suffix

SuffixValue
8 0
16 0
32 0
64 0

Arcadia_Natural*Value_Maximum

#define Arcadia_NaturalSuffixValue_Maximum implementation detail The greatest value representable by a the Arcadia_NaturalSuffixValue type where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64.

The following table denotes the value of the constant for the respective Suffix

ConstantValue
8 255
16 65535
32 4294967295
64 18446744073709551615

Arcadia_Natural*Value_Literal

#define Arcadia_NatualSuffixValue_Literal(x) implementation detail Macro used to write a literal of the type Arcadia_NaturalSuffixValue in C source code where Suffix denotes the number of Bits of the unsigned integer and can be one of 8, 16, 32, or 64.

The following table denotes the expansions of the macro:

SuffixValue
8 x
16 x
32 x##U
64 x##ULL

Arcadia_ObjectReferenceValue

Arcadia Ring 1 provides a ObjectReference type.

typedef implementation detail Arcadia_ObjectReferenceValue

The Arcadia_ObjectReferenceValue type is a pointer.

A valid value of the Arcadia_ObjectReferenceValue is the null reference

#define Arcadia_ObjectReferenceValue_Null implementation detail

#define Arcadia_ObjectReferenceValue_NumberOfBits implementation detail

denotes the number of Bits of the type.

#define Arcadia_ObjectReferenceValue_NumberOfBytes implementation detail

denotes the number of Bytes of the type which is usually Arcadia_ObjectReferenceValue_NumberOfBits divided by 8.

Arcadia_Real*Value

typedef implementation detail Arcadia_RealSuffixValue IEEE 754 binary real number type where Suffix denotes the number of Bits of the type and can be one of 32 or 64.

Arcadia_Real*Value_NumberOfBits

The macros in this section all include the Suffix metavariable and are defined for the values 32 and 64.

#define Arcadia_RealSuffixValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_VoidValue occupies where Suffix denotes the number of Bits of the type and can be one of 32 or 64. This is a positive multiple of 8.

Arcadia_Real*Value_NumberOfBytes

#define Arcadia_RealSuffixValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_RealSuffixValue occupies where Suffix denotes the number of Bits of the type and can be one of 32 or 64. The value is always equal to Arcadia_RealSuffixValue_NumberOfBits divided by 8.

Arcadia_Real*Value_Minimum

#define Arcadia_RealSuffixValue_Minimum implementation detail The least value representable by a the Arcadia_RealSuffixValue type where Suffix denotes the number of Bits of the type and can be one of 32 or 64. summary>

The following table denotes the value of the constant for the respective Suffix

SuffixValue
32 -FLT_MAX
64 -DBL_MAX

Arcadia_Real*Value_Maximum

#define Arcadia_RealSuffixValue_Maximum implementation detail The greatest value representable by a the Arcadia_RealSuffixValue type.

The following table denotes the value of the constant for the respective Suffix

ConstantValue
32 +FLT_MAX
64 +DBL_MAX

Arcadia_Real*Value_getBits

Arcadia_NaturalBits
Arcadia_RealBitsValue_getBits
(
Arcadia_Thread* thread,
Arcadia_RealBitsValue self
) Get the bits of an Arcadia_RealSuffixValue where Suffix denotes the number of Bits of the type and can be one of 32 or 64.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Arcadia_RealBits self
The Real value.

Return value

Return the bits of the Real value as a Natural value.

Size Type

typedef implementation detail Arcadia_SizeValue An alias for the builtin size_t type.

Arcadia_SizeValue_NumberOfBits

#define Arcadia_SizeValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_SizeValue occupies. This is a positive multiple of 8. This number must one of 32 or 64, otherwise the environment is not supported by Arcadia Ring 1. This restriction may be relaxed in future versions of Arcadia Ring 1.

Arcadia_SizeValue_NumberOfBytes

#define Arcadia_SizeValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_SizeValue occupies. The value is always equal to Arcadia_SizeValue divided by 8.

Arcadia_SizeValue_Minimum

#define Arcadia_SizeValue_Minimum implementation detail The least value representable by a the Arcadia_SizeValue type.

Arcadia_SizeValue_Maximum

#define Arcadia_SizeValue_Maximum implementation detail The greatest value representable by a the Arcadia_SizeValue type.

Arcadia_SizeValue_Maximum

#define Arcadia_SizeValue_Literal(x) implementation detail Macro used to write a literal of the type Arcadia_SizeValue in C source code.

Arcadia_VoidValue

typedef implementation detail Arcadia_VoidValue The only value of this type is Arcadia_VoidValue_Void. Arcadia_VoidValue is an unsigned integral type.

Arcadia_VoidValue_Void

#define Arcadia_VoidValue_Void implementation detail The single value of the type Arcadia_VoidValue.

Arcadia_VoidValue_NumberOfBits

#define Arcadia_VoidValue_NumberOfBits implementation detail The number of Bits of a value of the type Arcadia_VoidValue occupies. This is a positive multiple of 8.

Arcadia_VoidValue_NumberOfBytes

#define Arcadia_VoidValue_NumberOfBytes implementation detail The number of Bytes a value of the type Arcadia_VoidValue occupies. The value is always equal to Arcadia_VoidValue divided by 8.

Value Type

Arcadia_Value is a tagged union of values supported by the runtime. It consists of a tag indicating the value stored in the union and the union of the values. The following table lists all possible tags and their corresponding type.

Tag Type
Arcadia_ValueTag_Boolean Arcadia_BooleanValue
Arcadia_ValueTag_Integer16 Arcadia_Integer16Value
Arcadia_ValueTag_Integer32 Arcadia_Integer32Value
Arcadia_ValueTag_Integer64 Arcadia_Integer64Value
Arcadia_ValueTag_Integer8 Arcadia_Integer8Value
Arcadia_ValueTag_Natural16 Arcadia_Natural16Value
Arcadia_ValueTag_Natural32 Arcadia_Natural32Value
Arcadia_ValueTag_Natural64 Arcadia_Natural64Value
Arcadia_ValueTag_Natural8 Arcadia_Natural8Value
Arcadia_ValueTag_ObjectReferenceArcadia_ObjectReferenceValue
Arcadia_ValueTag_Size Arcadia_SizeValue
Arcadia_ValueTag_Void Arcadia_VoidValue

For each type, Arcadia_Value has three functions associated:

Type Arcadia_Value_getSuffix(Arcadia_Value const* value)
bool Arcadia_Value_isSuffix(Arcadia_Value const* value)
void Arcadia_Value_setSuffix(Arcadia_Value* value, Arcadia_SuffixValue VariableValue)

The following table lists the valid combinations of Suffix and Variable

Boolean boolean
Integer16 integer16
Integer32 integer32
Integer64 integer64
Integer8 integer8
Natural16 natural16
Natural32 natural32
Natural64 natural64
Natural8 natural8
ObjectReferenceobjectReference
Size size
Void void

Arcadia_Value_isSuffix returns true if the Arcadia_Value stores a value of the type corresponding to Suffix. Otherwise it returns false.

Arcadia_Value_setSuffix assigns the Arcadia_Value a value of the type corresponding to Suffix.

Arcadia_Value_getType get the value stored in the Arcadia_Value. The behavior of Arcadia_Value_setSuffix is undefined if the value does not store a value of the type corresponding to Suffix.

Status Codes

R provides a status type and symbolic constants for its values. That type denotes success or failure of program (or a part of it) as well as information on the reason for the failure.

typedef implementation detail Arcadia_Status

Arcadia_Status is a natural number type of a width of 32 Bit.

#definer Arcadia_Status_Success implementation detail

is the symbolic constant of the type Arcadia_Status has the value ((Arcadia_Status)0). It denotes success and is guaranteed to be defined to the value 0 of the underlaying natural number type of Arcadia_Status as well as to be the only symbolic constant starting with Arcadia_Status_ having defined to that value.

Symbolic constants of the form

#definer Arcadia_Status_Name implementation detail

where Name is not Success provide information on failure of a program (or a part of it). The following table denotes the value of the constant for the respective Name

Name Value
AllocationFailed An allocation failed.
ArgumentTypeInvalid The type of an argument is invalid.
ArgumentValueInvalid The value of an argument is invalid.
ConversionFailed A conversion failed.
DivisionByZero An divions by zero was detected.
EncodingInvalid An encoding is invalid.
Exists Something exists (but should not).
FileSystemOperationFailedA file system operation failed.
Initialized Something was initialized (but should not have been initialized).
NotExists Something does not exist.
NumberOfArgumentsInvalid The number of arguments is invalid.
OperationInvalid An operation is invalid.
SemanticalError
SyntacticalError
TestFailed A test failed. This is used by the built-in tests that ensure correctness.
TypeExists A type exists (but should not).
TypeNotExists A type does not exist (but should).
Uninitialized Something was uninitialized (but should have been initialized).

Status Variable

Arcadia.Ring1 provides by-thread status variable.

Arcadia_Status Arcadia_Thread_getStatus ( Arcadia_Thread* thread );

gets the value of the status variable. The initial value of the status variable is Arcadia_Status_Success.

void Arcadia_Thread_setStatus ( Arcadia_Thread* thread, Arcadia_Status status );

sets the value of the status variable to the value status.

Jumps and Jump Targets

Arcadia.Ring1 provides non-local jumps by allowing to save and restore the C program state.

typedef implementation detail Arcadia_JumpTarget;

is a type of which its values are stack allocated.

void Arcadia_Thread_pushJumpTarget(Arcadia_Thread* thread, Arcadia_JumpTarget* jumpTarget);

Push a jump target on top of the jump target stack. Initially, the jump target stack is empty.

void Arcadia_Thread_popJumpTarget(Arcadia_Thread* thread);

Pop the jump target on top of the jump target stack. The jump target stack must not be empty.

void Arcadia_jump(Arcadia_Thread* thread);

Jump to the jump target on top of the jump target stack. The jump target stack must not be empty.

#define Arcadia_JumpTarget_save(jumpTarget) implementation detail

Macro to save the current C program state into a jump target.

The canonical way of using Arcadia_Thread_pushJumpTarget, Arcadia_Thread_popJumpTarget, and Arcadia_Thread_jump is the following.

Arcadia_Thread_pushJumpTarget(thread, &jumpTarget);
if (Arcadia_JumpTarget_save(thread, &jumpTarget)) {
 (1)
 Arcadia_Thread_popJumpTarget(thread);(2)
} else {
 Arcadia_Thread_popJumpTarget(thread);(3)
 (4)
}
(5)

The if-branch is always entered at first as the Arcadia_JumpTarget_save() at its first invocation returns logically true. If the program at (1) does not jump to the jump target (using Arcadia_Thread_jump()), then Arcadia_Thread_popJumpTarget(); (2) and (5) are executed. If the program at (1) jumps to the jump target, then Arcadia_Thread_JumpTarget_save() is re-evaluated and returns logically false and Arcadia_Thread_popJumpTarget();(2) and (4) is executed.

One usage example is the implementation of the Arcadia_safeExecute function.

void Arcadia_safeExecute(Arcadia_Thread* thread, void (*f)(Arcadia_Thread*)) {
 Arcadia_JumpTarget jumpTarget;
 Arcadia_Thread_pushJumpTarget(thread, &jumpTarget);
 if (Arcadia_Thread_JumpTarget_save(thread, &jumpTarget)) {
  f();
  Arcadia_Thread_popJumpTarget(thread);
 }
}

Numeric functions

Arcadia_clamp*

Type
Arcadia_clampSuffix
 (
  Arcadia_Thread* thread,
  Type value,
  Type lower,
  Type upper
 ) Clamp a value to a range.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type value
The value to clamp.
Type lower
The lower bound (inclusive).
Type upper
The upper bound (inclusive).

This function returns the value value clamped to the range [lower, upper].

Errors

Arcadia_Status_ArgumentValueInvalid
lower > upper
Arcadia_Status_EncodingInvalid
The sequence of Bytes does not represented a UTF-8-NO-BOM string.

Return value

The value value clamped to the range [lower, upper].

Arcadia_countLeadingZeroes*

Arcadia_SizeValue
Arcadia_countLeadingZeroesSuffix
 (
  Arcadia_Thread* thread,
  Type value
 ) Return the number of leading zeroes of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function returns the number of leading zeroes of the binary representation of value.

Parameters
Arcadia_Thread* threadA pointer to the Arcadia_Thread object.
Type valueThe value.
Return value

The number of leading zeroes.

Arcadia_countSignificandBits*

Arcadia_SizeValue
Arcadia_countSignificandBitsSuffix
 (
  Arcadia_Thread* thread,
  Type value
 ) Get the number of significand Bits of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function returns the number of significand Bits of the binary representation of value.

Parameters
Arcadia_Thread* threadA pointer to the Arcadia_Thread object.
Type valueThe value.
Return value

The number of significand Bits.

Arcadia_hash*

Arcadia_SizeValue
Arcadia_hashSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the hash of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
BooleanValue Arcadia_BooleanValue
ForeignProcedureValueArcadia_ForeignProcedureValue
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
Real32Value Arcadia_Real32Value
Real64Value Arcadia_Real64Value
SizeValue Arcadia_SizeValue
VoidValue Arcadia_VoidValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Return value

Return hash of x.

Arcadia_isPowerOfTwo*

Arcadia_BooleanValue
Arcadia_isPowerOfTwoSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Get if a value is a power of two.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Return value

Arcadia_BooleanValue_True if the value x/ is a power of two. Arcadia_BooleanValue_False otherwise.

Arcadia_maximum*

Type
Arcadia_maximumSuffix
 (
  Arcadia_Thread* thread,
  Type x,
  Type y
 ) Return the maximum of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Integer8ValueArcadia_Integer8Value
Integer16ValueArcadia_Integer16Value
Integer32ValueArcadia_Integer32Value
Integer64ValueArcadia_Integer64Value
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The first value.
Type y
The second value.

Return value

Return the maximum of x and y.

Arcadia_minimum*

Type
Arcadia_minimumSuffix
 (
  Arcadia_Thread* thread,
  Type x,
  Type y
 ) Compute the minimum of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8ValueArcadia_Integer8Value
Integer16ValueArcadia_Integer16Value
Integer32ValueArcadia_Integer32Value
Integer64ValueArcadia_Integer64Value
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The first value.
Type y
The second value.

Return value

Return the minimum of x and y.

Arcadia_nextPowerOfTwoGreaterThan*

Type
Arcadia_nextPowerOfTwoGreaterThanSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Get the next power of two greater than a specified value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Errors

Arcadia_Status_NotExists
The next power of two greater than x is not representable by the type Type

Return value

Return the next power of two greater than x.

Arcadia_nextPowerOfTwoGreaterThanOrEqualTo*

Type
Arcadia_nextPowerOfTwoGreaterThanOrEqualToSuffix
 (
  Arcadia_Thread* thread,
  Type x
 ) Compute the next power of two greater then or equal to a specified value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The value.

Errors

Arcadia_Status_NotExists
The next power of two greater greater than or equal to x is not representable by the type Type

Return value

Return the next power of two greater than or equal to x.

Arcadia_quotientRemainder*

void
Arcadia_quotientRemainderSuffix
 (
  Arcadia_Thread* thread,
  Type dividend,
  Type divisor,
  Type* quotient,
  Type* remainder
 ) Return the number of significand Bits of the binary representation of a value.

The following table lists the combinations of Type and Suffix for which the above functions are defined

SuffixType
Integer8Value Arcadia_Integer8Value
Integer16Value Arcadia_Integer16Value
Integer32Value Arcadia_Integer32Value
Integer64Value Arcadia_Integer64Value
Natural8Value Arcadia_Natural8Value
Natural16Value Arcadia_Natural16Value
Natural32Value Arcadia_Natural32Value
Natural64Value Arcadia_Natural64Value
SizeValue Arcadia_SizeValue

This function computes the quotient q = dividend / divisor and the remainder r = dividend - (q * divisor). The quotient is stored in *quotient and the divisor is stored in *remainder.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type dividend
The dividend.
Type divisor
The divisor.
Type quotient
Variable to store the quotient in.
Type remainder
Variable to store the remainder in.

Errors

Arcadia_Status_ArgumentValueInvalid
quotient or remainder is zero.
Arcadia_Status_DivisionByZero
The divisor is zero.

Arcadia_safeAdd*

void
Arcadia_safeAddSuffix
 (
  Arcadia_Thread* thread,
  Type augend,
  Type addend,
  Type* sumHigh,
  Type* sumLow
 ) Compute the sum of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
Natural8Value Arcadia_Natural8Value
SizeValue Arcadia_SizeValue
Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type augend
The augend value.
Type addend
The addend value.
Type* sumHigh
A pointer to a variable. The variable is assigned the high bits of the result.
Type* sumLow
A pointer to a variable. The variable is assigned the low bits of the result.

Arcadia_safeMultiply*

void
Arcadia_safeMultiplySuffix
 (
  Arcadia_Thread* thread,
  Type x,
  Type y
 ) Compute the product of two values.

The following table lists the combinations of Type and Suffix for which the above functions are defined

Suffix Type
Natural8ValueArcadia_Natural8Value
Natural16ValueArcadia_Natural16Value
Natural32ValueArcadia_Natural32Value
Natural64ValueArcadia_Natural64Value
SizeValueArcadia_SizeValue

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
Type x
The first value.
Type y
The second value.

Return value

Return the maximum of x and y.

Time and Date Functions

Arcadia_getTickCount

Arcadia_Natural64Value
Arcadia_getTickCount
 (
  Arcadia_Thread* thread
 ) Get the time, in milliseconds, since an unspecified moment in the past.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.

Return value

The time, in milliseconds, since an unspecified momentn in the past.

Unicode Functions

Arcadia_isUtf8

Arcadia_BooleanValue
Arcadia_isUtf8
 (
  Arcadia_Thread* thread,
  const void* bytes,
  Arcadia_SizeValue numberOfBytes,
  Arcadia_SizeValue* numberOfSymbols
 ) Get if a sequence of Bytes is an UTF-8 sequence of Bytes and count its number of symbols.

Parameters

Arcadia_Thread* thread
A pointer to the Arcadia_Thread object.
const void* bytes
A pointer to an array of numberOfBytes Bytes.
Arcadia_SizeValue numberOfBytes
The number of Bytes in the array of Bytes pointed to by bytes.
Arcadia_SizeValue* numberOfSymbols
The number of Bytes in the array of Bytes pointed to by bytes. If this function terminates and this pointer is not null, the variable is assigned the number of symbols decoded successfully so far.

Return value

Arcadia_BooleanValue_True if the sequence of numberOfBytes Bytes pointed to by bytes is an UTF-8 sequence of Bytes. Arcadia_BooleanValue_False otherwise.

Arcadia_Value

Arcadia_Value is a tagged union of values supported by the runtime. It consists of a tag indicating the value stored in the union and the union of the values. The following table lists all possible tags and their corresponding type.

Tag Type
Arcadia_ValueTag_Atom n Arcadia_AtomValue
Arcadia_ValueTag_Boolean Arcadia_BooleanValue
Arcadia_ValueTag_Integer16 Arcadia_Integer16Value
Arcadia_ValueTag_Integer32 Arcadia_Integer32Value
Arcadia_ValueTag_Integer64 Arcadia_Integer64Value
Arcadia_ValueTag_Integer8 Arcadia_Integer8Value
Arcadia_ValueTag_Natural16 Arcadia_Natural16Value
Arcadia_ValueTag_Natural32 Arcadia_Natural32Value
Arcadia_ValueTag_Natural64 Arcadia_Natural64Value
Arcadia_ValueTag_Natural8 Arcadia_Natural8Value
Arcadia_ValueTag_ObjectReferenceArcadia_ObjectReferenceValue
Arcadia_ValueTag_Real32 Arcadia_Real32Value
Arcadia_ValueTag_Real64 Arcadia_Real64Value
Arcadia_ValueTag_Size Arcadia_SizeValue
Arcadia_ValueTag_Type Arcadia_TypeValue
Arcadia_ValueTag_Void Arcadia_VoidValue

For each type, Arcadia_Value has three functions associated:

Type Arcadia_Value_getSuffix(Arcadia_Value const* value)
bool Arcadia_Value_isSuffix(Arcadia_Value const* value)
void Arcadia_Value_setSuffix(Arcadia_Value* value, Arcadia_SuffixValue VariableValue)

The following table lists the valid combinations of Suffix and Variable

Atom atom
Boolean boolean
Integer16 integer16
Integer32 integer32
Integer64 integer64
Integer8 integer8
Natural16 natural16
Natural32 natural32
Natural64 natural64
Natural8 natural8
Real32 reall32
Real64 real64
ObjectReferenceobjectReference
Size size
Type type
Void void

Arcadia_Value_isSuffix returns true if the Arcadia_Value stores a value of the type corresponding to Suffix. Otherwise it returns false.

Arcadia_Value_setSuffix assigns the Arcadia_Value a value of the type corresponding to Suffix.

Arcadia_Value_getType get the value stored in the Arcadia_Value. The behavior of Arcadia_Value_setSuffix is undefined if the value does not store a value of the type corresponding to Suffix.

hash

Arcadia_Size Arcadia_Value_hash ( Arcadia_Process* process, Arcadia_Value* self );

Get the hash value of this Arcadia_Value.

Parameters
processA pointer to the Arcadia_Process object.
selfA pointer to this Arcadia_Value object.
Return value

The hash of the value of the value of thisArcadia_Value object.

isEqualTo

Arcadia_BooleanValue Arcadia_Value_isEqualTo ( Arcadia_Process* process, Arcadia_Value* self, Arcadia_Value* other );

Compare the value of this Arcadia_Value object to the value of another Arcadia_Value object.

Parameters
processA pointer to the Arcadia_Process object.
selfA pointer to this Arcadia_Value object.
objectA pointer to the other Arcadia_Value object.
Return value

Arcadia_BooleanValue_True if the value of this Arcadia_Value object is equal to the value of the other Arcadia_Value object. Arcadia_BooleanValue_False otherwise.

isEqualTo

Arcadia_TypeValue Arcadia_Value_isEqualTo ( Arcadia_Process* process, Arcadia_Value* self );

Get thet type of the value of this Arcadia_Value object.

Parameters
processA pointer to the Arcadia_Process object.
selfA pointer to this Arcadia_Value object.
Return value

The type of the value of this Arcadia_Value object.