///
/// Besides, the exception safety is considered /// while implementing the functions, especially the constructors. /// If possible, throw statements are located before any memory allocation or /// side effects like global/static data modification (e.g. reference count incrementation) /// Together with Rule of zero, this exception safety applications /// provides a code more appropriate to RAII idiom. /// 3. Resource management to achieve RAII is based on the smart pointers. /// The new operator is used only once in GlobalCoordSystem singleton static function /// together with the shared pointer constructor. /// The library does not use resources like I/O streams. /// However, special data structures (containers) for the library are CURRENTLY under construction. ///
/// In order to have a well-established code in terms of RAII, /// a strong guarantee for the exception safety is required to eliminate all memory leaks /// which is CURRENTLY not supported with GeometryLibrary_CPP11. /// The reason for this situation is that /// the library does not deal with significant resources (excluding the containers being impelemted): /// std::string, std::array and std::vector are used with a very small size. /// For example, the point coordinates are stored in a std::array with 3 elements. /// /// Some of the operations on the data structures (e.g. extending the data structure) throw exception. /// Hence, the functions dealing with the containers being implemented shall be designed to supply /// at least the strong exception guarantee. /// More detailed study for each function to have a strong exception gurantee WILL BE PERFORMED. /// Additionally, tools like Copy & Swap idiom will also be utilized /// especially for the special functions to improve the thread safety together with the exception safety. ///
/// Another point, which comes with the ownership issue, is the parametric design of a geometry library. /// Most of the CAE tools (e.g. Catia) support parametric design. /// Consider, a line defined by two points. /// Consider one of the points is updated. /// a. Parametric Framework (Catia): Updates the line accordingly /// Actually, the data of the line is not updated. /// Only, the visual representation of the line on the GUI is updated. /// b. Non-parametric Framework (MSC.PATRAN): Does not update the line. /// The reason of the above results is as follows: /// a. Parametric Framework (Catia): Line object is defined by two point objects /// Hence, the line is updated when points are updated. /// b. Non-parametric Framework (MSC.PATRAN): Line object is defined by numeric data. /// When the ctor of the line object is called with two points /// the ctor calculates the required parameters to define the line by two points /// and stores these numeric data into the new object instead of the points. /// Hence, the line object and the point objects are independent. /// Hence, the object ownership is crutial in order to have a parametric geometry library. /// 4. Shared ownership is implemented on all objects in the library via std::shared_ptr. /// For example, a Line object has ownership on two Point3D objects through c_endPoint0 and c_endPoint1 members. /// These point objects may be owned by other objects (e.g. an Axis object or another Line object). ///
/// Exclusive ownership (std::unique_ptr) is not considered relevant for the implementation of Geometry Library. /// Weak pointers (std::weak_ptr) are either not used. /// An application of the weak pointers would be to count the shared ownership on an object. /// This is actually required: /// Consider a user of the final product (i.e. the GUI) wants to delete a point. /// The forced delete operation by the user shall be canceled if any object has an ownership on that point. /// Weak pointers could be utilized in this respect. /// THIS SITUATION WILL BE STUDIED DETAILY IN THE FUTURE. /// Currently, weak pointers are not used to save memory /// Besides, a more optimistic solution (a special data structure?) can be determined. /// /// Smart pointers are used in function arguments in order to transfer ownership into the function. /// If ownership transfer is not required, /// the traditional const reference approach (const Type&) is followed. /// 5. The shared ownership between the objects /// is actually the implementation of an association/aggregation relationship /// between the objects of this library. /// For example, an axis object delegates the space calculus calculations to the Vector member. /// The class hierarchy is studied at the beginning of GeometryLibrary_CPP11 project. /// A Line object is decided to delegate some geometrical functions to an Axis object /// passing through the line /// while the inheritance relationship could also be used. /// However, there is no solid need to have more complex class hierarchy /// while the aggregation works well. /// 6. The objects in the library are defined in an implementation hyerarchy. /// The slicing problem that comes with the inheritance is /// solved by using pointers and references. /// THE CLIENTS OF THE LIBRARY SHOULD PAY ATTENTION ON THIS BASIC RULE. /// 7. The side effects must be considered together with the exception safety and memory leaks /// as they may cause vital problems /// The side effects must be inspected to achieve at least a strong exception guarantee. /// Followings are some of the cases where there exist side effects: /// a. Some of the constructors, copy constructors and assignments. /// For example, CURRENT version of GeometryObject contains the static ID member /// which is incremented and decremented in the constructor and destructor respectively. /// This issue is explained below in more detail. /// Another example, Circle constructor by 3 points, /// creates a Point object as the center point and a Plane object as the reference plane. /// b. The static counter for the GeometryObjects (GeometryObject::c_IDCounter). /// The counter is incremented when a GeometryObject is created /// and decremented when destructed. /// Both actions are side effects but the decrement operation is more problematic. /// See below with CAUTION FOR STATIC ID COUNTER heading for the details. /// The side effect in the destructor can be defeated /// by removing the decrement in the GeometryObject's destructor /// and letting it to have large values. /// But, this is not preferable /// as the ID member of GeometryObjects is used for the container hashing /// and large values will reduce the effectivity of the hash function. /// c. The containers currently being implemented are configured based on the three issues: /// a. Container and iterator /// b. The factory for the geometry objects /// c. The static ID counter /// The 2nd and the 3rd issues contains side effects. /// d. As specified before, the Equation Coefficients (EC) members of Axis and Plane objects /// of GeometryLibrary_OCCT are removed in GeometryLibrary_CPP11. /// Similarly, magnitude and length members of Vector and Line objects respectively are also removed. /// All of these members cause side effects /// as the setter methods of these classes must also modify one of these members /// together with the actual member to be set. /// The fundamental rule requires a unique setter for each member. /// Hence, these inter-related members are all removed. /// e. Some of the setters has side effects too. /// Consider a Line object with two points /// The points by definition of a line cannot be coincident /// which is inspecteed during the construction of the line objects. /// Let's consider we modified the location of one of the points. /// As a result, the line object will also modified PHYSICALLY. /// However, the state of the line object is not changed, /// as we removed the length member from Line class. /// The line is still the same pointing to the same two points. /// However, another condition exists. /// Lets consider we relocated the point where the other point exists. /// Now, the line becomes exceptional. /// We CURRENTLY cannot prevent this relocation /// as we do not inspect all objects sharing the ownership of an object /// when the object is modified. /// Hence, the coordinate setter of Point class has side effects. /// f. Many people consider that, for C++, the exceptions are side effects, /// as C++ does not have exception specification in the function definition (e.g. Java). /// The clients are not constrained to take the required action /// when an exception is thrown by the called function. /// Hence, the exception may not be considered to fulfill its duty /// to convert our partial function into a total function. /// /// The library contains many functions, even ctors, throwing. /// These functions may all be considered to have side effects. /// 8. Template and auto type deductions are CURRENTLY studied carefully. /// The initializer lists are not used together with auto types to simplify initializer list initializations. /// Both of the C++11 and C++14 type deduced function declarations are used /// C++11: auto identifier(args...) -> return_type /// C++14: auto identifier(args...) OR decltype(auto) identifier(args...) /// 9. Rvalue references are considered (if reasonable) together with the lvalue references for optimization. /// However, this library rarely has a separate function for the rvalue reference argument /// Ex: GeometryObject::setName(std::string&& theName) /// /// Instead, mostly, universal references are used. /// Ex: In Vector2D: /// auto add(T&& theVector) const /// ->std::shared_ptr<typename std::remove_const_t<std::remove_reference_t<decltype(theVector)>>>; /// Many functions rely on the universal references. /// A fundamental problem with the rvalue references is /// a result of the template type deduction together with the explicit constructors. /// For example, consider the above example (Vector2D::add(T&&)). /// Lets consider if the function has been defined with a universal reference. /// That template function would firstly inspect if the base type of the input parameter is VectorBase. /// Both Vector2D and Vector3D are acceptable. /// And both have explicit ctors with a std::array<double, 3>. /// Hence, in the client code, the compiler could not distinguish the type deduction /// for an rvalue std::array<double, 3> input to the add template function. /// It is realy hard to determine the cause of such a compiler error for a client developer. ///
/// Keep in mind that, despite of having a similar functionality, /// GeometryObject::Clone, does not use universal reference for the input argument /// as it does not make sence to clone a temporary object. /// 10. Copy elision, RVO and NRVO studied carefully. /// Most of the time, even standards on the issue differ between C++11 and C++17, /// leaving the optimization to the compiler is mostly more efficient. /// Explicit actions blocking the copy elision, RVO and NRVO has held only in a few locations: /// returning an rvalue reference with std::move /// returning a universal reference with std::forward /// returning with a trinary operator /// 11. C++98 enums used in GeometryLibrary_OCCT are still in use in this library (GeometryLibrary_CPP11) /// as a quite long time is required to update /// the library for the new enum class of C++11 /// because enum variables are used in too many locations as integer variables. /// 12. The source files (e.g. Axis.cxx) includes all headers /// and the header files are include guarded (i.e. #ifndef directive). /// This is the current strategy which is quite easy to compile the library without linking errors. /// However, this approach creates too much code at the end of the preprocess /// due to the inclusion of all headers some of which are redundant for the source file. /// The header file include directives will be rearranged for each source file ASAP. /// 13. The interface base class ReferenceAbstractObject in GeometryLibrary_OCCT /// is removed to have a simple class hyerarchy as it was totally redundant. /// 14. Protected class members in GeometryLibrary_OCCT is made private in this library for encapsulation. /// As is well known, protected variables are accessible by just simple inheritance /// and this breaks LSP (Liskov Substitution Principle), OCP (Open-Closed Principle). /// 15. GlobalCoordSystem is a singleton class /// as a space can be defined by only one global CS. /// However, the singleton static private member is defined by a shared pointer /// as ReferenceObjects must have a CS member with a shared owvership. /// A ReferenceObject object is created refering to the global CS /// if a CS is not supplied by the user. /// Hence, despite being a singleton, GlobalCoordSystem's /// private static member is defined by a shared pointer. /// The reference count of the private static shared pointer member /// incremented to 1 when the public getter (getGlobalCoordSystem) is called. /// Hence, the reference counter is 1 for the global CS /// even all the objects refering to it are out off scope. /// Besides, despite of being a singleton, the dtor is not removed. /// The discussion is quite long, hence, refer to the docstring of GlobalCoordSystem header file. ///
///
///
///
/// /// /// /// B. DEFINITION OF THE GEOMETRY LIBRARY: /// /// This library is a primitive geometry library /// which enables 2D to 3D (or vice versa) switch. /// Contains the fundamental variables only: /// Coord Systems (CS), a unique global CS, points, vectors, axes, lines, circles and planes. /// Points and vectors are ReferenceObject types which are defined wrt a CS. /// ReferenceObject instances can be 2D or 3D whereas the other types (e.g. an axis or plane) /// are default 3D objects. /// Complex geometries (e.g. a surface) are not implemented. /// /// /// /// GeometryObject is the implementation base class for all types in the library. /// It holds an ID (an internal ID) and name (for the use of the end users) members. /// /// CAUTION FOR STATIC ID COUNTER: /// GeometryObject stores a static member to hold the last used ID for any object. /// An important issue to note that the non-static ID of an object is coppied /// with the default copy and move operations. /// Hence, default copying of an object results with two objects having the same ID. /// This is solved easily by user defined copy ctor and assignment functions. /// The problem here is the temporary objects. /// In the geometrical operations many temporary objects are created. /// For example, creating a circle from three points generates lines and axes which are temporary. /// The static ID counter is incremented firstly for the temporary objects and then for the circle object. /// The temporaries are deleted when the circle ctor reaches the end /// and the static ID counter is decremented for them. /// Suppose at the beginning of the circle ctor, the static ID counter is 100 /// and suppose in the ctor we created 3 temporary objects. /// Hence, the ID for the new circle object will be 104 /// but the static ID counter will be 101. /// THE SOLUTION TO THIS PROBLEM IS BEING STUDIED CURRENTLY. /// /// Additionally, the library contains two static tolerance values to be used in the calculations: /// GeometryParameters::TOLERANCE_GENERAL and GeometryParameters::TOLERANCE_SENSITIVE /// The use of the tolerance consists of two cases: /// a. To eliminate any kind of computational errors (e.g. truncation errors), /// b. To be able to perform approximate calculations. /// For example, intersection of two line may not exist theoritically /// but an approximate point can be found. /// A tolerance value is required for such approximations. /// /// /// /// ReferenceObject is the base class for CS dependent objects (i.e. points and vectors). /// It owns a CS member. /// The geometry basically defined wrt to coordinate systems (CSs) in order to /// a. simplify the tracebility of the objects /// b. switch between spaces, especially 3D to 2D (or 2D to 3D) /// The 1st functionality is a fundamental issue in engineering applications. /// For example, an assembly of bodies is defined in a global CS /// while each body has its own CS. /// The 2nd functionality is similar to the 1st one. /// Its benefit is more clear when it comes to switching between 2D and 3D spaces. /// All CAE software (e.g. Catia) supports switching to 2D space. /// This library can be utilized in this respect. /// /// The z dimension (i.e. coord for a point and component for a vector) is zero for 2D objects by default. /// However, the object does not have to be defined wrt the global CS. /// If a CS other than the global CS is defined as the reference CS of a 2D object, /// the object has x and y dimensions but no z-dimension wrt that CS. /// /// Reference CS to global CS (or vice versa) transformations are supported. /// /// Global CS is a singleton class. /// See GlobalCoordSystem.hxx for the details /// /// /// /// Axis, Line, Circle and Plane classes inherit from the base class (GeometryObject) /// and do not have 2D and 3D types (e.g. Axis2D). /// Actually, only the classes inheritting from ReferenceObject have 2D and 3D types. /// The problem is not 2D/3D types but the reference CS. /// An Axis cannot have a reference CS /// because it has two members (point and vector) /// and the reference CSs of the two may not be the same. /// This can be satisfied as a precondition in the ctors of Axis /// but the reference CSs of the point and vector members can be modified /// after the Axis object instantiation. /// Hence, setReferenceCoordSystem method of ReferenceObject shall be removed /// in order for Axis to have a reference CS /// But this solution is not preferable. /// Hence, the types with more than one ReferenceObject members (Axis, Line, Circle and Plane) /// do not have a reference CS and 2D/3D types /// and inherit from the root class (GeometryObject). /// Instead, they have three member functions: /// is2D, is3D and getCommonReferenceCoordSystem. /// /// /// /// /// /// /// /// /// author: [email protected] ///
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent