add doc

looly · Aug 22, 2020 · 3423393 · 3423393
1 parent 20c636e
commit 3423393
Show file tree

Hide file tree

Showing 7 changed files with 285 additions and 11 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -22,6 +22,7 @@
       * [文件写入-FileWriter](core/IO/文件/文件写入-FileWriter.md)
       * [文件追加-FileAppender](core/IO/文件/文件追加-FileAppender.md)
       * [文件跟随-Tailer](core/IO/文件/文件跟随-Tailer.md)
+      * [文件名工具-FileNameUtil](core/IO/文件/文件名工具-FileNameUtil.md)
     * 资源
       * [概述](core/IO/资源/概述.md)
       * [资源工具-ResourceUtil.md](core/IO/资源/资源工具-ResourceUtil.md)
@@ -186,6 +187,10 @@
     * [中文分词封装-TokenizerUtil](extra/中文分词/中文分词封装-TokenizerUtil.md)
   * Spring
     * [Spring工具-SpringUtil](extra/Spring/Spring工具-SpringUtil.md)
+  * Cglib
+    * [Cglib工具-CglibUtil](extra/cglib/Cglib工具-CglibUtil.md)
+  * 拼音
+    * [拼音工具-PinyinUtil](extra/拼音/拼音工具-PinyinUtil.md)
 
 * 布隆过滤（Hutool-bloomFilter）
   * [概述](bloomFilter/概述.md)

diff --git a/docs/core/IO/文件/文件名工具-FileNameUtil.md b/docs/core/IO/文件/文件名工具-FileNameUtil.md
@@ -0,0 +1,31 @@
+## 由来
+
+文件名操作工具类，主要针对文件名获取主文件名、扩展名等操作，同时针对Windows平台，清理无效字符。
+
+此工具类在`5.4.1`之前是`FileUtil`的一部分，后单独剥离为`FileNameUtil`工具。
+
+## 使用
+
+1. 获取文件名
+
+```java
+File file = FileUtil.file("/opt/test.txt");
+
+// test.txt
+String name = FileNameUtil.getName(file);
+```
+
+2. 获取主文件名和扩展名
+
+```java
+File file = FileUtil.file("/opt/test.txt");
+
+// "test"
+String name = FileNameUtil.mainName(file);
+
+// "txt"
+String name = FileNameUtil.extName(file);
+```
+
+> 注意，此处获取的扩展名不带`.`。
+> `FileNameUtil.mainName`和`FileNameUtil.getPrefix`等价，同理`FileNameUtil.extName`和`FileNameUtil.getSuffix`等价，保留两个方法用于适应不同用户的习惯。
diff --git a/docs/core/日期时间/LocalDateTime工具-LocalDateTimeUtil.md b/docs/core/日期时间/LocalDateTime工具-LocalDateTimeUtil.md
@@ -0,0 +1,88 @@
+## 介绍
+
+从Hutool的5.4.x开始，Hutool加入了针对JDK8+日期API的封装，此工具类的功能包括`LocalDateTime`和`LocalDate`的解析、格式化、转换等操作。
+
+## 使用
+
+1. 日期转换
+
+```java
+String dateStr = "2020-01-23T12:23:56";
+DateTime dt = DateUtil.parse(dateStr);
+
+// Date对象转换为LocalDateTime
+LocalDateTime of = LocalDateTimeUtil.of(dt);
+
+// 时间戳转换为LocalDateTime
+of = LocalDateTimeUtil.ofUTC(dt.getTime());
+```
+
+2. 日期字符串解析
+
+```java
+// 解析ISO时间
+LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");
+
+
+// 解析自定义格式时间
+localDateTime = LocalDateTimeUtil.parse("2020-01-23", DatePattern.NORM_DATE_PATTERN);
+```
+
+解析同样支持`LocalDate`：
+
+```java
+LocalDate localDate = LocalDateTimeUtil.parseDate("2020-01-23");
+
+// 解析日期时间为LocalDate，时间部分舍弃
+localDate = LocalDateTimeUtil.parseDate("2020-01-23T12:23:56", DateTimeFormatter.ISO_DATE_TIME);
+```
+
+3. 日期格式化
+
+```java
+LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");
+
+// "2020-01-23 12:23:56"
+String format = LocalDateTimeUtil.format(localDateTime, DatePattern.NORM_DATETIME_PATTERN);
+```
+
+4. 日期偏移
+
+```java
+final LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");
+
+// 增加一天
+// "2020-01-24T12:23:56"
+LocalDateTime offset = LocalDateTimeUtil.offset(localDateTime, 1, ChronoUnit.DAYS);
+```
+
+如果是减少时间，offset第二个参数传负数即可：
+
+```java
+// "2020-01-22T12:23:56"
+offset = LocalDateTimeUtil.offset(localDateTime, -1, ChronoUnit.DAYS);
+```
+
+5. 计算时间间隔
+
+```java
+LocalDateTime start = LocalDateTimeUtil.parse("2019-02-02T00:00:00");
+LocalDateTime end = LocalDateTimeUtil.parse("2020-02-02T00:00:00");
+
+Duration between = LocalDateTimeUtil.between(start, end);
+
+// 365
+between.toDays();
+```
+
+6. 一天的开始和结束
+
+```java
+LocalDateTime localDateTime = LocalDateTimeUtil.parse("2020-01-23T12:23:56");
+
+// "2020-01-23T00:00"
+LocalDateTime beginOfDay = LocalDateTimeUtil.beginOfDay(localDateTime);
+
+// "2020-01-23T23:59:59.999999999"
+LocalDateTime endOfDay = LocalDateTimeUtil.endOfDay(localDateTime);
+```
diff --git a/docs/core/日期时间/日期时间工具-DateUtil.md b/docs/core/日期时间/日期时间工具-DateUtil.md
@@ -1,7 +1,5 @@
-日期时间工具-DateUtil
-===
-
 ## 由来
