This article describes commonly used C++ conventions in the API, and how they map to other supported languages.
C++ conventions
Namespaces
The LuciadCPillar library uses a single namespace luciad
, so that it can easily be distinguished from other libraries.
Grouping of functionality
A folder hierarchy is used to organize the API functionality into groups.
You can see this grouping in the Modules
section of the API reference documentation.
std::optional
Within the API, methods can return a std::optional<T>
to express the possibility that there is no result.
luciad::expected
Within the API, methods can return a luciad::expected<T,ErrorInfo>
to express the possibility that there is no result,
due to an error condition that you must handle.
If the method returns an expected result, you get the value of type T
.
Otherwise, you get an error object of type ErrorInfo
, which provides more information about the problem.
C# conventions
In essence, the LuciadCPillar C# API is the same as the C++ API.
It complies with C# naming conventions. This means that C# namespaces, classes, and method names follow the PascalCasing convention of C#.
The following sections explain how some C++ constructs are mapped within the C# API.
Namespaces
The namespaces for the C# API are related to the C++ API organization into folders. The C++ API uses a single namespace and organizes functionality in folders. The folder names are used as a basis for the C# namespace. The modules within the API reference documentation can be mapped directly to C# namespaces. The folder names are converted to PascalCasing for the C# namespace names.
For example:
-
The C++ class
luciad/cartesian/Coordinate.h
is available asLuciad.Cartesian.Coordinate
within the C# API. -
The C++ class
luciad/geometries/Geometry.h
is available asLuciad.Geometries.Geometry
within the C# API.
std::optional
The C++ optional convention for return values is mapped to C# as follows:
-
For primitive types,
std::optional<int>
is mapped toint?
, for example. -
For reference objects, the C++ method
std::optional<T> myMethod();
becomesT MyMethod()
. The return type of the method is the actual type and the value isnull
when there is no result.
luciad::expected
The luciad::expected C++ convention for return values is mapped to C# as follows:
-
The method
luciad::expected<T,ErrorInfo> myMethod()
becomesT MyMethod
, in which the method returns the actual object. -
The error case is handled by throwing a C#
System.Exception
that uses information of the error objectErrorInfo
.
Java conventions
In essence, the LuciadCPillar Java API is the same as the C++ API.
It complies with Java naming conventions. This means that Java packages, classes, and method names follow the casing conventions of Java.
The following sections explain how some C++ constructs are mapped within the Java API.
Packages
The packages for the Java API are related to the C++ API organization into folders. The C++ API uses a single namespace and organizes functionality in folders. The folder names are used as a basis for the Java package. The modules within the API reference documentation can be mapped directly to Java packages.
For example:
-
The C++ class
luciad/cartesian/Coordinate.h
is available ascom.luciad.cartesian.Coordinate
within the Java API. -
The C++ class
luciad/geometries/Geometry.h
is available ascom.luciad.geometries.Geometry
within the Java API.
std::optional
The C++ optional convention for return values is mapped to Java as follows:
-
For primitive types,
std::optional<int>
is mapped to its corresponding boxed typeInteger
, for example. -
For reference objects, the C++ method
std::optional<T> myMethod();
becomesT MyMethod()
. The return type of the method is the actual type and the value isnull
when there is no result.
luciad::expected
The luciad::expected C++ convention for return values is mapped to Java as follows:
-
The method
luciad::expected<T,ErrorInfo> myMethod()
becomesT MyMethod
, in which the method returns the actual object. -
The error case is handled by throwing a Java Exception that uses information of the error object
ErrorInfo
.
Exceptions
Exceptions in C++ are mapped to Java exceptions in the following way:
-
luciad::NullArgumentException
is mapped tojava.lang.IllegalArgumentException
-
luciad::InvalidArgumentException
is mapped tojava.lang.IllegalArgumentException
-
luciad::IOException
is mapped tojava.io.IOException
-
luciad::LogicException
is mapped tojava.lang.IllegalStateException
-
luciad::LicenseException
is mapped toLicenseException
-
luciad::ParseException
is mapped tojava.text.ParseException
-
Other
luciad::Exception
instances are mapped tojava.lang.RuntimeException