You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2022/09/22 02:15:22 UTC
[groovy] branch GROOVY_4_0_X updated: add some doco on arrays into the GDK section
This is an automated email from the ASF dual-hosted git repository.
paulk pushed a commit to branch GROOVY_4_0_X
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/GROOVY_4_0_X by this push:
new 5c1ef735fb add some doco on arrays into the GDK section
5c1ef735fb is described below
commit 5c1ef735fb2572945af2c900d935e9ef8726ea39
Author: Paul King <pa...@asert.com.au>
AuthorDate: Thu Sep 22 11:27:51 2022 +1000
add some doco on arrays into the GDK section
---
src/spec/doc/_working-with-arrays.adoc | 65 +++++++++++++++++++
src/spec/doc/core-gdk.adoc | 2 +
src/spec/test/gdk/WorkingWithArraysTest.groovy | 87 ++++++++++++++++++++++++++
3 files changed, 154 insertions(+)
diff --git a/src/spec/doc/_working-with-arrays.adoc b/src/spec/doc/_working-with-arrays.adoc
new file mode 100644
index 0000000000..44bf36b656
--- /dev/null
+++ b/src/spec/doc/_working-with-arrays.adoc
@@ -0,0 +1,65 @@
+//////////////////////////////////////////
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+//////////////////////////////////////////
+
+= Working with arrays
+:gdk: http://www.groovy-lang.org/gdk.html[Groovy development kit]
+
+Groovy provides array support based on Java arrays with several extensions found in the {gdk}. The overall
+intention is that whether you are using an array or a collection, the code for working with the aggregate remains the same.
+
+[[Arrays]]
+== Arrays
+
+=== Array literals
+
+You can create arrays as follows. Notice that `[]` is also used as the empty array
+expression when given an explicit array type.
+
+[source,groovy]
+-------------------------------------
+include::../test/gdk/WorkingWithArraysTest.groovy[tags=array_literals,indent=0]
+-------------------------------------
+
+=== Iterating on a list
+
+Iterating on elements of a list is usually done calling the `each` and `eachWithIndex` methods, which execute code on each
+item of a list:
+
+[source,groovy]
+----------------------------------------------------------------------------
+include::../test/gdk/WorkingWithArraysTest.groovy[tags=array_each,indent=0]
+----------------------------------------------------------------------------
+
+=== Other useful methods
+
+There are numerous other GDK methods for working with arrays.
+Just be a little careful to read the documentation.
+For collections, there are some mutating methods which alter
+the original collection and others which produce new collections,
+leaving the original untouched.
+Since arrays are of a fixed size, we wouldn't expect mutating
+methods which altered an array's size. Often instead, such methods return
+collections. Here are some interesting array GDK methods:
+
+[source,groovy]
+----------------------------------------------------------------------------
+include::../test/gdk/WorkingWithArraysTest.groovy[tags=array_gdk,indent=0]
+----------------------------------------------------------------------------
diff --git a/src/spec/doc/core-gdk.adoc b/src/spec/doc/core-gdk.adoc
index 95a1a98340..0a48c997b2 100644
--- a/src/spec/doc/core-gdk.adoc
+++ b/src/spec/doc/core-gdk.adoc
@@ -26,6 +26,8 @@ include::_working-with-io.adoc[leveloffset=+1]
include::_working-with-collections.adoc[leveloffset=+1]
+include::_working-with-arrays.adoc[leveloffset=+1]
+
include::../../../subprojects/groovy-dateutil/src/spec/doc/_working-with-dateutil-types.adoc[leveloffset=+1]
include::../../../subprojects/groovy-datetime/src/spec/doc/_working-with-datetime-types.adoc[leveloffset=+1]
diff --git a/src/spec/test/gdk/WorkingWithArraysTest.groovy b/src/spec/test/gdk/WorkingWithArraysTest.groovy
new file mode 100644
index 0000000000..9c0602c238
--- /dev/null
+++ b/src/spec/test/gdk/WorkingWithArraysTest.groovy
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package gdk
+
+import groovy.test.GroovyTestCase
+
+class WorkingWithArraysTest extends GroovyTestCase {
+ void testArrayLiterals() {
+ // tag::array_literals[]
+ Integer[] nums = [5, 6, 7, 8]
+ assert nums[1] == 6
+ assert nums.getAt(2) == 7 // alternative syntax
+ assert nums[-1] == 8 // negative indices
+ assert nums instanceof Integer[]
+
+ int[] primes = [2, 3, 5, 7] // primitives
+ assert primes instanceof int[]
+
+ def evens = new int[]{2, 4, 6} // alt syntax 1
+ assert evens instanceof int[]
+
+ def odds = [1, 3, 5] as int[] // alt syntax 2
+ assert odds instanceof int[]
+
+ // empty array examples
+ Integer[] emptyNums = []
+ assert emptyNums instanceof Integer[] && emptyNums.size() == 0
+
+ def emptyStrings = new String[]{} // alternative syntax 1
+ assert emptyStrings instanceof String[] && emptyStrings.size() == 0
+
+ var emptyObjects = new Object[0] // alternative syntax 2
+ assert emptyObjects instanceof Object[] && emptyObjects.size() == 0
+ // end::array_literals[]
+ }
+
+ void testArrayIteration() {
+ // tag::array_each[]
+ String[] vowels = ['a', 'e', 'i', 'o', 'u']
+ var result = ''
+ vowels.each {
+ result += it
+ }
+ assert result == 'aeiou'
+ result = ''
+ vowels.eachWithIndex { v, i ->
+ result += v * i // index starts from 0
+ }
+ assert result == 'eiiooouuuu'
+ // end::array_each[]
+ }
+
+ void testListCollect() {
+ // tag::array_gdk[]
+ int[] nums = [1, 2, 3]
+ def doubled = nums.collect { it * 2 }
+ assert doubled == [2, 4, 6] && doubled instanceof List
+ def tripled = nums*.multiply(3)
+ assert tripled == [3, 6, 9] && doubled instanceof List
+
+ assert nums.any{ it > 2 }
+ assert nums.every{ it < 4 }
+ assert nums.average() == 2
+ assert nums.min() == 1
+ assert nums.max() == 3
+ assert nums.sum() == 6
+ assert nums.indices == [0, 1, 2]
+ assert nums.swap(0, 2) == [3, 2, 1] as int[]
+ // end::array_gdk[]
+ }
+}