The BasePlus package [ver. 1.33.0]

## The BasePlus package [ver. 1.33.0]

- New macro [`%unzipArch()`](https://github.com/SASPAC/baseplus/blob/main/baseplus.md#unziparch-macro) added. The macro allows to extract ZIP archive file from SAS session and does not need `XCMD` (is OS independent).
- Documentation updated.

---

SHA256 digest for the latest version of `BasePlus`: F*6214654B4575DC8E4BA3CF032924862C2F69A03A6384872BAA9F774EDF6A8DDA

README.md

@@ -45,10 +45,14 @@ libname NEW "%workPath()/new";
 %put %translate(%str("A", "B", "C"),%str(%",),%str(%' ));
 
 %put %tranwrd(Miss Joan Smith,Miss,Ms.);
+
+%put %date() %time() %datetime();
+
+%put %monthShift(2023,1,-5);
 ```
 and more.
 
-SHA256 digest for the latest version of `BasePlus`: F*B91771D45C781B6806DBB44A3B491A0784D7698B9F3BBBE1A86EE5594834315F
+SHA256 digest for the latest version of `BasePlus`: F*6214654B4575DC8E4BA3CF032924862C2F69A03A6384872BAA9F774EDF6A8DDA
 
 [**Documentation for BasePlus**](./baseplus.md "Documentation for BasePlus")
 

baseplus.md

@@ -45,6 +45,7 @@
   * [`%RainCloudPlot()` macro](#raincloudplot-macro)
   * [`%zipLibrary()` macro](#ziplibrary-macro)
   * [`%unzipLibrary()` macro](#unziplibrary-macro)
+  * [`%unzipArch()` macro](#unzipatch-macro)
   * [`%LDSN()` macro](#ldsn-macro)
   * [`%LDsNm()` macro](#ldsnm-macro)
   * [`%LVarNm()` macro](#lvarnm-macro)
@@ -60,6 +61,11 @@
   * [`%filePath()` macro](#filepath-macro)
   * [`%libPath()` macro](#libpath-macro)
   * [`%workPath()` macro](#workpath-macro)
+  * [`%date()` macro](#date-macro)
+  * [`%today()` macro](#today-macro)
+  * [`%time()` macro](#time-macro)
+  * [`%datetime()` macro](#datetime-macro)
+  * [`%monthShift()` macro](#monthshift-macro)
   * [`%translate()` macro](#translate-macro)
   * [`%tranwrd()` macro](#tranwrd-macro)
   * [`%findDSwithVarVal()` macro](#finddswithvarval-macro)
@@ -73,7 +79,7 @@
   
 ---
 
-# The BasePlus package [ver. 1.30.0] <a name="baseplus-package"></a> ###############################################
+# The BasePlus package [ver. 1.33.0] <a name="baseplus-package"></a> ###############################################
 
 The **BasePlus** package implements useful
 functions and functionalities I miss in the BASE SAS.
@@ -81,6 +87,7 @@ functions and functionalities I miss in the BASE SAS.
 It is inspired by various people, e.g.
 - at the SAS-L discussion list
 - at the communities.sas.com (SASware Ballot Ideas)
+- at StackOverflow
 - at the Office...
 - etc.
 
@@ -96,8 +103,6 @@ Kudos to all who inspired me to generate this package:
 *Kurt Bremser*,
 *Leonid Batkhan*.
 
-Recording from the SAS Explore 2022 conference: [A BasePlus Package for SAS](https://communities.sas.com/t5/SAS-Explore-Presentations/A-BasePlus-Package-for-SAS/ta-p/838246 "A BasePlus Package for SAS") (September 27th-29th, 2022).
-
 ---
 
 ### BASIC EXAMPLES AND USECASES: ####################################################
@@ -334,80 +339,98 @@ data Times2_A3B4C5;
     %repList(work.A work.B work.C, times = 2, each = 3 4 5)
   ;
 run;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**EXAMPLE 23** Date and time one-liners:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%put %today() %date() %time() %datetime(); 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**EXAMPLE 24** Months shifting:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%put 
+  Past:    %monthShift(2023, 1, -1) 
+  Current: %monthShift(2023, 1    )
+  Future:  %monthShift(2023, 1, +1)
+;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ---
 
 Package contains: 
-1.   macro        bppipe
+1.  macro     bppipe                 
-2.   macro        deduplistc
+2.  macro     deduplistc             
-3.   macro        deduplistp
+3.  macro     deduplistp             
-4.   macro        deduplists
+4.  macro     deduplists             
-5.   macro        deduplistx
+5.  macro     deduplistx             
-6.   macro        dirsandfiles
+6.  macro     dirsandfiles           
-7.   macro        functionexists
+7.  macro     functionexists         
-8.   macro        getvars
+8.  macro     getvars                
-9.   macro        intslist
+9.  macro     intslist               
-10.  macro        ldsn
+10. macro     ldsn                   
-11.  macro        ldsnm
+11. macro     ldsnm                  
-12.  macro        lvarnm
+12. macro     lvarnm                 
-13.  macro        lvarnmlab
+13. macro     lvarnmlab              
-14.  macro        qdeduplistx
+14. macro     qdeduplistx            
-15.  macro        qgetvars
+15. macro     qgetvars               
-16.  macro        qzipevalf
+16. macro     qzipevalf              
-17.  macro        raincloudplot
+17. macro     raincloudplot          
-18.  macro        repeattxt
+18. macro     repeattxt              
-19.  macro        splitdsintoblocks
+19. macro     splitdsintoblocks      
-20.  macro        splitdsintoparts
+20. macro     splitdsintoparts       
-21.  macro        symdelglobal
+21. macro     symdelglobal           
-22.  macro        unziplibrary
+22. macro     unziparch              
-23.  macro        zipevalf
+23. macro     unziplibrary           
-24.  macro        ziplibrary
+24. macro     zipevalf               
-25.  format       bool
+25. macro     ziplibrary             
-26.  format       boolz
+26. format    bool                   
-27.  format       ceil
+27. format    boolz                  
-28.  format       floor
+28. format    ceil                   
-29.  format       int
+29. format    floor                  
-30.  functions    arrfill
+30. format    int                    
-31.  functions    arrfillc
+31. function  arrfill                
-32.  functions    arrmissfill
+32. function  arrfillc               
-33.  functions    arrmissfillc
+33. function  arrmissfill            
-34.  functions    arrmisstoleft
+34. function  arrmissfillc           
-35.  functions    arrmisstoleftc
+35. function  arrmisstoleft          
-36.  functions    arrmisstoright
+36. function  arrmisstoleftc         
-37.  functions    arrmisstorightc
+37. function  arrmisstoright         
-38.  functions    bracketsc
+38. function  arrmisstorightc        
-39.  functions    bracketsn
+39. function  bracketsc              
-40.  functions    catxfc
+40. function  bracketsn              
-41.  functions    catxfi
+41. function  catxfc                 
-42.  functions    catxfj
+42. function  catxfi                 
-43.  functions    catxfn
+43. function  catxfj                 
-44.  functions    deldataset
+44. function  catxfn                 
-45.  functions    semicolonc
+45. function  deldataset             
-46.  functions    semicolonn
+46. function  semicolonc             
-47.  format       brackets
+47. function  semicolonn             
-48.  format       semicolon
+48. format    brackets               
-49.  proto        qsortincbyprocproto
+49. format    semicolon              
-50.  functions    frommissingtonumberbs
+50. proto     qsortincbyprocproto    
-51.  functions    fromnumbertomissing
+51. function  frommissingtonumberbs  
-52.  functions    quicksort4notmiss
+52. function  fromnumbertomissing    
-53.  functions    quicksorthash
+53. function  quicksort4notmiss      
-54.  functions    quicksorthashsddv
+54. function  quicksorthash          
-55.  functions    quicksortlight
+55. function  quicksorthashsddv      
-56.  macro        filepath
+56. function  quicksortlight         
-57.  macro        finddswithvarval
+57. macro     date                   
-58.  macro        fmt
+58. macro     datetime               
-59.  macro        gettitle
+59. macro     filepath               
-60.  macro        infmt
+60. macro     finddswithvarval       
-61.  macro        letters
+61. macro     fmt                    
-62.  macro        libpath
+62. macro     gettitle               
-63.  macro        minclude
+63. macro     infmt                  
-64.  macro        replist
+64. macro     letters                
-65.  macro        translate
+65. macro     libpath                
-66.  macro        tranwrd
+66. macro     minclude               
-67.  macro        workpath
+67. macro     monthshift             
-
+68. macro     replist                
+69. macro     time                   
+70. macro     today                  
+71. macro     translate              
+72. macro     tranwrd                
+73. macro     workpath               
 
 
 
@@ -415,10 +438,10 @@ Package contains additional content, run:  %loadPackageAddCnt(BasePlus)  to load
 or look for the baseplus_AdditionalContent directory in the Packages fileref
 localization (only if additional content was deployed during the installation process).
 
-* SAS package generated by generatePackage, version 20230905 *
+* SAS package generated by generatePackage, version 20231107 *
 
 The SHA256 hash digest for package BasePlus: 
-`F*B91771D45C781B6806DBB44A3B491A0784D7698B9F3BBBE1A86EE5594834315F` 
+`F*6214654B4575DC8E4BA3CF032924862C2F69A03A6384872BAA9F774EDF6A8DDA` 
 
 ---
 # Content description ############################################################################################
@@ -3750,6 +3773,92 @@ run;
 
 ---
 
+## >>> `%unzipArch()` macro: <<< <a name="unziparch-macro"></a> #######################  
+
+The unzipArch() macro allows to unzip content of a ZIP archive. 
+Macro is OS independent, the `XCMD` option is not required.
+
+The `dlCreateDir` option is used under the hood.
+
+Content of unzipped archive can be listed in the log.
+
+Source files can be deleted after decompression.
+Errors of decompression and are reported. If any occur
+the deletion is suspended.
+
+See examples below for the details.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%unzipArch(
+    archName
+  <,path=>
+  <,target=>
+  <,list=> 
+  <,clean=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `archName`      - *Required*, name of the ZIP archive to be extracted.
+                     Name should be full, i.e., with the extension.
+
+* `path=`          - *Optional*, a path pointing to zipped file location.
+                     The path should be provided unquoted.
+                     Default value is `WORK` location.
+
+* `target=`        - *Optional*, a path pointing to target location where
+                     files will be extracted.
+                     The path should be provided unquoted.
+                     Default value is `WORK` location.
+
+* `list = 0`       - *Optional*, default value is `0`,
+                     indicates if zip content should be listed in the log. 
+                     `1` means *yes*, `0` means *no*. 
+
+* `clean = 0`      - *Optional*, default value is `0`,
+                     indicates if zip file should be deleted after unzipping. 
+                     `1` means *yes*, `0` means *no*. 
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Unzip compressed archive. Example requires the `basePlus` package.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+
+filename arch ZIP "%workPath()/testArch.zip";
+
+data _null_;
+  file arch(abc/test1.txt);
+  put "text for test file 1";
+data _null_;
+  file arch(abc/subdir/test2.txt);
+  put "text for test file 2";
+data _null_;
+  file arch(abc/subdir/test3.txt);
+  put "text for test file 3";
+run;
+
+%unzipArch(
+  testArch.zip 
+, path = %workPath()
+, target = %workPath()
+, list=1
+);
+
+%unzipArch(
+  testArch.zip 
+, path = %workPath()
+, target = %workPath()
+, clean=1
+);
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ## >>> `%LDSN()` macro: <<< <a name="ldsn-macro"></a> #######################  
 
 The LDSN (Long DataSet Names) macro function 
@@ -4970,6 +5079,277 @@ The basic syntax is the following, the `<...>` means optional parameters:
 
 ---
 
+## >>> `%date()` macro: <<< <a name="date-macro"></a> #######################  
+
+The date() macro function is a "lazy typer" wrapping up `%sysfunc(date())`.
+
+See examples below for the details.
+
+The `%date()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%date()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+ No arguments.
+
+---
+
+ 
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Get value of `date()`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %date();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+ 
+## >>> `%today()` macro: <<< <a name="today-macro"></a> #######################  
+
+The today() macro function is a "lazy typer" wrapping up `%sysfunc(today())`.
+
+See examples below for the details.
+
+The `%today()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%today()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+ No arguments.
+
+---
+
+ 
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Get value of `today()`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %today();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+ 
+## >>> `%time()` macro: <<< <a name="time-macro"></a> #######################  
+
+The time() macro function is a "lazy typer" wrapping up `%sysfunc(time())`.
+
+See examples below for the details.
+
+The `%time()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%time()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+ No arguments.
+
+---
+
+ 
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Get value of `time()`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %time();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+ 
+## >>> `%datetime()` macro: <<< <a name="datetime-macro"></a> #######################  
+
+The datetime() macro function is a "lazy typer" wrapping up `%sysfunc(datetime())`.
+
+See examples below for the details.
+
+The `%datetime()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%datetime()
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+ No arguments.
+
+---
+
+ 
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Get value of `datetime()`:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %datetime();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+## >>> `%monthShift()` macro: <<< <a name="monthshift-macro"></a> #######################  
+
+The monthShift() macro is a utility macro 
+which allows to shift "year-month" period by 
+a given number of "periods" (months).
+
+The result is in the `YYYYMM` format but can be altered.
+
+See examples below for the details.
+
+The `%monthShift()` macro executes like a pure macro code.
+
+### SYNTAX: ###################################################################
+
+The basic syntax is the following, the `<...>` means optional parameters:
+~~~~~~~~~~~~~~~~~~~~~~~sas
+%monthShift(
+  < Y>
+  <,M>
+  <,shift>
+  <,ofmt=>
+)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Arguments description**:
+
+1. `Y`           - *Optional*, a year from which counting starts.
+                   If null the value is set to *system year*.
+
+2. `M`           - *Optional*, a month from which counting starts.
+                   If null the value is set to `1`. Can be a number 
+                   (`1` to `12`) or a name (`June`, `OCTOBER`) or 
+                   a three letters short (`JAN`, `apr`).
+
+3. `shift`       - *Optional*, number of periods to shift.
+                   If null the value is set to `0`.
+                   Positive value shifts to the "future",
+                   negative value shifts to the "past",
+                   Can be an expression (e.g. `1+2*3`, see examples).
+
+* `ofmt=YYMMn6.` - *Optional*, it is a format name used to 
+                   display the result. Default value is `YYMMn6.`
+                   See examples.
+
+---
+
+### EXAMPLES AND USECASES: ####################################################
+
+**EXAMPLE 1.** Shift one up and one down:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+%put 
+  Past:    %monthShift(2023, 1, -1) 
+  Current: %monthShift(2023, 1    )
+  Future:  %monthShift(2023, 1, +1)
+;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 2.** Shift by expression:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %let n = 2;
+  %put 
+    %monthShift(2023, 1, +1 + &n.*3)
+  ;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 3.** Shift with default values:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put %monthShift();
+  %put %monthShift(2023);
+  %put %monthShift(2023,Jan);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 4.** Shift with months names:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put 
+    %monthShift(2023,Jan,-1)
+    %monthShift(2023,Feb,-2)
+    %monthShift(2023,Mar,-3)
+    %monthShift(2023,Apr,-4)
+    %monthShift(2023,May,-5)
+    %monthShift(2023,Jun,-6)
+    %monthShift(2023,Jul,-7)
+    %monthShift(2023,Aug,-8)
+    %monthShift(2023,Sep,-9)
+    %monthShift(2023,Oct,-10)
+    %monthShift(2023,Nov,-11)
+    %monthShift(2023,Dec,-12)
+  ;
+
+  %put 
+    %monthShift(2023,January,12)
+    %monthShift(2023,February,11)
+    %monthShift(2023,March,10)
+    %monthShift(2023,April,9)
+    %monthShift(2023,May,8)
+    %monthShift(2023,June,7)
+    %monthShift(2023,July,6)
+    %monthShift(2023,August,5)
+    %monthShift(2023,September,4)
+    %monthShift(2023,October,3)
+    %monthShift(2023,November,2)
+    %monthShift(2023,December,1)
+  ;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 5.** Play with formatting:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  %put
+    %monthShift(2023, 1, +1                )
+    %monthShift(2023, 1, +1, ofmt=yymm7. )
+    %monthShift(2023, 1, +1, ofmt=yymmd7.)
+    %monthShift(2023, 1, +1, ofmt=yymms7.)
+  ;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+**EXAMPLE 6.** Read monthly data with `noDSNFERR` option:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~sas
+  data
+    A202210 A202211 A202212
+    A202301 A202302 A202303
+    A202304 A202305 A202306
+    A202307 A202308 A202309
+  ;
+    set sashelp.class;
+  run;
+
+
+  options noDSNFERR; 
+  data ALL;
+    set 
+      A%monthShift(2023, 9, -12)  - A%monthShift(2023, 9)
+    ;
+  run;
+  options DSNFERR;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+---
+
+
 ## >>> `%translate()` macro: <<< <a name="translate-macro"></a> #######################  
 
 The translate() macro function allows to replace bytes with bytes in text string.