+
 考虑到Java本身对日期时间的支持有限，并且Date和Calendar对象的并存导致各种方法使用混乱和复杂，故使用此工具类做了封装。这其中的封装主要是日期和字符串之间的转换，以及提供对日期的定位（一个月前等等）。
 
 对于Date对象，为了便捷，使用了一个DateTime类来代替之，继承自Date对象，主要的便利在于，覆盖了toString()方法，返回yyyy-MM-dd HH:mm:ss形式的字符串，方便在输出时的调用（例如日志记录等），提供了众多便捷的方法对日期对象操作，关于DateTime会在相关章节介绍。
@@ -44,7 +42,7 @@ String dateStr = "2017-03-01";
 Date date = DateUtil.parse(dateStr, "yyyy-MM-dd");
 ```
 
-#### 格式化日期输出
+### 格式化日期输出
 
 ```java
 String dateStr = "2017-03-01";
@@ -63,7 +61,8 @@ String formatDateTime = DateUtil.formatDateTime(date);
 String formatTime = DateUtil.formatTime(date);
 ```
 
-#### 获取Date对象的某个部分
+### 获取Date对象的某个部分
+
 ```
 Date date = DateUtil.date();
 //获得年的部分
@@ -75,7 +74,8 @@ DateUtil.monthEnum(date);
 //.....
 ```
 
-#### 开始和结束时间
+### 开始和结束时间
+
 有的时候我们需要获得每天的开始时间、结束时间，每月的开始和结束时间等等，DateUtil也提供了相关方法：
 
 ```java
@@ -89,7 +89,8 @@ Date beginOfDay = DateUtil.beginOfDay(date);
 Date endOfDay = DateUtil.endOfDay(date);
 ```
 
-#### 日期时间偏移
+### 日期时间偏移
+
 日期或时间的偏移指针对某个日期增加或减少分、小时、天等等，达到日期变更的目的。Hutool也针对其做了大量封装
 
 ```java
@@ -122,7 +123,8 @@ DateUtil.lastMonth()
 DateUtil.nextMonth()
 ```
 
-#### 日期时间差
+### 日期时间差
+
 有时候我们需要计算两个日期之间的时间差（相差天数、相差小时数等等），Hutool将此类方法封装为between方法：
 
 ```java
@@ -136,7 +138,7 @@ Date date2 = DateUtil.parse(dateStr2);
 long betweenDay = DateUtil.between(date1, date2, DateUnit.DAY);
 ```
 
-#### 格式化时间差
+### 格式化时间差
 有时候我们希望看到易读的时间差，比如XX天XX小时XX分XX秒，此时使用`DateUtil.formatBetween`方法：
 
 ```java
@@ -146,7 +148,8 @@ String formatBetween = DateUtil.formatBetween(between, Level.MINUTE);
 Console.log(formatBetween);
 ```
 
-#### 计时器
+### 计时器
+
 计时器用于计算某段代码或过程花费的时间
 
 ```java
@@ -161,7 +164,18 @@ timer.intervalRestart();//返回花费时间，并重置开始时间
 timer.intervalMinute();//花费分钟数
 ```
 
-#### 其它
+### 星座和属相
+
+```java
+// "摩羯座"
+String zodiac = DateUtil.getZodiac(Month.JANUARY.getValue(), 19);
+
+// "狗"
+String chineseZodiac = DateUtil.getChineseZodiac(1994);
+```
+
+### 其它
+
 ```java
 //年龄
 DateUtil.ageOfNow("1990-01-30");

