Splits the ErrorBadPathName exception into three separate exceptions (empty, malformed, & extension not registered)

asmaloney · asmaloney · commit b86484d5cfe0 · 2025-12-14T13:55:04.000-05:00
This level of detail would have helped make what happened in #330 obvious. Deprecates ErrorBadPathName in favour of ErrorPathNameEmpty, ErrorPathNameMalformed, and ErrorPathNameExtensionNotRegistered. Note that ErrorPathUndefined is another case that can happen (valid path, not defined).
diff --git a/include/E57Exception.h b/include/E57Exception.h
@@ -114,7 +114,10 @@ namespace e57
       /// conversion required to assign element value, but not requested
       ErrorConversionRequired = 36,
 
-      ErrorBadPathName = 37,            ///< E57 path name is not well formed
+      /// @deprecated Will be removed in 4.0. Use e57::ErrorPathNameEmpty,
+      /// e57::ErrorPathNameMalformed, or e57::ErrorPathNameExtensionNotRegistered.
+      ErrorBadPathName = 37, ///< E57 path name is not well formed
+
       ErrorNotImplemented = 38,         ///< functionality not implemented
       ErrorBadNodeDowncast = 39,        ///< bad downcast from Node to specific node type
       ErrorWriterNotOpen = 40,          ///< CompressedVectorWriter is no longer open
@@ -142,6 +145,11 @@ namespace e57
       /// when "recordCount" is 0. "fileOffset" must be greater than 0 (Table 9 in the standard).
       ErrorData3DReadInvalidZeroRecords = 53,
 
+      // These refine ErrorBadPathName
+      ErrorPathNameEmpty,                  ///< E57 path name is empty
+      ErrorPathNameMalformed,              ///< E57 path name is not well formed
+      ErrorPathNameExtensionNotRegistered, ///< E57 path name uses an unregistered extension
+
       /// @deprecated Will be removed in 4.0. Use e57::Success.
       E57_SUCCESS E57_DEPRECATED_ENUM( "Will be removed in 4.0. Use Success." ) = Success,
       /// @deprecated Will be removed in 4.0. Use e57::ErrorBadCVHeader.
@@ -257,7 +265,8 @@ namespace e57
          "Will be removed in 4.0. Use ErrorConversionRequired." ) = ErrorConversionRequired,
       /// @deprecated Will be removed in 4.0. Use e57::ErrorBadPathName.
       E57_ERROR_BAD_PATH_NAME E57_DEPRECATED_ENUM(
-         "Will be removed in 4.0. Use ErrorBadPathName." ) = ErrorBadPathName,
+         "Will be removed in 4.0. Use ErrorPathNameEmpty, ErrorPathNameMalformed, or "
+         "ErrorPathNameExtensionNotRegistered." ) = ErrorBadPathName,
       /// @deprecated Will be removed in 4.0. Use e57::ErrorNotImplemented.
       E57_ERROR_NOT_IMPLEMENTED E57_DEPRECATED_ENUM(
          "Will be removed in 4.0. Use ErrorNotImplemented." ) = ErrorNotImplemented,
diff --git a/src/E57Exception.cpp b/src/E57Exception.cpp
@@ -362,6 +362,14 @@ namespace e57
             return "trying to read an invalid Data3D with zero records - check for zero records "
                    "before trying to read this Data3D section (ErrorInvalidZeroRecordsData3D)";
 
+         case ErrorPathNameEmpty:
+            return "E57 path name is empty (ErrorPathNameEmpty)";
+         case ErrorPathNameMalformed:
+            return "E57 path name is not well formed (ErrorPathNameMalformed)";
+         case ErrorPathNameExtensionNotRegistered:
+            return "E57 path name uses an unregistered extension "
+                   "(ErrorPathNameExtensionNotRegistered)";
+
          default:
             return "unknown error (" + std::to_string( ecode ) + ")";
       }
diff --git a/src/ImageFile.cpp b/src/ImageFile.cpp
@@ -704,7 +704,8 @@ prefixed form, the prefix does not have to be declared in the ImageFile.
 
 @post No visible state is modified.
 
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
 @throw ::ErrorInternal All objects in undocumented state
 
 @see ImageFile::isElementNameExtended
diff --git a/src/ImageFileImpl.cpp b/src/ImageFileImpl.cpp
@@ -564,7 +564,7 @@ namespace e57
 
       if ( prefix.length() > 0 && !extensionsLookupPrefix( prefix, uri ) )
       {
-         throw E57_EXCEPTION2( ErrorBadPathName,
+         throw E57_EXCEPTION2( ErrorPathNameExtensionNotRegistered,
                                "elementName=" + elementName + " prefix=" + prefix );
       }
    }
