/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#ifndef __NW_PATH_UTILS_H__
#define __NW_PATH_UTILS_H__

#include "NwExport.h"
#include "OdString.h"

namespace NwPathUtils
{
  /** \details
    Split the path into a pair, (head, tail) where tail is the last pathname component and
    head is everything leading up to that.

    \param filePath [in]  const ref OdString path
    \param head [out]  Splitted string head
    \param tail [out]  Splitted string tail

    \remarks
    The tail section will not include a slash.
    If the path ends with a slash, the tail will be empty.
    When the path has no slashes at all, the head will be empty.
    If the path itself is empty, both the head and tail will also be empty.
    Any slashes at the end of the head are removed.
    This function is analog of os.path.splitdrive in python3.
  */
   NWDBEXPORT void splitPath(const OdString& filePath, OdString& head, OdString& tail);
  
   /** \details
     Split the pathname path into a pair(drive, tail) where drive is either a mount point or the empty string.
     \param filePath [in]  const ref OdString path
     \param head [out]  Splitted string head
     \param tile [out]  Splitted string tail

     \remarks
     On systems which do not use drive specifications, drive will always be the empty string.
     In all cases, drive + tail will be the same as path.
     This function is analog of os.path.splitdrive in python3
   */
   NWDBEXPORT void splitDrive(const OdString& filePath, OdString& head, OdString& tail);
  
  /** \details
    Split the pathname path into a pair (head, tail)
    \param path [in]  const ref OdString path
    \param head [out]  Splitted string head
    \param tail [out]  Splitted string tail

    Split the pathname path into a pair (head, tail) such that head + tail == path,
    and the extension, ext, is empty or begins with a period and contains at most one period.
    This function is analog of os.path.splitdrive in python3
  */
  NWDBEXPORT void splitExt(const OdString& path, OdString& head, OdString& tail);
  
  /** \details
    Return the directory name of pathname path.
    \param path [in]  const ref OdString path
    \returns directory name of pathname path.
    This is the first element of the pair returned by passing path to the function splitPath().
  */  
  NWDBEXPORT OdString dirname(const OdString& path);
  
  /** \details
    Return the base name of pathname path.
    \param path [in]  full path.
    \returns base name of pathname path.
    \remarks
    This is the second element of the pair returned by passing path to the function splitPath().
    This function is analog of os.path.basename in python3 for windows
  */
  NWDBEXPORT OdString basename(const OdString& path);
  
  /** \details
    Join two path segments.
    \param path1 [in]  path segment first
    \param path2 [in]  path segment second
    \param path2 [in]  concatenation separator
 
    \remarks
    The return value is the concatenation of both path segment with path separator
    If path separator is not specified then will selected system depended.
  */
  NWDBEXPORT OdString join(const OdString& path1, const OdString& path2, const OdString& separ = "");
};

#endif