diff --git a/docs/extra/cglib/Cglib工具-CglibUtil.md b/docs/extra/cglib/Cglib工具-CglibUtil.md
@@ -0,0 +1,61 @@
+## 介绍
+
+CGLib (Code Generation Library) 是一个强大的,高性能,高质量的Code生成类库，通过此库可以完成动态代理、Bean拷贝等操作。
+
+Hutool在`5.4.1`之后加入对Cglib的封装——`CglibUtil`，用于解决Bean拷贝的性能问题。
+
+## 使用
+
+### 引入Cglib
+
+```xml
+<dependency>
+	<groupId>cglib</groupId>
+	<artifactId>cglib</artifactId>
+	<version>${cglib.version}</version>
+	<scope>compile</scope>
+</dependency>
+```
+
+### 使用
+
+1. Bean拷贝
+
+首先我们定义两个Bean：
+```java
+@Data
+public class SampleBean {
+	private String value;
+}
+@Data
+public class OtherSampleBean {
+	private String value;
+}
+```
+
+> @Data是Lombok的注解，请自行补充get和set方法，或者引入Lombok依赖
+
+```java
+SampleBean bean = new SampleBean();
+bean.setValue("Hello world");
+
+OtherSampleBean otherBean = new OtherSampleBean();
+
+CglibUtil.copy(bean, otherBean);
+
+// 值为"Hello world"
+otherBean.getValue();
+```
+
+当然，目标对象也可以省略，你可以传入一个class，让Hutool自动帮你实例化它：
+
+```
+OtherSampleBean otherBean2 = CglibUtil.copy(bean, OtherSampleBean.class);
+
+// 值为"Hello world"
+otherBean.getValue();
+```
+
+## 关于性能
+
+Cglib的性能是目前公认最好的，其时间主要耗费在`BeanCopier`创建上，因此，Hutool根据传入Class不同，缓存了`BeanCopier`对象，使性能达到最好。
diff --git a/docs/extra/拼音/拼音工具-PinyinUtil.md b/docs/extra/拼音/拼音工具-PinyinUtil.md
@@ -0,0 +1,68 @@
+## 介绍
+
+拼音工具类在旧版本的Hutool中在core包中，但是发现自己实现相关功能需要庞大的字典，放在core包中便是累赘。
+
+于是为了方便，Hutool封装了拼音的门面，用于兼容以下拼音库:
+
+1. TinyPinyin
+2. JPinyin
+3. Pinyin4j
+
+和其它门面模块类似，采用SPI方式识别所用的库。例如你想用Pinyin4j，只需引入jar，Hutool即可自动识别。
+
+## 使用
+
+### 引入库
+
+以下为Hutool支持的拼音库的pom坐标，你可以选择任意一个引入项目中，如果引入多个，Hutool会按照以上顺序选择第一个使用。
+
+```xml
+<dependency>
+	<groupId>io.github.biezhi</groupId>
+	<artifactId>TinyPinyin</artifactId>
+	<version>2.0.3.RELEASE</version>
+</dependency>
+```
+
+```xml
+<dependency>
+	<groupId>com.belerweb</groupId>
+	<artifactId>pinyin4j</artifactId>
+	<version>2.5.1</version>
+</dependency>
+```
+
+```xml
+<dependency>
+	<groupId>com.github.stuxuhai</groupId>
+	<artifactId>jpinyin</artifactId>
+	<version>1.1.8</version>
+</dependency>
+```
+
+### 使用
+
+1. 获取拼音
+
+```java
+// "ni hao"
+String pinyin = PinyinUtil.getPinyin("你好", " ");
+```
+
+这里定义的分隔符为空格，你也可以按照需求自定义分隔符，亦或者使用""无分隔符。
+
+2. 获取拼音首字母
+
+```java
+// "h, s, d, y, g"
+String result = PinyinUtil.getFirstLetter("H是第一个", ", ");
+```
+
+3. 自定义拼音库（拼音引擎）
+
+```java
+Pinyin4jEngine engine = new Pinyin4jEngine();
+
+// "ni hao h"
+String pinyin = engine.getPinyin("你好h", " ");
+```
diff --git a/docs/捐赠使用公开.md b/docs/捐赠使用公开.md
@@ -17,6 +17,7 @@
 |hutool.cn域名费用（3年）| ￥105  |
 
 --------------------------------------------------------------
+
 ## 2018年
 
 |         用途       |  金额  |
@@ -25,5 +26,11 @@
 |Hutool群VIP会员费用  | ￥228 |
 |作者偷吃辣条一包     | ￥2.5 |
 -------------------------------------------------------------
+## 2019年
+
+|         用途       |  金额  |
+|------------------- |-------|
+|Hutool群VIP会员费用  | ￥228 |
+-------------------------------------------------------------