@@ -620,10 +620,10 @@ namespace e57
 
          if ( !isElementNameLegal( elementName ) )
          {
-            throw E57_EXCEPTION2( ErrorBadPathName, std::string( "pathName=" )
-                                                       .append( pathName )
-                                                       .append( " elementName=" )
-                                                       .append( elementName ) );
+            throw E57_EXCEPTION2( ErrorPathNameMalformed, std::string( "pathName=" )
+                                                             .append( pathName )
+                                                             .append( " elementName=" )
+                                                             .append( elementName ) );
          }
 
          // Add to list
@@ -648,7 +648,7 @@ namespace e57
       // Empty relative path is not allowed
       if ( isRelative && fields.empty() )
       {
-         throw E57_EXCEPTION2( ErrorBadPathName, "pathName=" + pathName );
+         throw E57_EXCEPTION1( ErrorPathNameEmpty );
       }
 
 #ifdef E57_VERBOSE
@@ -712,7 +712,7 @@ namespace e57
       // Empty name is bad
       if ( len == 0 )
       {
-         throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );
+         throw E57_EXCEPTION1( ErrorPathNameEmpty );
       }
 
       unsigned char c = elementName[0];
@@ -727,7 +727,7 @@ namespace e57
 
             if ( c < '0' || c > '9' )
             {
-               throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );
+               throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );
             }
          }
 
@@ -739,7 +739,7 @@ namespace e57
       // Don't allow ':' as first char.
       if ( c < 128 && !( ( 'a' <= c && c <= 'z' ) || ( 'A' <= c && c <= 'Z' ) || c == '_' ) )
       {
-         throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );
+         throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );
       }
 
       // If each following char is ASCII (<128), check for legality
@@ -751,7 +751,7 @@ namespace e57
          if ( c < 128 && !( ( 'a' <= c && c <= 'z' ) || ( 'A' <= c && c <= 'Z' ) || c == '_' ||
                             c == ':' || ( '0' <= c && c <= '9' ) || c == '-' || c == '.' ) )
          {
-            throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );
+            throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );
          }
       }
 
@@ -763,7 +763,7 @@ namespace e57
          // Check doesn't have two colons
          if ( elementName.find_first_of( ':', found + 1 ) != std::string::npos )
          {
-            throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );
+            throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );
          }
 
          // Split element name at the colon
@@ -773,8 +773,9 @@ namespace e57
 
          if ( prefix.length() == 0 || localPart.length() == 0 )
          {
-            throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName + " prefix=" +
-                                                       prefix + " localPart=" + localPart );
+            throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName +
+                                                             " prefix=" + prefix +
+                                                             " localPart=" + localPart );
          }
       }
       else
