Confused about how to use mutating - arrays

Question

I have a simple struct called Card...
struct Card {
var order: Int? = -1
var data : [String: String]
var original : String?
And a collection object called Deck that looks like...
struct Deck {
var cards : [Card]
Deck has the reading and writing methods, which basically boils down to splitting up strings read in from a text file, and then pushing it bit by bit into the previous empty data. Here's an example...
mutating func parseGRCard(var c: Card) {
c.data["I1"] = c.original![2...4].trim()
c.data["I2"] = c.original![5...9].trim()
}
To read the file, I get each line, make a Card, and then call the parse methods on it...
let nc = Card(order: i, original: c)
parseGRCard(nc)
cards.append(nc)
When I step through this func, I see that mc's original has the expected data, the original line from the text file. I then watch parseGRCard read it and add the items to data, which now has two items. But when when it returns and nc is appended, data is empty.
I thought mutating was supposed to handle these things, but apparently I'm missing something fundamental here.

Answer 1

I changed your code a bit to make it compile and make it more illustrative.
append is mutating because it mutates cards.
It's parameter c is an inout parameter so that the passed Card is passed back after the function. Since Structs are value types and not reference types a new copy is actually passed to the function. This behaviour has nothing to do with the function being a mutating function.
struct Card {
var placeInDeck: Int = 0
}
struct Deck {
var cards : [Card] = []
mutating func append(inout c: Card) {
c.placeInDeck = cards.count
cards.append(c)
}
}
var cardZero = Card()
var cardOne = Card()
var deck = Deck()
deck.append(&cardZero)
deck.append(&cardOne)
cardZero.placeInDeck // 0
cardOne.placeInDeck // 1
In this case the function is not mutating because no properties from Deck are altered. The c parameter is a variable which just makes it mutable inside the scope from the function. Beware, this will be removed from Swift. When the function ends, this mutable copy of Card will not update it's original instance outside the scope of the function. The updated Card will not persist.
struct Card {
var placeInDeck: Int = 0
}
struct Deck {
var cards : [Card] = []
func updateCount(var c: Card) {
c.placeInDeck = 1
}
}
var cardZero = Card()
var cardOne = Card()
var deck = Deck()
deck.updateCount(cardZero)
deck.updateCount(cardOne)
cardZero.placeInDeck // 0
cardOne.placeInDeck // 0

Answer 2

From Apple's documentation methods, we can read the following regarding the mutable keyword:
However, if you need to modify the properties of your structure or
enumeration within a particular method, you can opt in to mutating
behavior for that method. The method can then mutate (that is, change)
its properties from within the method, and any changes that it makes
are written back to the original structure when the method ends.
I agree that it is could be possible to interpret the bold-marked part as as "the properties of the method, i.e., it's parameters?". From your example above, it would seem as if you have done this interpretation.
But the mutable keyword only tells us that the associated function is allowed to change (mutate) variable member values of the struct (in this case) that owns the method.
struct SingleIntegerValueStruct1 {
var myInt = 1
func LetsTryToMutateTheInteger () {
myInt += 1 // compile time error; myInt immutable
}
}
Whereas if we use the mutating keyword
struct SingleIntegerValueStruct {
var myInt = 0
mutating func LetsTryToMutateTheInteger () {
myInt += 1 // ok, mutating function
}
}
var a = SingleIntegerValueStruct(myInt: 1)
print("\(a.myInt)") // 1
a.LetsTryToMutateTheInteger()
print("\(a.myInt)") // 2
However, a struct type is and will always be a value type. So when when a struct type is passed to any function, the function will not be able to mutate the caller parameter, as it is only given a copy of it.
let nc = Card(order: i, original: c)
parseGRCard(nc) // passes _copy_ of struct typ nc to parseGRCard
cards.append(nc) // nc in this scope is stil unchanged
For wanting to use a "stand-alone" function that could mutate its input parameter, where the input is a struct, you could, as discussed in the comments, us the inout keyword on the function parameter.
We extend our example from above to include such a case:
struct SingleIntegerValueStruct {
var myInt = 0
mutating func LetsTryToMutateTheInteger () {
myInt += 1 // ok, mutating function
}
}
// "b" here is a _copy_ of "a" (in parameter), and the function
// thereafter returns a _copy_ of "b" (with state of "b" as its
// final state in the function)
func standAloneInOutFunction(inout b: SingleIntegerValueStruct) {
b.LetsTryToMutateTheInteger()
}
var a = SingleIntegerValueStruct(myInt: 1)
print("\(a.myInt)") // 1
a.LetsTryToMutateTheInteger()
print("\(a.myInt)") // 2
standAloneInOutFunction(&a)
// value copy a->b, modify(b), value copy back b->a
print("\(a.myInt)") // 3
Note however that the inout keyword does not mean that we pass by reference (as for class instances), but we simply send a value copy in and takes another value copy back, that we finally assigns to the original value type calling parameter (a).
From the Apple documentation on this keyword:
... An in-out parameter has a value that is passed in to the function,
is modified by the function, and is passed back out of the function to
replace the original value.