Merge pull request #11 from mauritssilvis/update_java

Update to Java 21

.gitattributes

@@ -0,0 +1,4 @@
+# https://help.github.com/articles/dealing-with-line-endings/
+* text eol=lf
+
+*.bat text eol=crlf

CHANGELOG.md

@@ -2,9 +2,18 @@
 
 All notable changes to the [Types](https://github.com/mauritssilvis/types) project are documented in this file.
 
-The file format is based on [keep a changelog](https://keepachangelog.com/en/1.0.0/),
+The file format is based on [keep a changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [semantic versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2023-10-11
+
+### Changed
+
+- Improve the project documentation.
+- Update the Java version from 20 to 21.
+- Update the Gradle version from 8.3 to 8.4.
+- Update the refreshVersions version from 0.60.2 to 0.60.3.
+
 ## [0.1.0] - 2023-09-16
 
 ### Added

README.md

@@ -36,20 +36,20 @@ Currently, implementations of commonly used data types and structures are availa
 
 I specifically provide the following (partial) data type and structure implementations:
 
-| Data type or structure | Java                                                                            |
-|------------------------|---------------------------------------------------------------------------------|
-| String                 | [✅](java/src/main/java/nl/mauritssilvis/types/java/string)                      |
-| • Immutable string     | [✅](java/src/main/java/nl/mauritssilvis/types/java/string#11-immutable-strings) |
+| Data type or structure | Java                                                                             |
+|------------------------|----------------------------------------------------------------------------------|
+| String                 | [✅](java/src/main/java/nl/mauritssilvis/types/java/string)                       |
+| • Immutable string     | [✅](java/src/main/java/nl/mauritssilvis/types/java/string/#11-immutable-strings) |
 
 ## 3. Background
 
-More information on the data types and structures I focus on in this project is given in the following.
+Below, I give general information on the data types and structures I focus on in this project.
 
-### 3.1 String
+### 3.1 Strings
 
 Next to numeric types like integers and floating point numbers, strings arguably are one of the most commonly used data types in programming.
 Essentially, strings are arrays of characters.
-However, despite this seeming simplicity, strings can store everything from single words to names, email addresses, codes like passwords and even full texts.
+However, despite this seeming simplicity, strings can store anything from single words to names, email addresses, passwords and even full texts.
 
 In many programming languages, including Java, strings are represented by immutable objects.
 Immutable objects are objects that cannot be changed once they are created.
@@ -58,7 +58,7 @@ Since we then end up with more objects, immutability could be considered a disad
 However, consider using strings as keys for a hash map.
 If strings were mutable, you could change those keys by changing the used strings.
 The immutability of strings prevents such changes, thus preventing unexpected situations and potential bugs.
-Mutable and immutable strings, thus, both have their role.
+Mutable and immutable strings, thus, both have their advantages and disadvantages.
 
 ## License
 

java/README.md

@@ -4,17 +4,18 @@
 
 ## Introduction
 
-With this part of the [Types](https://github.com/mauritssilvis/types) project, I provide implementations of commonly used data types and structures in Java.
+With this part of the [Types](..) project, I provide implementations of commonly used data types and structures in Java.
 
-Below, I give an [overview](#overview) of the available implementations.
+Below, I give an [overview](#1-overview) of the available implementations.
 
-## Overview
+## 1. Overview
 
 Currently, (partial) Java implementations of the following data types and structures are available:
 
-- [String](src/main/java/nl/mauritssilvis/types/java/string)
-
-  - [Immutable string](src/main/java/nl/mauritssilvis/types/java/string#11-immutable-strings)
+| Data type or structure                                                                       |
+|----------------------------------------------------------------------------------------------|
+| [String](src/main/java/nl/mauritssilvis/types/java/string)                                   |
+| • [Immutable string](src/main/java/nl/mauritssilvis/types/java/string/#11-immutable-strings) |
 
 ## License
 

java/gradle/libs.versions.toml

@@ -2,9 +2,9 @@
 
 [versions]
 
-java-jdk = "20"
+java-jdk = "21"
 
-java-types = "0.1.0"
+java-types = "0.2.0"
 
 junit-jupiter = "5.10.0"
 

java/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,7 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-bin.zip
+# TODO: Select a Gradle version that officially supports running on Java 21
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

java/gradlew

@@ -145,15 +145,15 @@ if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
     case $MAX_FD in #(
       max*)
         # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
-        # shellcheck disable=SC3045
+        # shellcheck disable=SC2039,SC3045
         MAX_FD=$( ulimit -H -n ) ||
             warn "Could not query maximum file descriptor limit"
     esac
     case $MAX_FD in  #(
       '' | soft) :;; #(
       *)
         # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
-        # shellcheck disable=SC3045
+        # shellcheck disable=SC2039,SC3045
         ulimit -n "$MAX_FD" ||
             warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac
@@ -202,11 +202,11 @@ fi
 # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
 
-# Collect all arguments for the java command;
-#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
-#     shell script including quotes and variable substitutions, so put them in
-#     double quotes to make sure that they get re-expanded; and
-#   * put everything else in single quotes, so that it's not re-expanded.
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
 
 set -- \
         "-Dorg.gradle.appname=$APP_BASE_NAME" \

java/gradlew.bat

@@ -1,92 +1,92 @@
-@rem
-@rem Copyright 2015 the original author or authors.
-@rem
-@rem Licensed under the Apache License, Version 2.0 (the "License");
-@rem you may not use this file except in compliance with the License.
-@rem You may obtain a copy of the License at
-@rem
-@rem      https://www.apache.org/licenses/LICENSE-2.0
-@rem
-@rem Unless required by applicable law or agreed to in writing, software
-@rem distributed under the License is distributed on an "AS IS" BASIS,
-@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-@rem See the License for the specific language governing permissions and
-@rem limitations under the License.
-@rem
-
-@if "%DEBUG%"=="" @echo off
-@rem ##########################################################################
-@rem
-@rem  Gradle startup script for Windows
-@rem
-@rem ##########################################################################
-
-@rem Set local scope for the variables with windows NT shell
-if "%OS%"=="Windows_NT" setlocal
-
-set DIRNAME=%~dp0
-if "%DIRNAME%"=="" set DIRNAME=.
-@rem This is normally unused
-set APP_BASE_NAME=%~n0
-set APP_HOME=%DIRNAME%
-
-@rem Resolve any "." and ".." in APP_HOME to make it shorter.
-for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
-
-@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
-
-@rem Find java.exe
-if defined JAVA_HOME goto findJavaFromJavaHome
-
-set JAVA_EXE=java.exe
-%JAVA_EXE% -version >NUL 2>&1
-if %ERRORLEVEL% equ 0 goto execute
-
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
-
-goto fail
-
-:findJavaFromJavaHome
-set JAVA_HOME=%JAVA_HOME:"=%
-set JAVA_EXE=%JAVA_HOME%/bin/java.exe
-
-if exist "%JAVA_EXE%" goto execute
-
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
-
-goto fail
-
-:execute
-@rem Setup the command line
-
-set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
-
-
-@rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
-
-:end
-@rem End local scope for the variables with windows NT shell
-if %ERRORLEVEL% equ 0 goto mainEnd
-
-:fail
-rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
-rem the _cmd.exe /c_ return code!
-set EXIT_CODE=%ERRORLEVEL%
-if %EXIT_CODE% equ 0 set EXIT_CODE=1
-if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
-exit /b %EXIT_CODE%
-
-:mainEnd
-if "%OS%"=="Windows_NT" endlocal
-
-:omega
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo.
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo.
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

java/settings.gradle.kts

@@ -5,8 +5,7 @@
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.7.0"
-    id("de.fayard.refreshVersions") version "0.60.2"
+    id("de.fayard.refreshVersions") version "0.60.3"
 }
 
 rootProject.name = "java-types"
-

java/src/main/java/nl/mauritssilvis/types/java/string/README.md

@@ -4,11 +4,11 @@
 
 ## Introduction
 
-With this part of the [Types](https://github.com/mauritssilvis/types) > [Java](../../../../../../../..) project, I provide implementations of the string data type in Java.
+With this part of the [Java types](../../../../../../../..) project, I provide implementations of the string data type in Java.
 
 Below, I give an overview of the different [implementations](#1-implementations) I considered.
 
-General information about the string data type can be found in the [string section](https://github.com/mauritssilvis/types#31-string) of the [Types](https://github.com/mauritssilvis/types) readme.
+General information about the string data type can be found in the [Strings section](../../../../../../../../../#31-strings) of the [Types](../../../../../../../../..) readme.
 
 ## 1. Implementations
 
@@ -29,8 +29,9 @@ public interface ImmutableString {
     char[] toCharArray();
 }
 ```
+
 Objects of the above type know their length, allow random access to their characters and can be converted to character arrays.
-None of the supplied methods can change an object's contents.
+None of the methods should change (or allow for changes in) an object's contents.
 
 #### 1.1.1 An array of characters
 
@@ -43,6 +44,7 @@ package nl.mauritssilvis.types.java.string;
 // Import statements
 
 public class ArrayString implements ImmutableString {
+    // The underlying data structure: an array of characters
     private final char[] chars;
 
     // A no-argument constructor and constructors accepting