diff --git a/src/NodeImpl.cpp b/src/NodeImpl.cpp
@@ -273,9 +273,9 @@ void NodeImpl::set( const ustring &pathName, NodeImplSharedPtr ni, bool autoPath
 void NodeImpl::set( const StringList & /*fields*/, unsigned /*level*/, NodeImplSharedPtr /*ni*/,
                     bool /*autoPathCreate*/ )
 {
-   // If get here, then tried to call set(fields...) on NodeImpl that wasn't a  StructureNodeImpl,
+   // If get here, then tried to call set(fields...) on NodeImpl that wasn't a StructureNodeImpl,
    // so that's an error
-   throw E57_EXCEPTION1( ErrorBadPathName ); //???
+   throw E57_EXCEPTION2( ErrorInternal, "Trying to set a path name on a non-structured node" );
 }
 
 void NodeImpl::checkBuffers( const std::vector<SourceDestBuffer> &sdbufs,
@@ -407,7 +407,7 @@ bool NodeImpl::_verifyPathNameAbsolute( const ustring &inPathName )
    // If not an absolute path name, have error
    if ( isRelative )
    {
-      throw E57_EXCEPTION2( ErrorBadPathName,
+      throw E57_EXCEPTION2( ErrorPathNameMalformed,
                             "this->pathName=" + this->pathName() + " pathName=" + inPathName );
    }
 
diff --git a/src/SourceDestBuffer.cpp b/src/SourceDestBuffer.cpp
@@ -149,8 +149,8 @@ transfer with a CompressedVectorNode.
 @pre The @a destImageFile must be open (i.e. destImageFile.isOpen() must be true).
 @pre The stride must be >= sizeof(*b)
 
-@throw ::ErrorBadAPIArgument (n/c)
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
 @throw ::ErrorBadBuffer (n/c)
 @throw ::ErrorImageFileNotOpen (n/c)
 @throw ::ErrorInternal All objects in undocumented state
@@ -287,8 +287,8 @@ destroyed).
 @pre b.size() must be > 0.
 @pre The @a destImageFile must be open (i.e. destImageFile.isOpen() must be true).
 
-@throw ::ErrorBadAPIArgument (n/c)
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
 @throw ::ErrorBadBuffer (n/c)
 @throw ::ErrorImageFileNotOpen (n/c)
 @throw ::ErrorInternal All objects in undocumented state
diff --git a/src/StructureNode.cpp b/src/StructureNode.cpp
@@ -225,7 +225,9 @@ is not attached to an ImageFile, the @a pathName origin root will not the root n
 
 @return true if pathName is currently defined.
 
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
+@throw ::ErrorPathNameExtensionNotRegistered (n/c)
 @throw ::ErrorImageFileNotOpen (n/c)
 @throw ::ErrorInternal All objects in undocumented state
 
@@ -278,7 +280,9 @@ an ImageFile.
 
 @return A smart Node handle referencing the child node.
 
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
+@throw ::ErrorPathNameExtensionNotRegistered (n/c)
 @throw ::ErrorPathUndefined (n/c)
 @throw ::ErrorImageFileNotOpen (n/c)
 @throw ::ErrorInternal All objects in undocumented state
@@ -322,7 +326,9 @@ destImageFile() == n.destImageFile()).
 @post The @a pathName will be defined (i.e. isDefined(pathName)).
 
 @throw ::ErrorImageFileNotOpen (n/c)
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
+@throw ::ErrorPathNameExtensionNotRegistered (n/c)
 @throw ::ErrorPathUndefined (n/c)
 @throw ::ErrorSetTwice (n/c)
 @throw ::ErrorAlreadyHasParent (n/c)
diff --git a/src/VectorNode.cpp b/src/VectorNode.cpp
@@ -268,7 +268,9 @@ The element names of child elements of VectorNodes are numbers, encoded as strin
 
 @return true if pathName is currently defined.
 
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
+@throw ::ErrorPathNameExtensionNotRegistered (n/c)
 @throw ::ErrorImageFileNotOpen (n/c)
 @throw ::ErrorInternal All objects in undocumented state
 
@@ -319,7 +321,9 @@ The element names of child elements of VectorNodes are numbers, encoded as strin
 
 @return A smart Node handle referencing the child node.
 
-@throw ::ErrorBadPathName (n/c)
+@throw ::ErrorPathNameEmpty (n/c)
+@throw ::ErrorPathNameMalformed (n/c)
+@throw ::ErrorPathNameExtensionNotRegistered (n/c)
 @throw ::ErrorPathUndefined (n/c)
 @throw ::ErrorImageFileNotOpen (n/c)
 @throw ::ErrorInternal All objects in undocumented state

Original file line number	Diff line number	Diff line change
`@@ -564,7 +564,7 @@ namespace e57`
`564`	`564`
`565`	`565`	`if ( prefix.length() > 0 && !extensionsLookupPrefix( prefix, uri ) )`
`566`	`566`	`{`
`567`		`- throw E57_EXCEPTION2( ErrorBadPathName,`
	`567`	`+ throw E57_EXCEPTION2( ErrorPathNameExtensionNotRegistered,`
`568`	`568`	`"elementName=" + elementName + " prefix=" + prefix );`
`569`	`569`	`}`
`570`	`570`	`}`
`@@ -620,10 +620,10 @@ namespace e57`
`620`	`620`
`621`	`621`	`if ( !isElementNameLegal( elementName ) )`
`622`	`622`	`{`
`623`		`- throw E57_EXCEPTION2( ErrorBadPathName, std::string( "pathName=" )`
`624`		`- .append( pathName )`
`625`		`- .append( " elementName=" )`
`626`		`- .append( elementName ) );`
	`623`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed, std::string( "pathName=" )`
	`624`	`+ .append( pathName )`
	`625`	`+ .append( " elementName=" )`
	`626`	`+ .append( elementName ) );`
`627`	`627`	`}`
`628`	`628`
`629`	`629`	`// Add to list`
`@@ -648,7 +648,7 @@ namespace e57`
`648`	`648`	`// Empty relative path is not allowed`
`649`	`649`	`if ( isRelative && fields.empty() )`
`650`	`650`	`{`
`651`		`- throw E57_EXCEPTION2( ErrorBadPathName, "pathName=" + pathName );`
	`651`	`+ throw E57_EXCEPTION1( ErrorPathNameEmpty );`
