# Utils

**Repository Path**: liyunxin_codinghub/Utils

## Basic Information

- **Project Name**: Utils
- **Description**: 自己用的一些工具函数
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2020-03-27
- **Last Updated**: 2021-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Utils

自己用的一些工具函数。
1. 编译安装：

    首先将CMakeLists.txt中BUILD_TEST选项设置为OFF（即不编译测试程序），然后执行以下命令：

    ```cmd
    git clone https://gitee.com/liyunxin_codinghub/Utils.git
    cd Utils
    mkdir build && cd build
    cmake ..
    make -j4
    sudo make install
    ```

2. 使用：

    在使用Utils包的项目中的CMakeLists.txt中添加如下查找库语句：

    ```cmake
    #CMakeLists.txt
    find_package(Utils REQUIRED)
    include_directories(${Utils_INCLUDE_DIRS})
    link_libraries(${Utils_LIBRARIES})
    ```

3. 源文件中为方便使用可重定义名字空间为更简短的名字：

    ```c++
    //in cpp file:
    #include <Utils.h>
    using namespace lyxutils::abbreviations;		//use convenient abbreviations for length namespaces
    ```
    
    使用名字空间`lyxutils::abbreviations`后就可以在源文件中使用一些简称，比如：
    
    - `dbg`=`lyxutils::debug`
    - `str`=`lyxutils::str_utils`
    - `xio`=`lyxutils::io`
    - `xos`=`lyxutils::os`
    - `Vec3u`,`Vec3i`,`Vec3f`,`Vec3d`=`lyxutils::geometry::Vector3<unsigned char>`,`lyxutils::geometry::Vector3<int>`,`lyxutils::geometry::Vector3<float>`与`lyxutils::geometry::Vector3<double>`等
# 函数一览
1. lyxutils::debug——一些调试时用的函数
    - `getTimeString`——获取当前时间字符串，格式`yyyy-mm-dd HH:MM:SS`
    - `timeIt`——对函数计时，函数是无参无返回值的函数，如果需要参数与返回值可以用`lambda`表达式适配一下
    
2. lyxutils::str_utils——字符串相关处理
    - `split`——以给定字符串中任一个字符分割字符串
    - `split_with_string`——以给定字符串分割字符串
    - `split_with_string_re`——以给定的字符串分割字符串并保留空串（如`split_with_string("google","o")`会返回`["g","","gle"]`；而`split_with_string("google","o")`会返回`["g","gle"]`
    - `lower`——转换为全小写
    - `upper`——转换为全大写
    - `replace`——字符串中子串替换
    - `type2str`——任意类型到字符串转换（基于`stringstream`）
    - `str2type`——字符串到任意类型转换（基于`stringstream`)
    - `join`——用指定字符串连接可迭代对象的每一个元素形成新的字符串
    - `count`——判断子串在字符串中出现次数
    - `multiply`——字符串重复指定次数
    - `center`——居中字符串，保持指定宽度，两边多余位置填充指定字符
    - `left`——左对齐字符串
    - `right`——右对齐字符串
    - `word_wrap`——自动文本换行
    - `frame`——将字符串用方框框起来的，比如license信息之类的
    - `strip`——剥去字符串两端的指定字符（默认是去除两端空格）
    - `find`——在字符串中查找子串，未找到返回-1
    
3. lyxutils::io——一些输入输出操作（标准输入输出与文件输入输出）

    - `consoleProgressBar`——向控制台打印进度信息（不换行单行打印）
    - `printVector`——向控制台打印一维数组
    - `print2DVector`——向控制台打印二维数组
    - `openLogFile`——打开一个文件输出流作为日志文件
    - `writeLog`——向日志文件（文件输出流）写日志，会自动加上时间
    - `read_csv`——读取`csv`文件
    - `read_pts`——读取点云文件
    - `read_pts_field`——读取带有标量场的点云文件
    - `read_ptsrgb`——读取`rgb`点云文件
    - `read_ptsrgb_field`——读取带有标量场的`rgb`点云文件
    - `write_csv`——写`csv`文件
    - `points_to_csv`——写二维点云文件
    - `points3D_to_csv`——写三维点云文件
    - `points3DRGB_to_csv`——写三维`rgb`点云文件

    =>`class CLParser`——用来解析命令行的类（比如从`argc`与`argv`参数中解析有哪些选项，选项对应的参数值以及命令操作的对象等）

    `CLParser`用法——

    1. 无模板解析
       - 构建对象——`lyxutils::io::CLParser parser;`
       - 解析命令——`parser.parse(command);`——可以解析一个字符串命令，或者解析主函数参数`argc`与`argv`，或者从文件中解析（相当于文件作为一个配置文件）
       - 获取命令选项
         - `parser.hasOption(optName)`——判断命令行中是否有`optName`选项
         - `parser.getOption(optName)`——获取`optName`选项对应的参数值，如果不存在则得到空字符串
       - 无模板解析不会抛出异常
    2. 有模板解析——基本与无模板用法一样，构建->解析->获取选项
       - 但是可以通过`parser.setOptionPattern(numOpts,optPattern)`来设置解析模板（在`parser.parse`之前），如有多少个长选项，每个长选项是否有对应的短选项以及对应的短选项是什么，每个选项是否必需给定参数还是参数可选或者没有参数；
       - `optPattern`是个`CLOption`结构体组成的数组，每一个元素指定一个选项的解析模板
       - **异常抛出**：如果解析到模板中没有的选项则会抛出`未识别选项`的invalid_argument异常；如果模板中选项要求必需参数但是没有解析到参数则会抛出`缺失参数`的invalid_argument异常；如果是从文件中解析还可能抛出`文件不存在`、`打开文件出错`的runtime_error异常

