This article describes commonly used C++ conventions in the API, and how they map to other supported languages.

C++ conventions

What can you implement?

Implement pure virtual classes prefixed with I only.

Namespaces

The LuciadCPillar library uses a single namespace luciadluciadluciad, 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 ErrorInfoErrorInfoErrorInfo, 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.

What can you implement?

Implement interfaces prefixed with I only.

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 as Luciad.Cartesian.Coordinate within the C# API.

  • The C++ class luciad/geometries/Geometry.h is available as Luciad.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 to int?, for example.

  • For reference objects, the C++ method std::optional<T> myMethod(); becomes T MyMethod(). The return type of the method is the actual type and the value is null 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() becomes T 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 object ErrorInfoErrorInfoErrorInfo.

Exceptions

Exceptions in C++ are mapped to C# exceptions in the following way:

  • luciad::NullArgumentException is mapped to System.ArgumentNullException

  • luciad::InvalidArgumentException is mapped to System.ArgumentException

  • Other luciad::Exception instances are mapped to System.ApplicationException

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.

What can you implement?

Implement interfaces prefixed with I only.

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 as com.luciad.cartesian.Coordinate within the Java API.

  • The C++ class luciad/geometries/Geometry.h is available as com.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 type Integer, for example.

  • For reference objects, the C++ method std::optional<T> myMethod(); becomes T MyMethod(). The return type of the method is the actual type and the value is null 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() becomes T 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 ErrorInfoErrorInfoErrorInfo.

Exceptions

Exceptions in C++ are mapped to Java exceptions in the following way:

  • luciad::NullArgumentException is mapped to java.lang.IllegalArgumentException

  • luciad::InvalidArgumentException is mapped to java.lang.IllegalArgumentException

  • luciad::IOException is mapped to java.io.IOException

  • luciad::LogicException is mapped to java.lang.IllegalStateException

  • luciad::LicenseException is mapped to LicenseExceptionLicenseExceptionLicenseException

  • luciad::ParseException is mapped to java.text.ParseException

  • luciad::NotImplementedException is mapped to java.text.UnsupportedOperationException

  • Other luciad::Exception instances are mapped to java.lang.RuntimeException