`652`	`652`	`}`
`653`	`653`
`654`	`654`	`#ifdef E57_VERBOSE`
`@@ -712,7 +712,7 @@ namespace e57`
`712`	`712`	`// Empty name is bad`
`713`	`713`	`if ( len == 0 )`
`714`	`714`	`{`
`715`		`- throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );`
	`715`	`+ throw E57_EXCEPTION1( ErrorPathNameEmpty );`
`716`	`716`	`}`
`717`	`717`
`718`	`718`	`unsigned char c = elementName[0];`
`@@ -727,7 +727,7 @@ namespace e57`
`727`	`727`
`728`	`728`	`if ( c < '0' \|\| c > '9' )`
`729`	`729`	`{`
`730`		`- throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );`
	`730`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );`
`731`	`731`	`}`
`732`	`732`	`}`
`733`	`733`
`@@ -739,7 +739,7 @@ namespace e57`
`739`	`739`	`// Don't allow ':' as first char.`
`740`	`740`	`if ( c < 128 && !( ( 'a' <= c && c <= 'z' ) \|\| ( 'A' <= c && c <= 'Z' ) \|\| c == '_' ) )`
`741`	`741`	`{`
`742`		`- throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );`
	`742`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );`
`743`	`743`	`}`
`744`	`744`
`745`	`745`	`// If each following char is ASCII (<128), check for legality`
`@@ -751,7 +751,7 @@ namespace e57`
`751`	`751`	`if ( c < 128 && !( ( 'a' <= c && c <= 'z' ) \|\| ( 'A' <= c && c <= 'Z' ) \|\| c == '_' \|\|`
`752`	`752`	`c == ':' \|\| ( '0' <= c && c <= '9' ) \|\| c == '-' \|\| c == '.' ) )`
`753`	`753`	`{`
`754`		`- throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );`
	`754`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );`
`755`	`755`	`}`
`756`	`756`	`}`
`757`	`757`
`@@ -763,7 +763,7 @@ namespace e57`
`763`	`763`	`// Check doesn't have two colons`
`764`	`764`	`if ( elementName.find_first_of( ':', found + 1 ) != std::string::npos )`
`765`	`765`	`{`
`766`		`- throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName );`
	`766`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName );`
`767`	`767`	`}`
`768`	`768`
`769`	`769`	`// Split element name at the colon`
`@@ -773,8 +773,9 @@ namespace e57`
`773`	`773`
`774`	`774`	`if ( prefix.length() == 0 \|\| localPart.length() == 0 )`
`775`	`775`	`{`
`776`		`- throw E57_EXCEPTION2( ErrorBadPathName, "elementName=" + elementName + " prefix=" +`
`777`		`- prefix + " localPart=" + localPart );`
	`776`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed, "elementName=" + elementName +`
	`777`	`+ " prefix=" + prefix +`
	`778`	`+ " localPart=" + localPart );`
`778`	`779`	`}`
`779`	`780`	`}`
`780`	`781`	`else`
Original file line number	Diff line number	Diff line change
`@@ -273,9 +273,9 @@ void NodeImpl::set( const ustring &pathName, NodeImplSharedPtr ni, bool autoPath`
`273`	`273`	`void NodeImpl::set( const StringList & /fields/, unsigned /level/, NodeImplSharedPtr /ni/,`
`274`	`274`	`bool /autoPathCreate/ )`
`275`	`275`	`{`
`276`		`- // If get here, then tried to call set(fields...) on NodeImpl that wasn't a StructureNodeImpl,`
	`276`	`+ // If get here, then tried to call set(fields...) on NodeImpl that wasn't a StructureNodeImpl,`
`277`	`277`	`// so that's an error`
`278`		`- throw E57_EXCEPTION1( ErrorBadPathName ); //???`
	`278`	`+ throw E57_EXCEPTION2( ErrorInternal, "Trying to set a path name on a non-structured node" );`
`279`	`279`	`}`
`280`	`280`
`281`	`281`	`void NodeImpl::checkBuffers( const std::vector<SourceDestBuffer> &sdbufs,`
`@@ -407,7 +407,7 @@ bool NodeImpl::_verifyPathNameAbsolute( const ustring &inPathName )`
`407`	`407`	`// If not an absolute path name, have error`
`408`	`408`	`if ( isRelative )`
`409`	`409`	`{`
`410`		`- throw E57_EXCEPTION2( ErrorBadPathName,`
	`410`	`+ throw E57_EXCEPTION2( ErrorPathNameMalformed,`
`411`	`411`	`"this->pathName=" + this->pathName() + " pathName=" + inPathName );`
`412`	`412`	`}`
`413`	`413`