4. lyxutils::algorithm——有关算法——已弃用

5. lyxutils::colors——有关颜色处理

    - `rgb2hsv`——将`rgb`颜色值转换为`hsv`颜色值
    - `hsv2rgb`——将`hsv`颜色值转换为`rgb`颜色值
    - `rand_color`——生成随机颜色（与给定的颜色形成对比色的随机颜色，默认的给定颜色是黑色；第二个参数可以指定随机颜色的随机变化范围）
    - 颜色常量`red`,`green`,`blue`,`white`,`black`,`gray`,`magenta`,`cyan`,`yellow`,`orange`,`purple`等

6. lyxutils::numpy——一些仿`numpy`的数组处理函数——使用循环实现，未向量化，并不能以此提高效率，仅用于简化代码

    - `broadcast`——仿照python中的广播法则
    - `transpose`——转置
    - `range`——生成范围向量
    - `linspace`——生成区间线性插值向量
    - `reshape`——将一维向量折叠成二维的
    - `flat`——将二维数组展开成一维的
    - `print`——打印一维/二维数组
    - `sum`，`mean`，`std`，`add`，`minus`，`dot`，`multiply`——数组求和、求均值、求标准差、按位加、减、乘以及向量内积或矩阵乘法
    - `apply`——对数组每一个元素执行某个操作
    - `where`——找到数组中符合某一条件的所有元素的索引
    - `apply_where`——对数组符合某一条件的元素执行指定操作
    - `cov`——计算高维点的协方差矩阵

7. lyxutils::os——常用到的系统相关操作，仿python的`os`库与系统命令

    - `exist`——判断文件是否存在
    - `file`——判断文件是否存在且为一般文件
    - `directory`——判断文件是否存在且为目录
    - `pwd`——获取当前目录字符串
    - `parent`——获取指定文件的父目录
    - `ls`，`lsdir`，`lsfile`——列出指定目录下所有的子项/子目录/子文件
    - `relpath`——计算一个目录相对于指定文件的相对路径（默认是相对于当前工作路径）
    - `abspath`——计算一个文件的相对路径名称的绝对路径（包括路径、后缀的完整名称）
    - `fullname`——计算给定文件的全名（除去路径；包括后缀）
    - `basename`——计算给定文件的基础名称（不包括后缀与路径，后缀为最后一个`.`之后的部分，可能没有后缀）
    - `suffix`——计算给定文件的后缀名
    - `cd`——更改当前工作目录
- `mkdir`——创建目录
  
    更多系统操作可通过`system("command")`来执行系统命令完成
    
8. lyxutils::Vector3\<T\>——方便的三维向量类，可用于保存诸如点坐标之类的三维向量并进行常用操作

    ==>已经移入geometry名字空间，即现为lyxutils::geometry::Vector3\<T\>，但是为了与旧代码兼容以及方便，也可以使用lyxutils::Vector3\<T\>
    
    - 支持四则运算符（可以与标量/向量进行加减乘除）——与标量加减乘除即每一个元素与标量加减乘除；与向量加减乘除即向量和、差、按位积以及按位商；与标量以及向量的四则运算会自动确定合适的返回类型（如`Vector3<int>`与`Vector3<double>`相加返回的是`Vector3<double>`），只需要使用auto接收返回值即可，如`auto v=v1+v2;`
    - 实现了`+=`,`-=`,`*=`,`/=`等拓展赋值运算符，但是需要注意类型，因为`a+=b`相当于`a=a+b`，不会改变a的元素类型，如果a的元素是int，b是float，相加之后赋值给a会丢失精度
    - 可以通过`v.x`，`v.y`，`v.z`的形式访问三个坐标值，也可以通过索引的方式`v[0]`,`v[1]`,`v[2]`访问
    - 支持initializer_list初始化：`Vector3<float> v{1,2,3};`支持std::vector向Vector3的转换（像initializer_list一样只取前三个）
    - `dot`——求与另一个三维向量的内积
    - `cross`——求与另一个三维向量的外积/叉乘
    - `mold`——求模（可以给定rank，求给定阶范数，默认是L2范数，也就是向量模）
    - `fromStringVector`——从`vector<string>`到`Vector3<T>`的转换，字符串会自动解析成T类型的值（字符串向T类型解析的时候使用的是stringstream来转换，可能存在转换失败，如`hello`转换成float就会失败）
    - `toStdVector`——转化为std::vector
    - `asType<T>`——转化为元素类型为T的新的Vector3